// #1873 T1 follow-up (org-defscan): the live credential store's held-secret check on an org // definition's text. A definition is role text written into the organization file; launch hands its // instructions to an agent as the contract. A file edited by hand, or while the bus was down, never // went through the writer's check, so bus start and every launch run this one. // // The answer names where a held credential sits, never the text there. A key that itself holds a // credential is named by its parent ("personality key"). Not imported by broker.mjs (the sandbox // loads that file); runtime.mjs and credential-verbs.mjs are its callers. import { BusError } from './broker.mjs'; export const DEFINITION_HOLDS_CREDENTIAL = 'definition-holds-credential'; // An organization file credentials.issue could not read to check: the issue refuses. export const DEFINITION_SCAN_UNREADABLE = 'definition-scan-unreadable'; // A definition name the scan quotes: the organization loader's id pattern. Anything else is "*". const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/; // A path segment the scan quotes; anything else becomes "*" (the hit is still reported). const SEGMENT = /^[A-Za-z0-9_-]{1,64}$/; const MAX_DEPTH = 32; const isClean = (assertClean, value) => { try { assertClean(value); return true; } catch { return false; } }; // The first place in `entry` whose text the store holds, as a path ("instructions", // "personality.traits[1]", "role key"), or null when the entry is clean. A hit the walk can't place // (a value JSON.stringify sees and the walk doesn't) is "(entry)": the check fails closed. export function heldPath(entry, assertClean) { if (isClean(assertClean, entry)) return null; const join = (path, key) => { const segment = SEGMENT.test(key) && isClean(assertClean, key) ? key : '*'; return path ? `${path}.${segment}` : segment; }; const walk = (value, path, depth) => { if (typeof value === 'string') return isClean(assertClean, value) ? null : path || '(entry)'; if (value === null || typeof value !== 'object' || depth > MAX_DEPTH) return null; if (Array.isArray(value)) { for (let i = 0; i < value.length; i++) { const hit = walk(value[i], `${path}[${i}]`, depth + 1); if (hit) return hit; } return null; } for (const [key, child] of Object.entries(value)) { if (!isClean(assertClean, key)) return path ? `${path} key` : 'key'; const hit = walk(child, join(path, key), depth + 1); if (hit) return hit; } return null; }; return walk(entry, '', 0) ?? '(entry)'; } // The refusal for one definition. `name` is the definition's name without "org:". At issue time // (`organization` given) it names the organization too, and the value is the one being issued. export function definitionRefusal(name, path, { organization, boot = false } = {}) { const quoted = typeof name === 'string' && NAME.test(name) ? name : '*'; const where = `${boot ? 'boot copy ' : ''}${name === null ? 'definitions' : `definitions.${quoted} ${path}`}`; if (organization === undefined) return new BusError(DEFINITION_HOLDS_CREDENTIAL, `${where} holds a credential this bus holds`); const org = typeof organization === 'string' && NAME.test(organization) ? organization : '*'; return new BusError(DEFINITION_HOLDS_CREDENTIAL, `organization ${org} ${where} holds the credential being issued`); } // The first entry of a `definitions` map that holds a credential, as { name, path }, or null. // `prefix` is stripped from each name ("org:" for a business's resolved definitions). A map that is // not an object is { name: null } when its text holds one. export function heldDefinition(definitions, assertClean, { prefix = '' } = {}) { if (definitions === undefined) return null; // an organization with no definitions key if (definitions === null || typeof definitions !== 'object' || Array.isArray(definitions)) return isClean(assertClean, definitions) ? null : { name: null, path: null }; for (const [key, entry] of Object.entries(definitions)) { if (prefix && !key.startsWith(prefix)) continue; if (!isClean(assertClean, key)) return { name: '*', path: 'key' }; const path = heldPath(entry, assertClean); if (path !== null) return { name: key.slice(prefix.length), path }; } return null; } // Every entry of a `definitions` map; throws the refusal for the first that holds a credential. export function scanDefinitions(definitions, assertClean, options = {}) { const hit = heldDefinition(definitions, assertClean, options); if (hit) throw definitionRefusal(hit.name, hit.path, options); } // org-defscan (#1873, Lead ruling on the re-check P2): credentials.issue and rotate refuse a value // that already sits in any organization's definitions, so no definition text becomes a held value // after its launch checks passed. `organizations` is every business this bus serves; `own` is the // issuing one's document, already read. Any other file is read raw, as bus start reads it, so a // definition no instance names is covered; a file that can't be read refuses. `boot` is the bus's boot // copy snapshot ({ org, definitions }, #1873 A3/A4): the root agents file's definitions merged with the // organization's at boot. Every reload re-applies it, so its text is live for the bus's lifetime. export function scanOrganizations({ organizations, own, readRaw, boot = null }, assertClean) { for (const organization of organizations) { let definitions; if (organization === own.id) definitions = own.document.definitions; else { let raw; try { raw = readRaw(organization); } catch { raw = { readable: false }; } if (raw?.readable !== true) throw new BusError(DEFINITION_SCAN_UNREADABLE); definitions = raw.document.definitions; } scanDefinitions(definitions, assertClean, { organization }); } if (boot?.definitions !== undefined) scanDefinitions(boot.definitions, assertClean, { organization: boot.org, boot: true }); }