Files
stack/packages/plugins/src/starter-pack.mjs
T
jason.woltje 4a9c7a931c feat(organization): triage is system-only, no organization gains it (#1873, lane triage-fence)
One list, SYSTEM_ONLY in vocabulary.mjs, names triage; every path by which an
organization could gain one refuses with the one code template-system-only:
hire prepare at org, project and root level and a change onto it (hire.raise,
hire.start.console, decision.raise naming role.hire or role.change); the hire
and definitions template lists omit it; definition import; a definition copied
from it; organization roles, root agents and project agents; a pack record
pinning it; a starter pack defining it, so pack preview and apply refuse an
installed pack that names it; instances.set add and change for the human and
the tester, and the instances add list omits it. The broker passes the code
through and the webui tables map it. The template itself still loads and
validates. Red-first tests in organization and bus system-only.test.mjs; the
channel-proof hash of webui bus.mjs and the broker import pin are updated.
2026-11-16 11:38:17 -06:00

486 lines
27 KiB
JavaScript

// Starter packs, slice SP1 (#1873): the pack kind's checker and its three readers. Design:
// starter-packs-design section 2 and SP1 in section 8.
//
// A pack is a declarative document that lists definitions, hires, a board style, workflows and
// skills to copy into an organization or a project. It grants nothing and never stays switched on.
// Three sources, each with the origin its reader sets (a closed set, never a field the document
// supplies):
// shipped a core module packages/plugins/starter-pack/<name>/index.mjs, through the loader;
// installed a PL1 hash-pinned plug-in of kind starter-pack, through the same loader;
// saved <configDir>/templates/<account>/<name>.json, read as data, never imported.
// Origin `saved` relaxes exactly two rules: it may carry `packs`, and a definition may have no
// `from`. Every other check runs for every origin.
//
// A refusal names a position (a key, an index) and names that already passed a strict pattern,
// never a value from the document and never a host path.
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
import { dirname, isAbsolute, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { types } from "node:util";
import { ENTRY_KEYS, checkDefinition, readTemplate } from "../../organization/src/definitions.mjs";
import { parseJsonFileText } from "../../organization/src/util.mjs";
import { ID_PATTERN, NETWORKS, SYSTEM_ONLY_REFUSAL, systemOnly } from "../../organization/src/vocabulary.mjs";
import { NAME, PluginError } from "./kinds.mjs";
import { hasModule, loadInstalled } from "./loader.mjs";
export const KIND = "starter-pack";
export const PACK_VERSION = 1;
export const ORIGINS = Object.freeze(["shipped", "installed", "saved"]);
// The task tracker's five states. The same list as STORE_STATES in packages/bus/src/broker.mjs;
// plugins does not import the bus, so the test pins the two together.
export const STORE_STATES = Object.freeze(["todo", "in-progress", "in-review", "blocked", "done"]);
export const LAYOUTS = Object.freeze(["kanban", "list"]);
export const HUMAN_STEP = "human";
export const PACK_BOUNDS = Object.freeze({
hires: 8, reason: 500, label: 64, description: 1000, columnLabel: 32,
steps: 20, stepTitle: 120, stepRoles: 8, workflowDescription: 1000,
skills: 64, packs: 32, version: 64,
});
export const SAVED_MAX_BYTES = 256 * 1024;
const TOP_KEYS = Object.freeze(["packVersion", "id", "version", "label", "description", "scope", "definitions",
"hires", "board", "workflows", "skills"]);
const SAVED_KEYS = Object.freeze([...TOP_KEYS, "packs"]);
const SCOPES = Object.freeze(["org", "project"]);
const REF_KEYS = Object.freeze(["template", "sha256"]);
// A pack definition is a T1 entry without rev; apply sets rev 1.
const PACK_ENTRY_KEYS = Object.freeze(ENTRY_KEYS.filter((key) => key !== "rev"));
const HIRE_KEYS = Object.freeze(["name", "definition", "reason"]);
const BOARD_KEYS = Object.freeze(["columns", "layout"]);
const COLUMN_KEYS = Object.freeze(["state", "label"]);
const WORKFLOW_KEYS = Object.freeze(["description", "steps"]);
const STEP_KEYS = Object.freeze(["id", "title", "roles", "state"]);
const PACKS_ENTRY_KEYS = Object.freeze(["id", "version"]);
const MESSAGING_KEYS = Object.freeze(["sendTo", "receiveFrom"]);
const HEX64 = /^[0-9a-f]{64}$/;
// Semantic Versioning 2.0.0, the pattern semver.org gives.
const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
// The shipped roles, as organization-service.mjs resolves them.
const ROLES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../../roles");
const fail = (code, message, name = null) => {
throw new PluginError(code, message, name);
};
const plain = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
&& [Object.prototype, null].includes(Object.getPrototypeOf(value));
const isSemver = (value) => typeof value === "string" && value.length <= PACK_BOUNDS.version && SEMVER.test(value);
// Non-blank, one line, no NUL, at most max characters.
const lineText = (value, max) => typeof value === "string" && value.trim().length > 0 && value.length <= max
&& !/[\r\n\0]/.test(value);
// ---- Narrowing ----
function credentialLines(credentials) {
const out = [];
for (const { service, scopes } of credentials ?? []) {
if (scopes === undefined) out.push([service, service]);
else if (Array.isArray(scopes)) for (const scope of scopes) out.push([service, scope]);
else for (const [group, verbs] of Object.entries(scopes)) for (const verb of verbs) out.push([service, `${group}.${verb}`]);
}
return out;
}
const listOf = (value) => (Array.isArray(value) ? value : []);
// Every line of `role` its template does not hold, as [{ field, value }], in the order
// checkComposition's step 7 reads them. A within-role action is held only within-role; a
// cross-role one either way. A template with no messaging key lets the role message anyone; a role
// with no messaging key against a template that has one is wider ("*"). `role` is a composition
// (checkDefinition's result, or a T1 role); `template` is a version 2 role document.
export function widerLines(role, template) {
const out = [];
const add = (field, value) => out.push({ field, value });
const within = listOf(template.authority?.withinRole);
const any = [...within, ...listOf(template.authority?.crossRole)];
listOf(role.authority?.withinRole).forEach((a) => { if (!within.includes(a)) add("authority.withinRole", a); });
listOf(role.authority?.crossRole).forEach((a) => { if (!any.includes(a)) add("authority.crossRole", a); });
const tools = listOf(template.tools);
listOf(role.tools).forEach((t) => { if (!tools.includes(t)) add("tools", t); });
const network = NETWORKS.indexOf(role.network);
if (network === -1 || network > NETWORKS.indexOf(template.network)) add("network", role.network);
const held = new Set(credentialLines(template.credentials).map(([s, v]) => `${s}\n${v}`));
for (const [service, value] of credentialLines(role.credentials)) {
if (!held.has(`${service}\n${value}`)) add(`credentials.${service}`, value);
}
const templateMessaging = template.messaging ?? null;
const roleMessaging = role.messaging ?? null;
if (templateMessaging) {
for (const key of MESSAGING_KEYS) {
if (roleMessaging === null) add(`messaging.${key}`, "*");
else listOf(roleMessaging[key]).forEach((t) => { if (!listOf(templateMessaging[key]).includes(t)) add(`messaging.${key}`, t); });
}
}
const skills = listOf(template.skills);
listOf(role.skills).forEach((s) => { if (!skills.includes(s)) add("skills", s); });
return out;
}
// True when every tool, action, skill, messaging target and credential request line of `role` is
// in `template`, and its network is no wider: "no grant above the templates".
export function narrowsTemplate(role, template) {
return widerLines(role, template).length === 0;
}
// ---- The checker ----
function keysOnly(object, allowed, where, id) {
Object.keys(object).forEach((key, i) => {
if (!allowed.includes(key)) fail("starter-pack-invalid", `${where} has an unknown key (key ${i + 1}; allowed: ${allowed.join(", ")})`, id);
});
}
function requireKeys(object, required, where, id) {
for (const key of required) {
if (!Object.hasOwn(object, key)) fail("starter-pack-invalid", `${where} requires "${key}"`, id);
}
}
// One template, read now: { role, sha256 } or null when the name is no usable version 2 template.
function templateOrNull(rolesDir, name) {
if (typeof name !== "string" || !ID_PATTERN.test(name)) return null;
try {
return readTemplate(rolesDir, name);
} catch (error) {
if (error?.name === "BusinessError") return null;
throw error;
}
}
function checkDefinitions(definitions, { origin, rolesDir, id }) {
if (!plain(definitions)) fail("starter-pack-invalid", "starter pack definitions must be a JSON object", id);
const templates = new Map();
const template = (name) => {
if (!templates.has(name)) templates.set(name, templateOrNull(rolesDir, name));
return templates.get(name);
};
Object.keys(definitions).forEach((name, i) => {
if (!ID_PATTERN.test(name)) fail("starter-pack-invalid", `starter pack definitions key ${i + 1} must be a definition name matching ${ID_PATTERN}`, id);
const at = `starter pack definitions.${name}`;
const entry = definitions[name];
if (!plain(entry)) fail("starter-pack-invalid", `${at} must be a JSON object`, id);
// #1873 triage-fence: a pack never carries a system-only template, as a reference or as a from.
const named = entry.template ?? (plain(entry.from) ? entry.from.template : undefined);
if (systemOnly(named)) fail(SYSTEM_ONLY_REFUSAL, `${at} names template ${named}, which no organization may hold`, id);
const keys = Object.keys(entry);
if (keys.length === REF_KEYS.length && REF_KEYS.every((k) => keys.includes(k))) {
// A template reference: the whole template, pinned by its hash.
if (typeof entry.template !== "string" || !ID_PATTERN.test(entry.template)) fail("starter-pack-invalid", `${at}.template must be a template name matching ${ID_PATTERN}`, id);
if (typeof entry.sha256 !== "string" || !HEX64.test(entry.sha256)) fail("starter-pack-invalid", `${at}.sha256 must be 64 lowercase hex characters`, id);
const t = template(entry.template);
if (!t) fail("starter-pack-invalid", `${at} names template ${entry.template}, which is not a version 2 role`, id);
if (t.sha256 !== entry.sha256) fail("starter-pack-template-changed", `${at} pins template ${entry.template} at a hash it no longer has`, id);
return;
}
// A full entry in the T1 shape, without rev.
keysOnly(entry, PACK_ENTRY_KEYS, at, id);
let composition;
try {
({ composition } = checkDefinition(name, { ...entry, rev: 1 }, { where: "starter pack definitions" }));
} catch (error) {
// definitions.mjs and composition.mjs quote only names that passed a strict pattern.
if (error?.name === "BusinessError") fail("starter-pack-invalid", error.message, id);
throw error;
}
if (entry.from === undefined) {
if (origin !== "saved") fail("starter-pack-invalid", `${at} has no "from"; only a saved template may carry a role that copies no template`, id);
return;
}
const t = template(entry.from.template);
if (!t) fail("starter-pack-invalid", `${at}.from names template ${entry.from.template}, which is not a version 2 role`, id);
if (t.sha256 !== entry.from.sha256) fail("starter-pack-template-changed", `${at}.from pins template ${entry.from.template} at a hash it no longer has`, id);
const wider = widerLines(composition, t.role);
if (wider.length) {
const fields = [...new Set(wider.map((l) => l.field))].join(", ");
fail("starter-pack-invalid", `${at}.role is wider than template ${entry.from.template} (${fields})`, id);
}
});
}
function checkHires(hires, definitions, id) {
if (!Array.isArray(hires)) fail("starter-pack-invalid", "starter pack hires must be an array", id);
if (hires.length > PACK_BOUNDS.hires) fail("starter-pack-invalid", `starter pack hires must hold at most ${PACK_BOUNDS.hires} entries`, id);
const names = new Set();
hires.forEach((hire, i) => {
const at = `starter pack hires[${i}]`;
if (!plain(hire)) fail("starter-pack-invalid", `${at} must be a JSON object`, id);
// No level and no route: a hire is org-level in an org pack, project-level in a project pack,
// never root, and the raiser supplies the route.
keysOnly(hire, HIRE_KEYS, at, id);
requireKeys(hire, HIRE_KEYS, at, id);
if (typeof hire.name !== "string" || !ID_PATTERN.test(hire.name)) fail("starter-pack-invalid", `${at}.name must match ${ID_PATTERN}`, id);
if (names.has(hire.name)) fail("starter-pack-invalid", `${at}.name repeats an earlier hire`, id);
names.add(hire.name);
if (typeof hire.definition !== "string" || !Object.hasOwn(definitions, hire.definition)) {
fail("starter-pack-invalid", `${at}.definition must name a definition in this pack`, id);
}
if (typeof hire.reason !== "string" || hire.reason.trim().length === 0 || hire.reason.length > PACK_BOUNDS.reason || hire.reason.includes("\0")) {
fail("starter-pack-invalid", `${at}.reason must be a non-blank string of at most ${PACK_BOUNDS.reason} characters`, id);
}
});
}
function checkBoard(board, id) {
if (!plain(board)) fail("starter-pack-invalid", "starter pack board must be a JSON object", id);
keysOnly(board, BOARD_KEYS, "starter pack board", id);
requireKeys(board, BOARD_KEYS, "starter pack board", id);
if (!LAYOUTS.includes(board.layout)) fail("starter-pack-invalid", `starter pack board.layout must be one of ${LAYOUTS.join(", ")}`, id);
const columns = board.columns;
if (!Array.isArray(columns) || columns.length !== STORE_STATES.length) {
fail("starter-pack-invalid", `starter pack board.columns must hold the ${STORE_STATES.length} task states, each once`, id);
}
const seen = new Set();
columns.forEach((column, i) => {
const at = `starter pack board.columns[${i}]`;
if (!plain(column)) fail("starter-pack-invalid", `${at} must be a JSON object`, id);
keysOnly(column, COLUMN_KEYS, at, id);
requireKeys(column, COLUMN_KEYS, at, id);
if (!STORE_STATES.includes(column.state)) fail("starter-pack-invalid", `${at}.state must be one of ${STORE_STATES.join(", ")}`, id);
if (seen.has(column.state)) fail("starter-pack-invalid", `${at}.state ${column.state} repeats an earlier column`, id);
seen.add(column.state);
if (!lineText(column.label, PACK_BOUNDS.columnLabel)) fail("starter-pack-invalid", `${at}.label must be one line of 1 to ${PACK_BOUNDS.columnLabel} characters`, id);
});
}
function checkWorkflows(workflows, definitions, { rolesDir, id }) {
if (!plain(workflows)) fail("starter-pack-invalid", "starter pack workflows must be a JSON object", id);
const templates = new Map();
const isTemplate = (name) => {
if (!templates.has(name)) templates.set(name, templateOrNull(rolesDir, name) !== null);
return templates.get(name);
};
Object.keys(workflows).forEach((name, i) => {
if (!NAME.test(name)) fail("starter-pack-invalid", `starter pack workflows key ${i + 1} must match ${NAME}`, id);
const at = `starter pack workflows.${name}`;
const workflow = workflows[name];
if (!plain(workflow)) fail("starter-pack-invalid", `${at} must be a JSON object`, id);
keysOnly(workflow, WORKFLOW_KEYS, at, id);
requireKeys(workflow, WORKFLOW_KEYS, at, id);
if (typeof workflow.description !== "string" || workflow.description.trim().length === 0
|| workflow.description.length > PACK_BOUNDS.workflowDescription || workflow.description.includes("\0")) {
fail("starter-pack-invalid", `${at}.description must be a non-blank string of at most ${PACK_BOUNDS.workflowDescription} characters`, id);
}
const steps = workflow.steps;
if (!Array.isArray(steps) || steps.length < 1 || steps.length > PACK_BOUNDS.steps) {
fail("starter-pack-invalid", `${at}.steps must hold 1 to ${PACK_BOUNDS.steps} steps`, id);
}
const ids = new Set();
steps.forEach((step, j) => {
const where = `${at}.steps[${j}]`;
if (!plain(step)) fail("starter-pack-invalid", `${where} must be a JSON object`, id);
keysOnly(step, STEP_KEYS, where, id);
requireKeys(step, STEP_KEYS, where, id);
if (typeof step.id !== "string" || !NAME.test(step.id)) fail("starter-pack-invalid", `${where}.id must match ${NAME}`, id);
if (ids.has(step.id)) fail("starter-pack-invalid", `${where}.id repeats an earlier step`, id);
ids.add(step.id);
if (!lineText(step.title, PACK_BOUNDS.stepTitle)) fail("starter-pack-invalid", `${where}.title must be one line of 1 to ${PACK_BOUNDS.stepTitle} characters`, id);
if (!STORE_STATES.includes(step.state)) fail("starter-pack-invalid", `${where}.state must be one of ${STORE_STATES.join(", ")}`, id);
const roles = step.roles;
if (!Array.isArray(roles) || roles.length < 1 || roles.length > PACK_BOUNDS.stepRoles) {
fail("starter-pack-invalid", `${where}.roles must hold 1 to ${PACK_BOUNDS.stepRoles} names`, id);
}
const seen = new Set();
roles.forEach((role, k) => {
const ok = typeof role === "string"
&& (role === HUMAN_STEP || Object.hasOwn(definitions, role) || isTemplate(role));
if (!ok) fail("starter-pack-invalid", `${where}.roles[${k}] must be a definition in this pack, a version 2 template or "${HUMAN_STEP}"`, id);
if (seen.has(role)) fail("starter-pack-invalid", `${where}.roles[${k}] repeats an earlier name`, id);
seen.add(role);
});
});
});
}
function checkNameList(value, where, max, id) {
if (!Array.isArray(value)) fail("starter-pack-invalid", `${where} must be an array`, id);
if (value.length > max) fail("starter-pack-invalid", `${where} must hold at most ${max} entries`, id);
const seen = new Set();
value.forEach((name, i) => {
if (typeof name !== "string" || !NAME.test(name)) fail("starter-pack-invalid", `${where}[${i}] must match ${NAME}`, id);
if (seen.has(name)) fail("starter-pack-invalid", `${where}[${i}] repeats an earlier entry`, id);
seen.add(name);
});
}
function checkPacksList(packs, id) {
if (!Array.isArray(packs)) fail("starter-pack-invalid", "starter pack packs must be an array", id);
if (packs.length > PACK_BOUNDS.packs) fail("starter-pack-invalid", `starter pack packs must hold at most ${PACK_BOUNDS.packs} entries`, id);
packs.forEach((entry, i) => {
const at = `starter pack packs[${i}]`;
if (!plain(entry)) fail("starter-pack-invalid", `${at} must be a JSON object`, id);
keysOnly(entry, PACKS_ENTRY_KEYS, at, id);
requireKeys(entry, PACKS_ENTRY_KEYS, at, id);
if (typeof entry.id !== "string" || !NAME.test(entry.id)) fail("starter-pack-invalid", `${at}.id must match ${NAME}`, id);
if (!isSemver(entry.version)) fail("starter-pack-invalid", `${at}.version must be a semantic version`, id);
});
}
// Checks one pack document for its origin and returns a checked copy; the input is not read again
// after the copy. options.rolesDir is the shipped roles directory (tests pass their own);
// options.name, for a module, is the module's name, which the pack's id must equal.
export function checkPack(doc, { origin, rolesDir = ROLES_DIR, name } = {}) {
if (!ORIGINS.includes(origin)) fail("starter-pack-invalid", `starter pack origin must be one of ${ORIGINS.join(", ")}`);
let pack;
try {
pack = JSON.parse(JSON.stringify(doc));
} catch {
fail("starter-pack-invalid", "starter pack must be a JSON document");
}
if (!plain(pack)) fail("starter-pack-invalid", "starter pack must be a JSON object");
const id = typeof pack.id === "string" && NAME.test(pack.id) ? pack.id : null;
keysOnly(pack, origin === "saved" ? SAVED_KEYS : TOP_KEYS, "starter pack", id);
requireKeys(pack, TOP_KEYS, "starter pack", id);
if (pack.packVersion !== PACK_VERSION) fail("starter-pack-invalid", `starter pack packVersion must be ${PACK_VERSION}`, id);
if (id === null) fail("starter-pack-invalid", `starter pack id must match ${NAME}`);
if (name !== undefined && id !== name) fail("starter-pack-invalid", `starter pack id must equal its module name ${name}`, id);
if (!isSemver(pack.version)) fail("starter-pack-invalid", "starter pack version must be a semantic version", id);
if (!lineText(pack.label, PACK_BOUNDS.label)) fail("starter-pack-invalid", `starter pack label must be one line of 1 to ${PACK_BOUNDS.label} characters`, id);
if (!lineText(pack.description, PACK_BOUNDS.description)) fail("starter-pack-invalid", `starter pack description must be one line of 1 to ${PACK_BOUNDS.description} characters`, id);
if (!SCOPES.includes(pack.scope)) fail("starter-pack-invalid", `starter pack scope must be one of ${SCOPES.join(", ")}`, id);
checkDefinitions(pack.definitions, { origin, rolesDir, id });
checkHires(pack.hires, pack.definitions, id);
checkBoard(pack.board, id);
checkWorkflows(pack.workflows, pack.definitions, { rolesDir, id });
checkNameList(pack.skills, "starter pack skills", PACK_BOUNDS.skills, id);
if (Object.hasOwn(pack, "packs")) checkPacksList(pack.packs, id);
return pack;
}
// ---- Shipped and installed packs ----
// Lists shipped and installed packs through the loader, each checked with the origin of where it
// came from. A refused core pack fails the listing, as system types do. A refused installed pack is
// omitted and logged. Returns { packs: [{ id, origin, pack }], refused }.
export async function installedStarterPacks({ dataRoot = null, rolesDir = ROLES_DIR, log = () => {} } = {}) {
const { modules, refused: loadRefused } = await loadInstalled(KIND, { dataRoot });
const refused = [];
const omit = (name, error) => {
const entry = { event: "starter-pack-refused", kind: KIND, name, code: error.code, message: error.message };
log(entry);
refused.push(entry);
};
for (const entry of loadRefused) {
// A refusal with no name, or under a core module's name, is the core tree: fail closed.
if (entry.name === null || hasModule(KIND, entry.name)) {
fail("starter-pack-invalid", "a shipped starter pack was refused", entry.name);
}
omit(entry.name, entry);
}
const packs = [];
for (const { name, module, installed } of modules) {
const origin = installed ? "installed" : "shipped";
try {
let doc;
try {
doc = module.starterPack();
} catch {
fail("starter-pack-invalid", `starter pack ${name} failed to describe itself`, name);
}
// A pack is returned, never awaited: a promise refuses below, and a later rejection of it
// must not reach the process as an unhandled one. Only a native promise is recognised, and
// the built-in then is used, so the module's own then or getter never runs here; any other
// object goes to checkPack, whose closed key sets refuse it.
if (types.isPromise(doc)) {
Promise.prototype.then.call(doc, undefined, () => {});
fail("starter-pack-invalid", `starter pack ${name} must return its document, not a promise`, name);
}
packs.push({ id: name, origin, pack: checkPack(doc, { origin, rolesDir, name }) });
} catch (error) {
if (!(error instanceof PluginError)) throw error;
if (origin === "shipped") throw error;
omit(name, error);
}
}
return { packs, refused };
}
// ---- Saved templates ----
function lstatOrNull(path) {
try {
return lstatSync(path);
} catch (error) {
if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
fail("starter-pack-invalid", "the saved template can't be read");
}
}
// A directory on the way to a saved template: a real directory owned by the instance's user that
// no group or other user can write. `private` also refuses group and other read and list, for the
// account's own directory, which the writer creates 0700.
function checkDirectory(path, uid, { private: closed = false } = {}) {
const st = lstatOrNull(path);
if (st === null) fail("starter-pack-not-found", "no saved template has that name");
if (st.isSymbolicLink() || !st.isDirectory()) fail("starter-pack-invalid", "the saved templates directory must be a real directory");
if (st.uid !== uid) fail("starter-pack-invalid", "the saved templates directory must belong to the instance's user");
if ((st.mode & 0o022) !== 0) fail("starter-pack-invalid", "the saved templates directory must not be writable by group or others");
if (closed && (st.mode & 0o077) !== 0) fail("starter-pack-invalid", "the account's saved templates directory must be mode 0700 or narrower");
}
// Reads <configDir>/templates/<account>/<name>.json as data and checks it with origin `saved`. The
// account is the calling owner's id (s.human), checked against ID_PATTERN; the name is checked
// against NAME. Both are checked before any path is built, so neither ".." nor "/" reaches the file
// system. The account directory must be mode 0700 or narrower. The file must be a regular file, not
// a symlink or a hard link, owned by the instance's user, mode 0600 or narrower, at most 256 KiB,
// checked before the read. Returns { name, origin: "saved", pack }.
export function readSavedTemplate({ configDir, account, name, rolesDir = ROLES_DIR, uid = process.getuid() } = {}) {
if (typeof account !== "string" || !ID_PATTERN.test(account)) fail("starter-pack-invalid", `the saved template account must match ${ID_PATTERN}`);
if (typeof name !== "string" || !NAME.test(name)) fail("starter-pack-invalid", `the saved template name must match ${NAME}`);
if (typeof configDir !== "string" || !isAbsolute(configDir)) fail("starter-pack-invalid", "the configuration directory must be an absolute path");
const templates = join(configDir, "templates");
const accountDir = join(templates, account);
checkDirectory(templates, uid);
checkDirectory(accountDir, uid, { private: true });
const file = join(accountDir, `${name}.json`);
const before = lstatOrNull(file);
if (before === null) fail("starter-pack-not-found", "no saved template has that name", name);
if (before.isSymbolicLink() || !before.isFile()) fail("starter-pack-invalid", "the saved template must be a regular file, not a symlink", name);
let fd;
try {
fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
} catch (error) {
if (error.code === "ENOENT") fail("starter-pack-not-found", "no saved template has that name", name);
if (error.code === "ELOOP") fail("starter-pack-invalid", "the saved template must be a regular file, not a symlink", name);
fail("starter-pack-invalid", "the saved template can't be read", name);
}
let bytes;
try {
const st = fstatSync(fd);
if (!st.isFile() || st.dev !== before.dev || st.ino !== before.ino) fail("starter-pack-invalid", "the saved template changed while it was read", name);
if (st.uid !== uid) fail("starter-pack-invalid", "the saved template must belong to the instance's user", name);
if (st.nlink === 0) fail("starter-pack-invalid", "the saved template changed while it was read", name);
if (st.nlink !== 1) fail("starter-pack-invalid", "the saved template must not be a hard link", name);
if ((st.mode & 0o077) !== 0) fail("starter-pack-invalid", "the saved template must be mode 0600 or narrower", name);
if (st.size > SAVED_MAX_BYTES) fail("starter-pack-invalid", `the saved template must be at most ${SAVED_MAX_BYTES} bytes`, name);
// Read at most one byte past the limit, so a file that grew after the fstat still refuses.
const buffer = Buffer.alloc(SAVED_MAX_BYTES + 1);
let length = 0;
for (;;) {
const n = readSync(fd, buffer, length, buffer.length - length, null);
if (n === 0) break;
length += n;
if (length > SAVED_MAX_BYTES) fail("starter-pack-invalid", `the saved template grew past ${SAVED_MAX_BYTES} bytes while it was read`, name);
}
bytes = buffer.subarray(0, length);
} finally {
closeSync(fd);
}
let text;
try {
text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
fail("starter-pack-invalid", "the saved template is not valid UTF-8", name);
}
let doc;
try {
doc = parseJsonFileText(text, file, "saved template");
} catch {
fail("starter-pack-invalid", "the saved template is not valid JSON", name);
}
return { name, origin: "saved", pack: checkPack(doc, { origin: "saved", rolesDir }) };
}