diff --git a/packages/business/src/composition.mjs b/packages/business/src/composition.mjs new file mode 100644 index 000000000..0530664f8 --- /dev/null +++ b/packages/business/src/composition.mjs @@ -0,0 +1,2 @@ +// Old path of packages/organization/src/composition.mjs (rename design r2, stage B). +export * from "../../organization/src/composition.mjs"; diff --git a/packages/organization/src/composition.mjs b/packages/organization/src/composition.mjs new file mode 100644 index 000000000..9408471da --- /dev/null +++ b/packages/organization/src/composition.mjs @@ -0,0 +1,502 @@ +// Roles round 2, slice P1 (#1873): the primitives registry and the composition validator. +// Design: docs/plans/2026-11-10_roles-and-rails-design.md sections 3, 4 and 7, and the P1 +// paragraph of section 13. +// +// A role is a composition of the primitives in section 4 and nothing else: tools, network, +// authority, credentials, messaging, skills, instructions and personality. checkComposition +// checks one against a registry (the core set from vocabulary.mjs plus a plugin-declared set) in +// the seven steps section 4 lists, in order, and returns the lines a human must see flagged. +// +// Nothing calls checkComposition yet. HIRE_ALLOWED and unhireableAction (vocabulary.mjs) still +// bound a hire, and role.mjs and the broker still use them. Slice A4 switches hire over to this +// validator and removes them. In P1 the plugin set is whatever the caller passes, empty by +// default; nothing here reads a plugin file (PL1 builds install and the manifest). +// +// A refusal names the field and the position at fault. It quotes a value only when that value is +// a registered name (a core or plugin action, tool, network, service or scope), so no role text, +// and no secret placed where a name belongs, reaches an error. Free text (instructions, +// personality) is never quoted. + +import { refuse } from "./errors.mjs"; +import { + ACTIONS, ROUTED, GATED_ONLY, TOOLS, NETWORKS, SERVICES, HOST_SERVICE, GITEA_SCOPE_CATEGORIES, VIKUNJA_GRANTABLE, + ID_PATTERN, +} from "./vocabulary.mjs"; +import { NAME as PLUGIN_NAME } from "../../plugins/src/kinds.mjs"; +import { deepFreeze } from "./util.mjs"; + +// The primitives (section 4). Every other key refuses (step 1). +export const COMPOSITION_KEYS = Object.freeze([ + "tools", "network", "authority", "credentials", "messaging", "skills", "instructions", "personality", +]); +const REQUIRED = Object.freeze(["tools", "network", "authority", "credentials", "instructions"]); +const AUTHORITY_KEYS = Object.freeze(["withinRole", "crossRole"]); +const MESSAGING_KEYS = Object.freeze(["sendTo", "receiveFrom"]); +const PERSONALITY_KEYS = Object.freeze(["summary", "traits", "voice"]); +const CREDENTIAL_KEYS = Object.freeze(["service", "scopes"]); +const PLUGIN_KEYS = Object.freeze(["name", "tools", "actions", "services"]); +const PLUGIN_SERVICE_KEYS = Object.freeze(["name", "scopes"]); + +// Step 6's length bounds, in characters or entries. The design gives none, so P1 sets them. The +// largest shipped contract is about 8 KB; instructions get twice that. T1 stores personality +// with these same bounds. +export const COMPOSITION_BOUNDS = Object.freeze({ + instructions: 16384, + summary: 280, + traits: 12, + trait: 40, + voice: 280, + messaging: 64, + skills: 64, +}); + +// Ruling 8 and R9: a hired agent can't hire or fire, whatever HIRE_ALLOWED says later. +export const NEVER_HIRED = Object.freeze(["role.hire", "role.fire"]); +// The role rails (section 3): an action that lets its holder decide for other agents. +export const RESOLVE_PREFIX = "decision.resolve."; + +export const FLAG_RESOLVE = "resolve-right"; +export const FLAG_ABOVE_CHIEF = "above-chief"; + +const SKILL_NAME = /^[A-Za-z0-9._-]+$/; +const GITEA_SCOPE = /^(read|write):([a-z]+)$/; +// A plugin's declared bare name: lower-case segments joined by dots. With the prefix it is +// .. +const DECLARED_NAME = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/; +const DECLARED_SCOPE = /^[a-z][a-z0-9_.:-]*$/; +const NAME_MAX = 64; + +const isPlain = (value) => { + if (typeof value !== "object" || value === null || Array.isArray(value)) return false; + const proto = Object.getPrototypeOf(value); + return proto === Object.prototype || proto === null; +}; + +// --------------------------------------------------------------------------------------------- +// The registry. + +const BUILT = new WeakSet(); + +// The first segment of every core action, tool and service. A plugin may not take one as its +// name, so a prefixed plugin name can never read as a core name (git + push.protected). +const RESERVED_PLUGIN_NAMES = Object.freeze([...new Set([ + ...ACTIONS.map((a) => a.split(".")[0]), ...TOOLS, ...SERVICES, HOST_SERVICE, ...NETWORKS, +])]); + +function declaredList(value, where, pattern) { + if (value === undefined) return []; + if (!Array.isArray(value)) refuse(`${where} must be an array`); + const seen = new Set(); + value.forEach((entry, i) => { + if (typeof entry !== "string" || entry.length > NAME_MAX || !pattern.test(entry)) { + refuse(`${where}[${i}] must be a name matching ${pattern}`); + } + if (seen.has(entry)) refuse(`${where}[${i}] repeats an earlier entry`); + seen.add(entry); + }); + return [...seen]; +} + +// One plugin's declared set: { name, tools?: [name], actions?: [name], services?: [{ name, scopes: +// [scope] }] }. Names are declared bare and registered with the plugin's prefix. A plugin action is +// always routed (section 4), so it may not name a hard wait, and no declared name may reuse a core +// name, bare or prefixed. +function checkPlugin(plugin, i, core) { + const where = `registry plugins[${i}]`; + if (!isPlain(plugin)) refuse(`${where} must be a JSON object`); + for (const key of Object.keys(plugin)) { + if (!PLUGIN_KEYS.includes(key)) refuse(`${where} has a key outside ${PLUGIN_KEYS.join(", ")}`); + } + const { name } = plugin; + if (typeof name !== "string" || name.length > 32 || !PLUGIN_NAME.test(name)) refuse(`${where}.name must match ${PLUGIN_NAME}`); + if (RESERVED_PLUGIN_NAMES.includes(name)) refuse(`${where}.name ${JSON.stringify(name)} is a core name`); + const full = (bare) => `${name}.${bare}`; + const coreName = (bare) => core.has(bare) || core.has(full(bare)); + const tools = declaredList(plugin.tools, `${where}.tools`, DECLARED_NAME); + tools.forEach((bare, j) => { + if (coreName(bare)) refuse(`${where}.tools[${j}] reuses the core name ${JSON.stringify(core.has(bare) ? bare : full(bare))}`); + }); + const actions = declaredList(plugin.actions, `${where}.actions`, DECLARED_NAME); + actions.forEach((bare, j) => { + if (GATED_ONLY.includes(bare)) refuse(`${where}.actions[${j}] declares ${bare}, a hard wait; a plugin action is always routed`); + if (coreName(bare)) refuse(`${where}.actions[${j}] reuses the core name ${JSON.stringify(core.has(bare) ? bare : full(bare))}`); + }); + if (plugin.services !== undefined && !Array.isArray(plugin.services)) refuse(`${where}.services must be an array`); + const services = (plugin.services ?? []).map((service, j) => { + const at = `${where}.services[${j}]`; + if (!isPlain(service)) refuse(`${at} must be a JSON object`); + for (const key of Object.keys(service)) { + if (!PLUGIN_SERVICE_KEYS.includes(key)) refuse(`${at} has a key outside ${PLUGIN_SERVICE_KEYS.join(", ")}`); + } + const [bare] = declaredList([service.name], `${at}.name`, DECLARED_NAME); + if (coreName(bare)) refuse(`${at}.name reuses the core name ${JSON.stringify(core.has(bare) ? bare : full(bare))}`); + const scopes = declaredList(service.scopes, `${at}.scopes`, DECLARED_SCOPE); + if (scopes.length === 0) refuse(`${at}.scopes must not be empty`); + return { name: full(bare), scopes }; + }); + const names = [...tools, ...actions, ...services.map((s) => s.name.slice(name.length + 1))]; + const twice = names.find((n, j) => names.indexOf(n) !== j); + if (twice !== undefined) refuse(`${where} declares ${JSON.stringify(full(twice))} twice`); + return { name, tools: tools.map(full), actions: actions.map(full), services }; +} + +// The registry checkComposition reads: the core set plus each plugin's declared set. The plugin +// set is the caller's input and empty by default (PL1 passes the plugins enabled in the +// organization). checkComposition accepts only a registry built here. +export function buildRegistry({ plugins = [] } = {}) { + if (!Array.isArray(plugins)) refuse("registry plugins must be an array"); + const core = new Set([...ACTIONS, ...TOOLS, ...SERVICES, HOST_SERVICE]); + const declared = plugins.map((plugin, i) => checkPlugin(plugin, i, core)); + const pluginNames = declared.map((p) => p.name); + const twice = pluginNames.find((n, j) => pluginNames.indexOf(n) !== j); + if (twice !== undefined) refuse(`registry names plugin ${JSON.stringify(twice)} twice`); + const services = Object.create(null); + for (const name of SERVICES) services[name] = { kind: name }; + services[HOST_SERVICE] = { kind: HOST_SERVICE }; + for (const p of declared) for (const s of p.services) services[s.name] = { kind: "plugin", scopes: s.scopes }; + const pluginActions = declared.flatMap((p) => p.actions); + const registry = deepFreeze({ + tools: [...TOOLS, ...declared.flatMap((p) => p.tools)], + networks: [...NETWORKS], + actions: [...ACTIONS, ...pluginActions], + routed: [...ROUTED, ...pluginActions], + services, + plugins: declared, + }); + BUILT.add(registry); + return registry; +} + +// --------------------------------------------------------------------------------------------- +// The validator. + +function keysWithin(object, allowed, where) { + Object.keys(object).forEach((key, i) => { + if (!allowed.includes(key)) refuse(`composition ${where} has an unknown key (key ${i + 1}; allowed: ${allowed.join(", ")})`); + }); +} + +// A list of distinct strings. Entries are named by position only: this runs before anything is +// known to be a registered name. +function stringList(value, where, { nonEmpty = false } = {}) { + if (!Array.isArray(value)) refuse(`composition ${where} must be an array`); + if (nonEmpty && value.length === 0) refuse(`composition ${where} must not be empty`); + const seen = new Set(); + for (let i = 0; i < value.length; i += 1) { + if (typeof value[i] !== "string" || value[i].includes("\0")) refuse(`composition ${where}[${i}] must be a string`); + if (seen.has(value[i])) refuse(`composition ${where}[${i}] repeats an earlier entry`); + seen.add(value[i]); + } + return [...seen]; +} + +function text(value, where) { + if (typeof value !== "string" || value.includes("\0")) refuse(`composition ${where} must be a string`); + return value; +} + +// Step 1: the shape, with every unknown key refused. Returns a fresh copy; the input is not read +// again after this. +function shape(role) { + if (!isPlain(role)) refuse("composition must be a JSON object"); + keysWithin(role, COMPOSITION_KEYS, "role"); + for (const key of REQUIRED) { + if (role[key] === undefined) refuse(`composition requires "${key}"`); + } + const out = {}; + out.tools = stringList(role.tools, "tools", { nonEmpty: true }); + if (typeof role.network !== "string") refuse("composition network must be a string"); + out.network = role.network; + + if (!isPlain(role.authority)) refuse("composition authority must be a JSON object"); + keysWithin(role.authority, AUTHORITY_KEYS, "authority"); + out.authority = {}; + for (const key of AUTHORITY_KEYS) out.authority[key] = stringList(role.authority[key], `authority.${key}`); + out.authority.crossRole.forEach((action, i) => { + if (out.authority.withinRole.includes(action)) refuse(`composition authority.crossRole[${i}] is also in authority.withinRole`); + }); + + if (!Array.isArray(role.credentials)) refuse("composition credentials must be an array"); + out.credentials = role.credentials.map((entry, i) => { + const where = `credentials[${i}]`; + if (!isPlain(entry)) refuse(`composition ${where} must be a JSON object`); + keysWithin(entry, CREDENTIAL_KEYS, where); + if (typeof entry.service !== "string") refuse(`composition ${where}.service must be a string`); + const copy = { service: entry.service }; + if (entry.scopes !== undefined) { + if (Array.isArray(entry.scopes)) { + copy.scopes = stringList(entry.scopes, `${where}.scopes`); + } else if (isPlain(entry.scopes)) { + // No prototype, so a "__proto__" group stays a key and step 2 refuses it. + copy.scopes = Object.create(null); + Object.keys(entry.scopes).forEach((group, j) => { + if (group.includes("\0")) refuse(`composition ${where}.scopes key ${j + 1} must be a string`); + copy.scopes[group] = stringList(entry.scopes[group], `${where}.scopes (group ${j + 1})`); + }); + } else { + refuse(`composition ${where}.scopes must be an array or a JSON object`); + } + } + return copy; + }); + + if (role.messaging === undefined) { + out.messaging = null; + } else { + if (!isPlain(role.messaging)) refuse("composition messaging must be a JSON object"); + keysWithin(role.messaging, MESSAGING_KEYS, "messaging"); + out.messaging = {}; + for (const key of MESSAGING_KEYS) { + out.messaging[key] = stringList(role.messaging[key], `messaging.${key}`); + out.messaging[key].forEach((entry, i) => { + if (!ID_PATTERN.test(entry)) refuse(`composition messaging.${key}[${i}] must be a role name matching ${ID_PATTERN}`); + if (entry === "tester") refuse(`composition messaging.${key}[${i}] names the tester, which is never a role`); + }); + } + } + + out.skills = role.skills === undefined ? [] : stringList(role.skills, "skills"); + out.skills.forEach((name, i) => { + if (!SKILL_NAME.test(name) || name === "." || name === "..") refuse(`composition skills[${i}] must be a skill directory name matching ${SKILL_NAME}`); + }); + + out.instructions = text(role.instructions, "instructions"); + + if (role.personality === undefined) { + out.personality = null; + } else { + if (!isPlain(role.personality)) refuse("composition personality must be a JSON object"); + keysWithin(role.personality, PERSONALITY_KEYS, "personality"); + out.personality = {}; + if (role.personality.summary !== undefined) out.personality.summary = text(role.personality.summary, "personality.summary"); + if (role.personality.traits !== undefined) out.personality.traits = stringList(role.personality.traits, "personality.traits"); + if (role.personality.voice !== undefined) out.personality.voice = text(role.personality.voice, "personality.voice"); + } + return out; +} + +function checkGitea(scopes, where) { + if (!Array.isArray(scopes) || scopes.length === 0) refuse(`composition ${where}.scopes must be a non-empty array of read: or write:`); + const categories = new Set(); + scopes.forEach((scope, i) => { + const m = GITEA_SCOPE.exec(scope); + if (!m || !GITEA_SCOPE_CATEGORIES.includes(m[2])) { + refuse(`composition ${where}.scopes[${i}] is not a grantable gitea scope (categories: ${GITEA_SCOPE_CATEGORIES.join(", ")}; admin and all are never granted)`); + } + if (categories.has(m[2])) refuse(`composition ${where}.scopes[${i}] names the category ${m[2]} again; a token holds one level per category`); + categories.add(m[2]); + }); +} + +function checkVikunja(scopes, where) { + if (!isPlain(scopes) || Object.keys(scopes).length === 0) refuse(`composition ${where}.scopes must name at least one vikunja route group`); + Object.keys(scopes).forEach((group, j) => { + if (!Object.hasOwn(VIKUNJA_GRANTABLE, group)) refuse(`composition ${where}.scopes group ${j + 1} is not a grantable vikunja route group`); + const verbs = scopes[group]; + if (verbs.length === 0) refuse(`composition ${where}.scopes.${group} must not be empty`); + verbs.forEach((verb, i) => { + if (!VIKUNJA_GRANTABLE[group].includes(verb)) refuse(`composition ${where}.scopes.${group}[${i}] is not a grantable vikunja verb`); + }); + }); +} + +function checkPluginScopes(scopes, declared, service, where) { + if (!Array.isArray(scopes) || scopes.length === 0) refuse(`composition ${where}.scopes must be a non-empty array of ${service} scopes`); + scopes.forEach((scope, i) => { + if (!declared.includes(scope)) refuse(`composition ${where}.scopes[${i}] is not a scope ${service} declares`); + }); +} + +// Step 2: every action, tool, network, service and scope must be in the registry. +function registered(c, registry) { + c.tools.forEach((tool, i) => { + if (!registry.tools.includes(tool)) refuse(`composition tools[${i}] names no registered tool`); + }); + if (!registry.networks.includes(c.network)) refuse(`composition network must be one of: ${registry.networks.join(", ")}`); + for (const key of AUTHORITY_KEYS) { + c.authority[key].forEach((action, i) => { + if (!registry.actions.includes(action)) refuse(`composition authority.${key}[${i}] names no registered action`); + }); + } + const seen = new Set(); + c.credentials.forEach((entry, i) => { + const where = `credentials[${i}]`; + if (!Object.hasOwn(registry.services, entry.service)) refuse(`composition ${where}.service names no registered credential service`); + if (seen.has(entry.service)) refuse(`composition ${where} names ${entry.service} again`); + seen.add(entry.service); + const { kind, scopes } = registry.services[entry.service]; + if (kind === HOST_SERVICE) { + if (entry.scopes !== undefined) refuse(`composition ${where} names ${HOST_SERVICE}, which takes no scopes`); + } else if (kind === "gitea") { + checkGitea(entry.scopes, where); + } else if (kind === "vikunja") { + checkVikunja(entry.scopes, where); + } else { + checkPluginScopes(entry.scopes, scopes, entry.service, where); + } + }); +} + +function eachAction(c, fn) { + for (const key of AUTHORITY_KEYS) c.authority[key].forEach((action, i) => fn(action, key, i)); +} + +// Every string in the composition with its path, for step 6. +function strings(c) { + const out = []; + c.tools.forEach((v, i) => out.push([`tools[${i}]`, v])); + out.push(["network", c.network]); + eachAction(c, (v, key, i) => out.push([`authority.${key}[${i}]`, v])); + c.credentials.forEach((entry, i) => { + out.push([`credentials[${i}].service`, entry.service]); + if (Array.isArray(entry.scopes)) entry.scopes.forEach((v, j) => out.push([`credentials[${i}].scopes[${j}]`, v])); + else if (entry.scopes) { + for (const [group, verbs] of Object.entries(entry.scopes)) { + out.push([`credentials[${i}].scopes (group key)`, group]); + verbs.forEach((v, j) => out.push([`credentials[${i}].scopes.${group}[${j}]`, v])); + } + } + }); + if (c.messaging) for (const key of MESSAGING_KEYS) c.messaging[key].forEach((v, i) => out.push([`messaging.${key}[${i}]`, v])); + c.skills.forEach((v, i) => out.push([`skills[${i}]`, v])); + out.push(["instructions", c.instructions]); + if (c.personality) { + if (c.personality.summary !== undefined) out.push(["personality.summary", c.personality.summary]); + (c.personality.traits ?? []).forEach((v, i) => out.push([`personality.traits[${i}]`, v])); + if (c.personality.voice !== undefined) out.push(["personality.voice", c.personality.voice]); + } + return out; +} + +function bounded(value, max, where, { empty = false } = {}) { + if ((!empty && value.trim().length === 0) || value.length > max) { + refuse(`composition ${where} must be ${empty ? "" : "non-empty and "}at most ${max} characters`); + } +} + +// Step 6, the bounds half. +function checkBounds(c) { + const b = COMPOSITION_BOUNDS; + bounded(c.instructions, b.instructions, "instructions"); + if (c.personality) { + if (c.personality.summary !== undefined) bounded(c.personality.summary, b.summary, "personality.summary"); + if (c.personality.voice !== undefined) bounded(c.personality.voice, b.voice, "personality.voice"); + const traits = c.personality.traits ?? []; + if (traits.length > b.traits) refuse(`composition personality.traits must hold at most ${b.traits} entries`); + traits.forEach((trait, i) => bounded(trait, b.trait, `personality.traits[${i}]`)); + } + if (c.messaging) { + for (const key of MESSAGING_KEYS) { + if (c.messaging[key].length > b.messaging) refuse(`composition messaging.${key} must hold at most ${b.messaging} entries`); + } + } + if (c.skills.length > b.skills) refuse(`composition skills must hold at most ${b.skills} entries`); +} + +// The chief's resolved role, as loadRole returns it. Read only for step 7; a malformed one refuses. +function checkChief(chief) { + const bad = () => refuse("checkComposition needs the chief's resolved role"); + if (!isPlain(chief) || !Array.isArray(chief.tools) || !NETWORKS.includes(chief.network)) bad(); + if (!isPlain(chief.authority) || !AUTHORITY_KEYS.every((k) => Array.isArray(chief.authority[k]))) bad(); + if (!Array.isArray(chief.credentials) || !chief.credentials.every((c) => isPlain(c) && typeof c.service === "string")) bad(); + if (chief.messaging !== null && chief.messaging !== undefined && + !(isPlain(chief.messaging) && MESSAGING_KEYS.every((k) => Array.isArray(chief.messaging[k])))) bad(); + return chief; +} + +// One string per credential scope a role holds: service, then scope (a vikunja scope is +// group.verb; host has the one line "host"). +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; +} + +// Validate a composition (section 4's seven steps, in order) against a registry from +// buildRegistry, with the chief's resolved role for step 7. options.assertClean is the credential +// store's check (credentials.assertClean, as the broker's secretCheck); it throws on a held +// secret. Returns a frozen { composition, flagged }, where each flagged line is +// { field, value, reasons } and reasons holds "resolve-right" (step 5), "above-chief" (step 7) or +// both. A composition that fails a step refuses with an OrganizationConfigError. +export function checkComposition(role, registry, chief, { assertClean } = {}) { + if (!BUILT.has(registry)) refuse("checkComposition needs a registry from buildRegistry"); + if (typeof assertClean !== "function") refuse("checkComposition needs the credential store's assertClean"); + const boss = checkChief(chief); + + // 1. Unknown keys, and the shape. + const c = shape(role); + + // 2. Every name in the registry. + registered(c, registry); + + // 3. Hard waits stay with the human (R4). From here on an action is a registered name and may be + // quoted. + eachAction(c, (action, key, i) => { + if (!registry.routed.includes(action)) refuse(`composition authority.${key}[${i}] is ${action}, a hard wait the human always decides`); + }); + + // 4. No hire chains (R9). + eachAction(c, (action, key, i) => { + if (NEVER_HIRED.includes(action)) refuse(`composition authority.${key}[${i}] is ${action}; a hired agent cannot hire or fire`); + }); + + // 5. Every resolve right is a flagged line. + const lines = []; + const flag = (field, value, reason) => { + const line = lines.find((l) => l.field === field && l.value === value); + if (line) { + if (!line.reasons.includes(reason)) line.reasons.push(reason); + } else { + lines.push({ field, value, reasons: [reason] }); + } + }; + eachAction(c, (action, key) => { + if (action.startsWith(RESOLVE_PREFIX)) flag(`authority.${key}`, action, FLAG_RESOLVE); + }); + + // 6. No secret in any string (R1), and every field within its bound. + for (const [where, value] of strings(c)) { + let clean = true; + try { + assertClean(value); + } catch { + clean = false; + } + if (!clean) refuse(`composition ${where} holds a credential`); + } + checkBounds(c); + + // 7. Everything the chief's own role does not hold (R8). A within-role action is held only + // within-role; a cross-role one either way. + const chiefWithin = boss.authority.withinRole; + const chiefAny = [...chiefWithin, ...boss.authority.crossRole]; + c.authority.withinRole.forEach((action) => { + if (!chiefWithin.includes(action)) flag("authority.withinRole", action, FLAG_ABOVE_CHIEF); + }); + c.authority.crossRole.forEach((action) => { + if (!chiefAny.includes(action)) flag("authority.crossRole", action, FLAG_ABOVE_CHIEF); + }); + c.tools.forEach((tool) => { + if (!boss.tools.includes(tool)) flag("tools", tool, FLAG_ABOVE_CHIEF); + }); + if (NETWORKS.indexOf(c.network) > NETWORKS.indexOf(boss.network)) flag("network", c.network, FLAG_ABOVE_CHIEF); + const held = new Set(credentialLines(boss.credentials).map(([s, v]) => `${s}\n${v}`)); + for (const [service, value] of credentialLines(c.credentials)) { + if (!held.has(`${service}\n${value}`)) flag(`credentials.${service}`, value, FLAG_ABOVE_CHIEF); + } + // A role with no messaging key may message anyone; "*" stands for that. + const chiefSends = boss.messaging ? boss.messaging.sendTo : null; + if (chiefSends !== null) { + if (c.messaging === null) flag("messaging.sendTo", "*", FLAG_ABOVE_CHIEF); + else c.messaging.sendTo.forEach((target) => { + if (!chiefSends.includes(target)) flag("messaging.sendTo", target, FLAG_ABOVE_CHIEF); + }); + } + + for (const line of lines) line.reasons.sort(); + return deepFreeze({ composition: c, flagged: lines }); +} diff --git a/packages/organization/tests/composition.test.mjs b/packages/organization/tests/composition.test.mjs new file mode 100644 index 000000000..b3329e002 --- /dev/null +++ b/packages/organization/tests/composition.test.mjs @@ -0,0 +1,281 @@ +// Roles round 2, slice P1 (#1873): the composition validator and its registry. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { loadRole, BusinessError } from "../src/index.mjs"; +import { GATED_ONLY, HIRE_ALLOWED, unhireableAction, ROUTED } from "../src/vocabulary.mjs"; +import { + buildRegistry, checkComposition, COMPOSITION_BOUNDS, COMPOSITION_KEYS, FLAG_RESOLVE, FLAG_ABOVE_CHIEF, +} from "../src/composition.mjs"; +import { REPO_ROLES } from "./helpers.mjs"; + +const SECRET = "sk-test-NOT-A-SECRET-1234"; +// Stands in for the bus credential store's assertClean. Its own error quotes the secret, so a test +// can tell if checkComposition ever passes that error on. +const assertClean = (value) => { + if (JSON.stringify(value).includes(SECRET)) throw new Error(`credential-leak: ${SECRET}`); +}; +const OPTS = { assertClean }; +const CHIEF = loadRole(REPO_ROLES, "chief-of-staff"); +const CORE = buildRegistry(); + +function base(overrides = {}) { + return { + tools: ["read"], + network: "none", + authority: { withinRole: ["message.send"], crossRole: [] }, + credentials: [{ service: "gitea", scopes: ["read:repository"] }], + instructions: "Do the work in the brief.", + ...overrides, + }; +} + +const run = (role, registry = CORE, chief = CHIEF) => checkComposition(role, registry, chief, OPTS); + +function refuses(fn, pattern, ...absent) { + assert.throws(fn, (error) => { + assert.ok(error instanceof BusinessError, `expected BusinessError, got ${error}`); + assert.equal(error.exitCode, 2); + assert.match(error.message, pattern); + for (const text of [SECRET, ...absent]) { + assert.ok(!error.message.includes(text), `the refusal quotes ${JSON.stringify(text)}: ${error.message}`); + } + return true; + }); +} + +test("a minimal composition passes with nothing flagged", () => { + const { composition, flagged } = run(base()); + assert.deepEqual(flagged, []); + assert.equal(composition.instructions, "Do the work in the brief."); + assert.equal(composition.messaging, null); + assert.equal(composition.personality, null); + assert.ok(Object.isFrozen(composition) && Object.isFrozen(composition.authority.withinRole)); +}); + +test("checkComposition needs a registry from buildRegistry and the store's assertClean", () => { + refuses(() => checkComposition(base(), { ...CORE }, CHIEF, OPTS), /registry from buildRegistry/); + refuses(() => checkComposition(base(), CORE, CHIEF), /assertClean/); + refuses(() => checkComposition(base(), CORE, CHIEF, { assertClean: true }), /assertClean/); + refuses(() => checkComposition(base(), CORE, { tools: [] }, OPTS), /chief's resolved role/); +}); + +// Step 1. +test("an unknown key refuses at every level, without quoting the key", () => { + const key = `notes ${SECRET}`; + refuses(() => run({ ...base(), [key]: 1 }), /role has an unknown key/, key); + for (const field of ["name", "title", "contract", "roleVersion", "hireable"]) { + refuses(() => run({ ...base(), [field]: "x" }), /role has an unknown key/); + } + refuses(() => run(base({ authority: { withinRole: [], crossRole: [], [key]: [] } })), /authority has an unknown key/, key); + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: ["read:issue"], [key]: 1 }] })), /credentials\[0\] has an unknown key/, key); + refuses(() => run(base({ messaging: { sendTo: [], receiveFrom: [], [key]: [] } })), /messaging has an unknown key/, key); + refuses(() => run(base({ personality: { summary: "Calm.", [key]: "x" } })), /personality has an unknown key/, key); + refuses(() => run(JSON.parse('{"__proto__": {"tools": ["read"]}}')), /unknown key|requires/); +}); + +test("the required primitives and their shapes", () => { + for (const key of ["tools", "network", "authority", "credentials", "instructions"]) { + const role = base(); + delete role[key]; + refuses(() => run(role), new RegExp(`requires "${key}"`)); + } + refuses(() => run(base({ tools: [] })), /tools must not be empty/); + refuses(() => run(base({ tools: ["read", "read"] })), /tools\[1\] repeats/); + refuses(() => run(base({ authority: { withinRole: ["message.send"] } })), /authority.crossRole must be an array/); + refuses(() => run(base({ authority: { withinRole: ["message.send"], crossRole: ["message.send"] } })), /crossRole\[0\] is also in authority.withinRole/); + refuses(() => run(base({ instructions: ["x"] })), /instructions must be a string/); + refuses(() => run(base({ instructions: "a\0b" })), /instructions must be a string/); + refuses(() => run(base({ messaging: { sendTo: ["tester"], receiveFrom: [] } })), /names the tester/); + refuses(() => run(base({ messaging: { sendTo: ["Bad Name"], receiveFrom: [] } })), /sendTo\[0\] must be a role name/, "Bad Name"); + refuses(() => run(base({ skills: [".."] })), /skills\[0\] must be a skill directory name/); + assert.deepEqual(Object.keys(base()).every((k) => COMPOSITION_KEYS.includes(k)), true); +}); + +// Step 2. +test("an unknown action, tool, network, service or scope refuses without quoting it", () => { + const odd = `zz-${SECRET}`; + refuses(() => run(base({ authority: { withinRole: [odd], crossRole: [] } })), /withinRole\[0\] names no registered action/, odd); + refuses(() => run(base({ authority: { withinRole: [], crossRole: ["task.nonesuch"] } })), /crossRole\[0\] names no registered action/, "task.nonesuch"); + refuses(() => run(base({ tools: ["read", "hammer"] })), /tools\[1\] names no registered tool/, "hammer"); + refuses(() => run(base({ network: odd })), /network must be one of: none, api-only, open/, odd); + refuses(() => run(base({ credentials: [{ service: "jira", scopes: ["read"] }] })), /credentials\[0\].service names no registered/, "jira"); + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: ["write:nonesuch"] }] })), /scopes\[0\] is not a grantable gitea scope/, "nonesuch"); + refuses(() => run(base({ credentials: [{ service: "vikunja", scopes: { nonesuch: ["read_one"] } }] })), /group 1 is not a grantable vikunja route group/, "nonesuch"); + refuses(() => run(base({ credentials: [{ service: "vikunja", scopes: { __proto__: null, ["__proto__"]: ["read_one"] } }] })), /not a grantable vikunja route group/); + refuses(() => run(base({ credentials: [{ service: "vikunja", scopes: { tasks: ["obliterate"] } }] })), /scopes.tasks\[0\] is not a grantable vikunja verb/, "obliterate"); + refuses(() => run(base({ credentials: [{ service: "host", scopes: ["any"] }] })), /host, which takes no scopes/); + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: ["read:issue"] }, { service: "gitea", scopes: ["read:user"] }] })), /credentials\[1\] names gitea again/); +}); + +test("gitea admin and all refuse, at either level", () => { + for (const scope of ["admin", "all", "write:admin", "read:admin", "write:all", "read:all", "sudo"]) { + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: [scope] }] })), /not a grantable gitea scope/); + } + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: ["read:issue", "write:issue"] }] })), /scopes\[1\] names the category issue again/); + refuses(() => run(base({ credentials: [{ service: "gitea", scopes: [] }] })), /non-empty array/); +}); + +// Step 3. +test("each hard wait refuses, in either authority list", () => { + assert.ok(GATED_ONLY.length > 0); + for (const action of GATED_ONLY) { + refuses(() => run(base({ authority: { withinRole: [action], crossRole: [] } })), /withinRole\[0\] is .* a hard wait/); + refuses(() => run(base({ authority: { withinRole: [], crossRole: [action] } })), /crossRole\[0\] is .* a hard wait/); + } +}); + +// Step 4. +test("role.hire and role.fire refuse", () => { + for (const action of ["role.hire", "role.fire"]) { + assert.ok(ROUTED.includes(action), `${action} is routed, so step 4 is what refuses it`); + refuses(() => run(base({ authority: { withinRole: [action], crossRole: [] } })), /cannot hire or fire/); + refuses(() => run(base({ authority: { withinRole: [], crossRole: [action] } })), /cannot hire or fire/); + } +}); + +// Step 5. +test("a decision.resolve action comes back as a flagged line", () => { + const { flagged } = run(base({ authority: { withinRole: ["message.send"], crossRole: ["decision.resolve.technical"] } })); + assert.deepEqual(flagged, [ + { field: "authority.crossRole", value: "decision.resolve.technical", reasons: [FLAG_ABOVE_CHIEF, FLAG_RESOLVE] }, + ]); + // Held by the chief: still flagged as a resolve right, and only that. + const chief = { ...CHIEF, authority: { withinRole: [...CHIEF.authority.withinRole, "decision.resolve.technical"], crossRole: [] } }; + const held = run(base({ authority: { withinRole: ["decision.resolve.technical"], crossRole: [] } }), CORE, chief); + assert.deepEqual(held.flagged, [{ field: "authority.withinRole", value: "decision.resolve.technical", reasons: [FLAG_RESOLVE] }]); +}); + +// Step 6. +test("a secret in instructions or personality refuses, and the refusal does not contain it", () => { + const cases = [ + [{ instructions: `Use ${SECRET} for the API.` }, /instructions holds a credential/], + [{ personality: { summary: `Knows ${SECRET}.` } }, /personality.summary holds a credential/], + [{ personality: { traits: ["calm", `key ${SECRET}`] } }, /personality.traits\[1\] holds a credential/], + [{ personality: { voice: `Says ${SECRET} often.` } }, /personality.voice holds a credential/], + [{ skills: [SECRET] }, /skills\[0\] holds a credential/], + ]; + for (const [overrides, pattern] of cases) refuses(() => run(base(overrides)), pattern, "Use ", "Knows", "Says"); +}); + +test("the free text never reaches an error", () => { + const prose = "PRIVATE-INSTRUCTION-TEXT"; + refuses(() => run(base({ instructions: prose.repeat(2000) })), /instructions must be non-empty and at most 16384 characters/, prose); + refuses(() => run(base({ instructions: prose, personality: { summary: prose.repeat(20) } })), /personality.summary must be/, prose); + refuses(() => run(base({ instructions: prose, authority: { withinRole: ["deploy"], crossRole: [] } })), /hard wait/, prose); +}); + +test("the length bounds hold, from one exported constant", () => { + assert.deepEqual({ ...COMPOSITION_BOUNDS }, { instructions: 16384, summary: 280, traits: 12, trait: 40, voice: 280, messaging: 64, skills: 64 }); + assert.ok(Object.isFrozen(COMPOSITION_BOUNDS)); + const b = COMPOSITION_BOUNDS; + run(base({ instructions: "x".repeat(b.instructions), personality: { summary: "s".repeat(b.summary), voice: "v".repeat(b.voice), traits: Array.from({ length: b.traits }, (_, i) => `${i}`.padEnd(b.trait, "t")) } })); + refuses(() => run(base({ instructions: "x".repeat(b.instructions + 1) })), /instructions must be/); + refuses(() => run(base({ instructions: " " })), /instructions must be non-empty/); + refuses(() => run(base({ personality: { summary: "s".repeat(b.summary + 1) } })), /personality.summary must be/); + refuses(() => run(base({ personality: { voice: "v".repeat(b.voice + 1) } })), /personality.voice must be/); + refuses(() => run(base({ personality: { traits: Array.from({ length: b.traits + 1 }, (_, i) => `t${i}`) } })), /at most 12 entries/); + refuses(() => run(base({ personality: { traits: ["t".repeat(b.trait + 1)] } })), /traits\[0\] must be/); + refuses(() => run(base({ messaging: { sendTo: Array.from({ length: b.messaging + 1 }, (_, i) => `r${i}`), receiveFrom: [] } })), /sendTo must hold at most 64/); + refuses(() => run(base({ skills: Array.from({ length: b.skills + 1 }, (_, i) => `s${i}`) })), /skills must hold at most 64/); +}); + +test("the steps run in order: a hard wait refuses before the secret check", () => { + refuses(() => run(base({ instructions: SECRET, authority: { withinRole: ["spend"], crossRole: [] } })), /hard wait/); + refuses(() => run(base({ instructions: SECRET, authority: { withinRole: ["role.fire"], crossRole: [] } })), /cannot hire or fire/); +}); + +// Step 7. +test("the shipped coder against the shipped chief flags exactly the hand-built set", () => { + const coder = loadRole(REPO_ROLES, "coder"); + const role = { + tools: coder.tools, + network: coder.network, + authority: coder.authority, + credentials: coder.credentials, + skills: coder.skills, + instructions: readFileSync(join(REPO_ROLES, "coder.md"), "utf8"), + }; + const { flagged } = run(role); + const above = (field, value) => ({ field, value, reasons: [FLAG_ABOVE_CHIEF] }); + const expected = [ + above("authority.withinRole", "task.update.assigned"), + above("authority.withinRole", "git.push.working"), + above("authority.withinRole", "review.request"), + above("authority.crossRole", "task.scope.change"), + above("tools", "write"), + above("tools", "edit"), + above("tools", "bash"), + above("credentials.gitea", "write:issue"), + above("credentials.gitea", "write:repository"), + above("credentials.vikunja", "tasks.read_one"), + above("credentials.vikunja", "tasks.update"), + above("credentials.vikunja", "tasks_comments.create"), + above("credentials.vikunja", "projects.views_buckets_tasks"), + ]; + const key = (l) => `${l.field} ${l.value}`; + assert.deepEqual([...flagged].map((l) => ({ ...l, reasons: [...l.reasons] })).sort((a, b) => key(a).localeCompare(key(b))), + expected.sort((a, b) => key(a).localeCompare(key(b)))); +}); + +test("network, cross-role and messaging above the chief are flagged", () => { + assert.deepEqual(run(base({ network: "open" })).flagged, [{ field: "network", value: "open", reasons: [FLAG_ABOVE_CHIEF] }]); + assert.deepEqual(run(base({ network: "api-only" })).flagged, []); + // A cross-role action the chief holds within its role is not above it. + assert.deepEqual(run(base({ authority: { withinRole: [], crossRole: ["message.send"] } })).flagged, []); + // A within-role action the chief holds only cross-role is. + const crossChief = { ...CHIEF, authority: { withinRole: ["message.send"], crossRole: ["record.write"] } }; + assert.deepEqual(run(base({ authority: { withinRole: ["record.write"], crossRole: [] } }), CORE, crossChief).flagged, + [{ field: "authority.withinRole", value: "record.write", reasons: [FLAG_ABOVE_CHIEF] }]); + const host = run(base({ credentials: [{ service: "host" }] })).flagged; + assert.deepEqual(host, [{ field: "credentials.host", value: "host", reasons: [FLAG_ABOVE_CHIEF] }]); + const narrow = { ...CHIEF, messaging: { sendTo: ["pm"], receiveFrom: [] } }; + assert.deepEqual(run(base(), CORE, narrow).flagged, [{ field: "messaging.sendTo", value: "*", reasons: [FLAG_ABOVE_CHIEF] }]); + assert.deepEqual(run(base({ messaging: { sendTo: ["pm", "cto"], receiveFrom: ["qa"] } }), CORE, narrow).flagged, + [{ field: "messaging.sendTo", value: "cto", reasons: [FLAG_ABOVE_CHIEF] }]); +}); + +// The plugin-declared set (section 7, registry shape only). +test("a plugin action is accepted only with its prefix", () => { + const registry = buildRegistry({ plugins: [{ name: "forge", tools: ["lathe"], actions: ["build.run"], services: [{ name: "store", scopes: ["read", "write"] }] }] }); + const ok = run(base({ + tools: ["read", "forge.lathe"], + authority: { withinRole: ["forge.build.run"], crossRole: [] }, + credentials: [{ service: "forge.store", scopes: ["read"] }], + }), registry); + assert.deepEqual(ok.flagged.map((l) => `${l.field} ${l.value}`).sort(), + ["authority.withinRole forge.build.run", "credentials.forge.store read", "tools forge.lathe"]); + refuses(() => run(base({ authority: { withinRole: ["build.run"], crossRole: [] } }), registry), /names no registered action/, "build.run"); + refuses(() => run(base({ tools: ["lathe"] }), registry), /names no registered tool/, "lathe"); + refuses(() => run(base({ credentials: [{ service: "store", scopes: ["read"] }] }), registry), /names no registered credential service/); + refuses(() => run(base({ credentials: [{ service: "forge.store", scopes: ["admin"] }] }), registry), /is not a scope forge.store declares/, "admin"); + // Without the plugin in the registry, its names are unknown. + refuses(() => run(base({ authority: { withinRole: ["forge.build.run"], crossRole: [] } })), /names no registered action/); +}); + +test("a plugin refuses if it reuses a core name or declares a hard wait", () => { + const reg = (plugin) => () => buildRegistry({ plugins: [plugin] }); + for (const action of GATED_ONLY) refuses(reg({ name: "forge", actions: [action] }), /a hard wait/); + refuses(reg({ name: "forge", actions: ["message.send"] }), /reuses the core name "message.send"/); + refuses(reg({ name: "forge", tools: ["read"] }), /reuses the core name "read"/); + refuses(reg({ name: "forge", services: [{ name: "gitea", scopes: ["x"] }] }), /reuses the core name "gitea"/); + for (const name of ["git", "role", "decision", "read", "gitea", "host", "open"]) { + refuses(reg({ name, actions: ["x"] }), /is a core name/); + } + refuses(reg({ name: "Forge" }), /name must match/); + refuses(reg({ name: "forge", extra: 1 }), /has a key outside/); + refuses(reg({ name: "forge", actions: ["a", "a"] }), /repeats an earlier entry/); + refuses(reg({ name: "forge", tools: ["a"], actions: ["a"] }), /declares "forge.a" twice/); + refuses(reg({ name: "forge", actions: [`x ${SECRET}`] }), /must be a name matching/); + refuses(reg({ name: "forge", services: [{ name: "store", scopes: [] }] }), /scopes must not be empty/); + refuses(() => buildRegistry({ plugins: [{ name: "forge" }, { name: "forge" }] }), /plugin "forge" twice/); + refuses(() => buildRegistry({ plugins: {} }), /plugins must be an array/); + // A plugin action is routed, so it never reads as a hard wait at step 3. + assert.ok(buildRegistry({ plugins: [{ name: "forge", actions: ["build.run"] }] }).routed.includes("forge.build.run")); +}); + +test("HIRE_ALLOWED and unhireableAction stay until A4", () => { + assert.ok(Array.isArray(HIRE_ALLOWED) && HIRE_ALLOWED.length > 0); + assert.equal(typeof unhireableAction, "function"); +});