aimeat 2.7.0 → 3.0.0

package/dist/scripts/check-route-scopes.js

@@ -0,0 +1,174 @@
+/**
+ * @file scripts/check-route-scopes.ts
+ * @description The gate for Rule 10 invariant 4: every mutating route carries an explicit scope or
+ *   role check. Whether a route requires a scope is stated in exactly one place, the argument list
+ *   of an Express handler, and until this script nothing read that place. The August 2026 audit
+ *   found roughly twenty findings that are each one entry in the list this produces.
+ *
+ *   Why it matters more than it reads: `requireScope`'s owner bypass deliberately excludes the
+ *   `app` role, so `requireScope` is the ONLY middleware that stops an app-grant token. A mutating
+ *   handler with `requireAuth()` alone is exactly the surface a granted app reaches holding whatever
+ *   single scope the consent screen displayed.
+ *
+ *   Ratchet, not a wall: the exemption file is seeded with today's offenders, so the gate fails only
+ *   on a NEW un-exempted handler. The count can go down and never up. Same shape as
+ *   check-silent-catch.ts, which is the repo's established pattern for this.
+ * @structure
+ *   - GATES: middleware names that count as an explicit authorization decision
+ *   - collectRoutes(): parse router.<verb>( calls and resolve their middleware chain
+ *   - main(): compare against security/route-scope-exemptions.json; --strict exits 1 on new ones
+ * @usage
+ *   cd aimeat && pnpm check:route-scopes            # report
+ *   cd aimeat && pnpm check:route-scopes --strict   # the hook/CI gate
+ *   cd aimeat && pnpm check:route-scopes --seed     # rewrite the exemption file from today's state
+ * @version-history
+ *   v1.1.0 — 2026-08-11 — requireOwnerPrincipal counts as a gate (August 2026 audit H-1/H-7), so
+ *     the fourteen account-security routes it now carries could leave the exemption file.
+ *   v1.0.0 — 2026-08-10 — Initial (August 2026 audit, systemic pattern 1).
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const ROOT = process.cwd();
+const ROUTES_DIR = join(ROOT, 'src', 'routes');
+const EXEMPTIONS = join(ROOT, 'security', 'route-scope-exemptions.json');
+/** Middleware that constitutes an explicit authorization decision. `requireAuth` is NOT one: it
+ *  answers "is anyone there", never "may this principal do this". `requireOwnerPrincipal` is one:
+ *  it answers "is this the account holder, or something acting for them", which is the decision the
+ *  account-security doors need and the one no scope word can express. */
+const GATES = ['requireScope', 'requireAnyScope', 'requireRole', 'requireRoleOrScope', 'requireOperator',
+    'requireOwnerPrincipal'];
+/** Verbs that change state. A GET is only checked when it already carries requireAuth (below). */
+const MUTATING = ['post', 'put', 'patch', 'delete'];
+function walk(dir, out = []) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, out);
+        else if (entry.endsWith('.ts'))
+            out.push(full);
+    }
+    return out;
+}
+/**
+ * The middleware section of a `router.verb(...)` call: everything between the path argument and the
+ * handler. Stops at the handler's parameter list, which is the first `(req`/`(_req`/`(async` shape,
+ * so a handler body full of parentheses never confuses the scan.
+ */
+function middlewareSection(source, from) {
+    const slice = source.slice(from, from + 900);
+    const handlerAt = slice.search(/(async\s*)?\(\s*_?req\b|\basync\s*\(\s*_?\w*\s*[,)]/);
+    return handlerAt > 0 ? slice.slice(0, handlerAt) : slice;
+}
+/** Middleware-array constants: `const auth = [requireAuth(), requireRole('operator')]`. */
+function gatedArrayNames(source) {
+    const names = new Set();
+    const re = /const\s+(\w+)\s*(?::[^=]+)?=\s*\[([^\]]*)\]/g;
+    let m;
+    while ((m = re.exec(source))) {
+        if (GATES.some(g => m[2].includes(g)))
+            names.add(m[1]);
+    }
+    return names;
+}
+/**
+ * Federation is authorized by an Ed25519 peer signature verified inside the handler, not by a scope:
+ * there is no auth middleware on `/v1/federation/*` by design (Rule 10 invariant 5), and a scope is
+ * meaningless for a peer node. Those routes have their own gate and their own audit; asking them for
+ * a scope would fill this list with noise and hide the routes that genuinely lack one.
+ */
+function isFederationRoute(rel, path) {
+    return rel.includes('/federation') || path.startsWith('/v1/federation');
+}
+export function collectRoutes(files) {
+    const findings = [];
+    for (const file of files) {
+        const source = readFileSync(file, 'utf-8');
+        const rel = relative(ROOT, file).replace(/\\/g, '/');
+        const arrays = gatedArrayNames(source);
+        // A router-level gate applies to every route in the file: `router.use(requireAuth(), requireRole(...))`
+        const routerLevelGate = /router\.use\(([^)]*(?:requireScope|requireRole|requireAnyScope)[^)]*)\)/.test(source);
+        if (routerLevelGate)
+            continue;
+        const re = /router\.(post|put|patch|delete|get)\(\s*(['"`])([^'"`]+)\2\s*,?/g;
+        let m;
+        while ((m = re.exec(source))) {
+            const [, method, , path] = m;
+            if (isFederationRoute(rel, path))
+                continue;
+            const chain = middlewareSection(source, m.index + m[0].length);
+            const hasGate = GATES.some(g => chain.includes(g))
+                || [...arrays].some(name => new RegExp(`\\b${name}\\b`).test(chain));
+            if (hasGate)
+                continue;
+            // A GET with no auth at all is a deliberately public read (catalogue, bootstrap, an
+            // <img src> path). Only an AUTHENTICATED read is asked to say which scope it needs.
+            if (method === 'get' && !chain.includes('requireAuth'))
+                continue;
+            const line = source.slice(0, m.index).split('\n').length;
+            findings.push({ file: rel, line, method: method.toUpperCase(), path });
+        }
+    }
+    return findings;
+}
+const key = (f) => `${f.file}:${f.line}:${f.method}:${f.path}`;
+/** Line numbers move; the identity that survives an edit is file + method + path. */
+const softKey = (f) => `${f.file}:${f.method}:${f.path}`;
+function loadExemptions() {
+    if (!existsSync(EXEMPTIONS))
+        return { note: '', exempt: {} };
+    return JSON.parse(readFileSync(EXEMPTIONS, 'utf-8'));
+}
+function main() {
+    const strict = process.argv.includes('--strict');
+    const seed = process.argv.includes('--seed');
+    const files = walk(ROUTES_DIR);
+    const findings = collectRoutes(files);
+    if (seed) {
+        const exempt = {};
+        for (const f of findings) {
+            exempt[softKey(f)] = 'Seeded 2026-08-10 from the August audit. Not yet reviewed: this route '
+                + 'changes state (or reads authenticated) without saying which scope it needs.';
+        }
+        const out = {
+            note: 'Routes that mutate (or read while authenticated) without an explicit scope or role gate. '
+                + 'Seeded from the state on 2026-08-10 so the gate can only ratchet down. Remove an entry when '
+                + 'the route gets its gate; never add one without a written reason and an approver.',
+            exempt,
+        };
+        writeFileSync(EXEMPTIONS, JSON.stringify(out, null, 2) + '\n');
+        console.log(`Seeded ${findings.length} exemptions into ${relative(ROOT, EXEMPTIONS)}`);
+        return;
+    }
+    const { exempt } = loadExemptions();
+    const known = new Set(Object.keys(exempt));
+    const fresh = findings.filter(f => !known.has(softKey(f)));
+    const stale = [...known].filter(k => !findings.some(f => softKey(f) === k));
+    const byFile = new Map();
+    for (const f of findings)
+        byFile.set(f.file, [...(byFile.get(f.file) ?? []), f]);
+    console.log('');
+    console.log('  Route authorization gate — Rule 10 invariant 4');
+    console.log('  ' + '─'.repeat(62));
+    console.log(`  ungated handlers   ${String(findings.length).padStart(5)}`);
+    console.log(`  of which exempt    ${String(findings.length - fresh.length).padStart(5)}   (seeded backlog, may only shrink)`);
+    console.log(`  NEW, not exempt    ${String(fresh.length).padStart(5)}`);
+    if (stale.length)
+        console.log(`  exemptions now fixed ${String(stale.length).padStart(3)}   (remove them from the file)`);
+    console.log('');
+    if (fresh.length) {
+        console.log('  A mutating route with requireAuth() alone is reachable by any app-grant token,');
+        console.log('  whatever single scope its owner approved. Add requireScope/requireRole, or add an');
+        console.log('  entry with a reason to security/route-scope-exemptions.json.');
+        console.log('');
+        for (const f of fresh)
+            console.log(`    ${f.file}:${f.line}  ${f.method} ${f.path}`);
+        console.log('');
+    }
+    if (strict && fresh.length) {
+        console.error(`✖ ${fresh.length} new ungated route handler(s).`);
+        process.exit(1);
+    }
+    console.log(fresh.length ? '  (report only — pass --strict to gate)' : '  ✓ no new ungated handlers');
+}
+main();
+//# sourceMappingURL=check-route-scopes.js.map

package/dist/scripts/check-route-scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-route-scopes.js","sourceRoot":"","sources":["../../scripts/check-route-scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAC3B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,6BAA6B,CAAC,CAAC;AAEzE;;;yEAGyE;AACzE,MAAM,KAAK,GAAG,CAAC,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB;IACpG,uBAAuB,CAAC,CAAC;AAE7B,kGAAkG;AAClG,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAgBpD,SAAS,IAAI,CAAC,GAAW,EAAE,MAAgB,EAAE;IACzC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;YAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;aAC7C,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,MAAc,EAAE,IAAY;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,qDAAqD,CAAC,CAAC;IACtF,OAAO,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC7D,CAAC;AAED,2FAA2F;AAC3F,SAAS,eAAe,CAAC,MAAc;IACnC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,EAAE,GAAG,8CAA8C,CAAC;IAC1D,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAW,EAAE,IAAY;IAChD,OAAO,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAe;IACzC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAEvC,wGAAwG;QACxG,MAAM,eAAe,GAAG,yEAAyE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/G,IAAI,eAAe;YAAE,SAAS;QAE9B,MAAM,EAAE,GAAG,kEAAkE,CAAC;QAC9E,IAAI,CAAyB,CAAC;QAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,EAAE,MAAM,EAAE,AAAD,EAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC;gBAAE,SAAS;YAC3C,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC/D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;mBAC3C,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YACzE,IAAI,OAAO;gBAAE,SAAS;YAEtB,oFAAoF;YACpF,oFAAoF;YACpF,IAAI,MAAM,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAAE,SAAS;YAEjE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3E,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AACxE,qFAAqF;AACrF,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAElE,SAAS,cAAc;IACnB,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAkB,CAAC;AAC1E,CAAC;AAED,SAAS,IAAI;IACT,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,IAAI,EAAE,CAAC;QACP,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACvB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,wEAAwE;kBACvF,6EAA6E,CAAC;QACxF,CAAC;QACD,MAAM,GAAG,GAAkB;YACvB,IAAI,EAAE,2FAA2F;kBAC3F,8FAA8F;kBAC9F,kFAAkF;YACxF,MAAM;SACT,CAAC;QACF,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,UAAU,QAAQ,CAAC,MAAM,oBAAoB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;QACvF,OAAO;IACX,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEjF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC;IAC9H,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC;IAC1H,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,kFAAkF,CAAC,CAAC;QAChG,OAAO,CAAC,GAAG,CAAC,qFAAqF,CAAC,CAAC;QACnG,OAAO,CAAC,GAAG,CAAC,gEAAgE,CAAC,CAAC;QAC9E,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,MAAM,gCAAgC,CAAC,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,yCAAyC,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC;AAC1G,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/scripts/check-shared-implementation.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=check-shared-implementation.d.ts.map

package/dist/scripts/check-shared-implementation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-shared-implementation.d.ts","sourceRoot":"","sources":["../../scripts/check-shared-implementation.ts"],"names":[],"mappings":""}

package/dist/scripts/check-shared-implementation.js

@@ -0,0 +1,158 @@
+/**
+ * @file scripts/check-shared-implementation.ts
+ * @description How far the MCP surface still is from calling what REST calls.
+ *
+ *   THE RULE (CLAUDE.md, Backend): one capability, one implementation, whatever the interface. An MCP
+ *   tool declares its own name, description and parameters because the protocol requires that. It
+ *   does not do the work itself: it calls the same route or the same service function REST calls, so
+ *   the scope check, the validation and the provenance happen where they were written once.
+ *
+ *   THE COST OF NOT DOING THAT, measured rather than argued: the same defect has been fixed three
+ *   separate times inside `aimeat_memory_write` — schema locks, the write target, the provenance
+ *   stamp — each time in one place while the other surface kept the old behaviour. The August 2026
+ *   audit then found two more of the same kind, and step 4 found eight more in the extension sandbox.
+ *
+ *   WHAT THIS COUNTS. A file under src/mcp/ that calls `storage.<something>` is doing the work
+ *   itself. That is the number to drive to zero, and it is a ratchet: the seed is the count on the
+ *   day this was written, and the gate fails only if the number GOES UP. Fixing one tool at a time
+ *   is the intended way through, because each fix is local — one tool swaps a direct call for a
+ *   shared service function that takes the caller and holds the gate.
+ * @structure SEED — the count on 2026-08-10. main(): report, and gate on any increase.
+ * @usage
+ *   cd aimeat && pnpm check:shared-impl            # report
+ *   cd aimeat && pnpm check:shared-impl --strict   # the hook/CI gate
+ * @version-history
+ *   v1.1.0 — 2026-08-11 — WRITE_SEED 2 → 1: aimeat_operator_agent_configure writes through
+ *     services/agent-profile-write.ts. The remaining writer is named, with what its REST twin is
+ *     and how the two already disagree.
+ *   v1.0.0 — 2026-08-10 — Initial (August 2026 audit step 3, option B).
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const ROOT = process.cwd();
+const MCP = join(ROOT, 'src', 'mcp');
+/**
+ * Files under src/mcp/ that are not tool surfaces and may talk to storage freely: the OAuth server,
+ * session plumbing, and the catalog. They implement the protocol, not a capability.
+ */
+const NOT_A_TOOL_SURFACE = new Set([
+    'src/mcp/oauth.ts',
+    'src/mcp/session.ts',
+    'src/mcp/sessions.ts',
+    'src/mcp/transport.ts',
+]);
+/**
+ * The count on the day the rule got a measure. The gate fails only above this.
+ *
+ * 44 when the number was first taken (the diagram the developer asked for, commit 846f21f4).
+ * 43 after aimeat_memory_write moved onto services/memory-write.ts — the capability whose same
+ * defect had been fixed three separate times. Lower this line with every tool that follows.
+ *
+ * 44 on 2026-08-11 after mcp/apps-fork.ts moved its quota onto services/install-quotas.ts.
+ * 45 earlier that day, and the two extra files were NOT new offenders: apps-fork.ts and
+ * workspace-create.ts are pure extractions out of apps.ts and workspaces.ts, which grew past
+ * max-file-lines while their gates were being fixed. The same code, counted in two places instead
+ * of one. Raising a ratchet needs a reason in writing, and that is the reason; the backlog did not
+ * grow, and clearing either parent clears its extraction with it.
+ *
+ * 39 files / 2 writers on 2026-08-11, audit step 8: nineteen capabilities moved in one pass, each
+ * one's write extracted into the service its REST twin already called. The number that matters is
+ * the second one, 29 writing tool surfaces became 2, because a tool that only READS a record it did
+ * not build has no shape to drift. The move found 169 places where the two copies had already
+ * disagreed, 113 of them visible to whoever was using the tool. That is the argument for this rule
+ * restated as measurement rather than as principle.
+ */
+const SEED = 39;
+/**
+ * The number that actually matters. A READ through storage is the same read whichever door asks;
+ * a WRITE is where the two implementations drift, because a write carries a gate, a validation and
+ * a side effect that one copy can forget. 30 of the 45 files write. Reported separately so progress
+ * on the risky half is visible even while the file-level count sits still.
+ *
+ * 30 rather than 28 for the same reason as SEED above: two pure extractions, no new capability
+ * writing on its own. Both parents still write, so both extractions count as writers too.
+ *
+ * 2 on 2026-08-11 after step 8. Nineteen capabilities moved in one pass.
+ *
+ * 1 on 2026-08-11 after aimeat_operator_agent_configure moved onto services/agent-profile-write.ts,
+ * where PATCH /v1/agents/:name/tags and /mode already were. Three rules it had been writing around:
+ * tags were stored verbatim, a mode change skipped the Hello Integration step-list re-derive, and an
+ * empty scope list was accepted where REST refuses it.
+ *
+ * The one that remains is mcp/agent-tasks.ts, and the step 8 note that it has "no REST twin at all"
+ * is wrong: aimeat_task_complete writes the same two records POST /v1/agents/:name/tasks/:id/complete
+ * writes, and the two have already drifted. REST completes an ACTIVE or a STALLED task and the tool
+ * only an active one, so an agent that crashed and came back cannot report the work it finished --
+ * the same narrowing services/agent-task-fanout.ts was written to close on the failure path. REST
+ * takes a deliverable_key and the tool has no way to send one, so an MCP completion never reaches
+ * the public feed. And the tool stamps AI provenance on the completion message where REST does not.
+ * The shared home is a completeTask() in services/agent-task-fanout.ts, next to the failTask() that
+ * is the same shape, and closing it means editing the REST door in the same pass.
+ */
+const WRITE_SEED = 1;
+/** Storage methods that change something. Everything else is a read. */
+const WRITEISH = /^(create|set|update|delete|add|remove|insert|upsert|write|debit|credit|transfer|enqueue|revoke|grant|mint|save|publish|archive|deactivate|activate|link|unlink)/i;
+function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, out);
+        else if (entry.endsWith('.ts'))
+            out.push(full);
+    }
+    return out;
+}
+/** Drop comments so a docblock naming `storage.setMemory` does not read as a call. */
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+function main() {
+    const strict = process.argv.includes('--strict');
+    const offenders = [];
+    for (const file of walk(MCP)) {
+        const rel = relative(ROOT, file).replace(/\\/g, '/');
+        if (NOT_A_TOOL_SURFACE.has(rel))
+            continue;
+        const source = stripComments(readFileSync(file, 'utf-8'));
+        const calls = [...source.matchAll(/\bstorage\.([a-zA-Z]+)\s*\(/g)].map(m => m[1]);
+        if (calls.length)
+            offenders.push({ file: rel, calls: [...new Set(calls)].sort() });
+    }
+    const count = offenders.length;
+    const writers = offenders.filter(o => o.calls.some(c => WRITEISH.test(c)));
+    console.log('');
+    console.log('  One capability, one implementation — MCP files doing the work themselves');
+    console.log('  ' + '─'.repeat(62));
+    console.log(`  tool-surface files calling storage directly  ${String(count).padStart(4)}`);
+    console.log(`  seeded on 2026-08-10                         ${String(SEED).padStart(4)}`);
+    console.log('');
+    console.log(`  of those, files that WRITE                   ${String(writers.length).padStart(4)}`);
+    console.log(`  seeded on 2026-08-10                         ${String(WRITE_SEED).padStart(4)}`);
+    console.log('');
+    if (writers.length > WRITE_SEED) {
+        console.error(`✖ ${writers.length} files write through storage directly, above the seeded ${WRITE_SEED}.`);
+        if (strict)
+            process.exit(1);
+        return;
+    }
+    if (count > SEED) {
+        console.log('  NEW since the seed — these are the ones to look at:');
+        for (const o of offenders.slice(0, 10))
+            console.log(`    ${o.file}  (${o.calls.slice(0, 5).join(', ')})`);
+        console.log('');
+        console.error(`✖ ${count} exceeds the seeded ${SEED}. A new MCP tool must call the same service or route REST calls.`);
+        if (strict)
+            process.exit(1);
+        return;
+    }
+    if (count < SEED) {
+        console.log(`  ✓ down ${SEED - count} from the seed. Lower the SEED constant in this script to lock the gain in.`);
+    }
+    else {
+        console.log('  ✓ no new direct-storage tool surfaces (the backlog is unchanged)');
+    }
+}
+main();
+//# sourceMappingURL=check-shared-implementation.js.map

package/dist/scripts/check-shared-implementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-shared-implementation.js","sourceRoot":"","sources":["../../scripts/check-shared-implementation.ts"],"names":[],"mappings":"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"}

package/dist/scripts/check-sse-parity.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=check-sse-parity.d.ts.map

package/dist/scripts/check-sse-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-sse-parity.d.ts","sourceRoot":"","sources":["../../scripts/check-sse-parity.ts"],"names":[],"mappings":""}

package/dist/scripts/check-sse-parity.js

@@ -0,0 +1,195 @@
+/**
+ * @file scripts/check-sse-parity.ts
+ * @description An MCP tool file that writes must say so on the change bus.
+ *
+ *   WHY. Every live view in this node subscribes to SSE change domains, and every REST route that
+ *   writes emits the domain its view listens on. The tool surface mostly did not: on 2026-08-11,
+ *   21 of the 31 tool files that write emitted nothing at all. The write landed, so nothing looked
+ *   broken — and the person watching the screen saw the old state until they reloaded, which reads
+ *   as "the agent did nothing" rather than "the page is stale". It is the quietest class of drift
+ *   there is, which is exactly why it needs a machine to notice it.
+ *
+ *   WHAT IT ASSERTS. A file under src/mcp/ that calls a write-shaped storage method must either
+ *   emit a change domain itself, or delegate to something that does — a shared service, or a route
+ *   function it calls. Both count: the point is that the write announces itself, not where the line
+ *   sits.
+ *
+ *   WHAT IT DOES NOT ASSERT. Which domain. A tool writing an app record could plausibly emit 'apps'
+ *   or 'owners', and a check that guessed would be noise. Whether the domain is the RIGHT one is
+ *   what test/e2e-mcp-sse-parity.ts measures, against a real open stream.
+ *
+ *   FALSE POSITIVES, and the shape of the exemption. Three kinds of file genuinely write and
+ *   genuinely must not emit: the OAuth server (a token is protocol, not a view), the session and
+ *   transport layer (it touches a chat instance on every request, and emitting there would be a
+ *   firehose), and a tool whose REST twin emits nothing either — capabilities is the standing
+ *   example. Each exemption below carries its reason, because "this one is fine" without a reason
+ *   is how the list grows until it means nothing.
+ * @structure EXEMPT (with reasons) · DELEGATES (files whose emit happens downstream) · main()
+ * @usage pnpm check:sse-parity  ·  --strict fails the build
+ * @version-history
+ *   v1.1.0 — 2026-08-11 — The rule reads the tool ANNOTATIONS as well as storage calls. The first
+ *     version looked only for storage.*, and four files walked past it — companies, skills,
+ *     workflows and the email invitations all write through a service, and each was silently
+ *     missing its emit. Found by an adversarial pass over this very check.
+ *   v1.0.0 — 2026-08-11 — Initial (August 2026 audit, the side-effect sweep).
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const MCP = join(ROOT, 'src/mcp');
+const ANNOTATIONS = join(ROOT, 'src/mcp/annotations.ts');
+/** Storage methods that change something. Everything else is a read, and a read announces nothing. */
+const WRITEISH = /\bstorage\.(?:create|set|update|delete|add|remove|insert|upsert|write|debit|credit|transfer|enqueue|revoke|grant|mint|save|publish|archive|deactivate|activate|link|unlink)[A-Za-z]*\s*\(/;
+/**
+ * Every tool that declares itself as changing something (`readOnlyHint: false` in annotations.ts).
+ *
+ * The first version of this check looked only for `storage.*` calls, and four files walked straight
+ * past it — companies, skills, workflows and the email invitations all write through a SERVICE, so
+ * the regex above never saw them and each was silently missing its emit. A tool's own annotation is
+ * the honest signal: it is what the tool tells its client about itself, and a mutating tool that
+ * lies there has a bigger problem than a missing event.
+ */
+function mutatingTools() {
+    const src = readFileSync(ANNOTATIONS, 'utf-8');
+    const out = new Set();
+    for (const m of src.matchAll(/(\w+):\s*\{[^}]*readOnlyHint:\s*false/g))
+        out.add(m[1]);
+    return out;
+}
+/** Files that write and must NOT emit, each with the reason it is not a gap. */
+const EXEMPT = {
+    'src/mcp/oauth.ts': 'The OAuth server. A client registration, an approval and a refresh token are protocol state, '
+        + 'not something a view renders, and no REST route emits for them either.',
+    'src/mcp/index.ts': 'The session and transport layer. It touches the chat instance on EVERY request to keep '
+        + 'lastSeen current, so emitting here would be a frame per tool call rather than a change '
+        + 'anyone asked about. The chat-instance tools emit for the acts a person cares about.',
+    'src/mcp/capabilities.ts': 'routes/capabilities.ts emits nothing either — a published capability is read through the '
+        + 'catalogue, which is not SSE-backed. Silence here is parity, not a gap.',
+    'src/mcp/agent-onboarding.ts': 'Emits agent-onboarding on its own; listed because the storage write sits in a helper the '
+        + 'regex below does not associate with the emit.',
+    'src/mcp/exchange.ts': 'The EXCHANGE surface has no SSE domain at all — routes/exchange.ts and exchange-market.ts '
+        + 'emit nothing either, and the market is read through the catalogue rather than a live view. '
+        + 'Silence is parity. If the exchange ever gets a live surface, both doors need the domain.',
+    'src/mcp/exchange-run.ts': 'Same as exchange.ts: no SSE domain exists for the running half either.',
+    'src/mcp/app-template-proposals.ts': 'There is no REST route for template proposals — it is an MCP-only capability, so there is '
+        + 'no twin to be out of step with. Emitting here would be a new behaviour, not a repair.',
+};
+/**
+ * Files whose write announces itself DOWNSTREAM: they call a service or a route function that emits.
+ * Named rather than inferred, because "somewhere below this there is an emit" is exactly the kind of
+ * claim that rots — each entry says which function carries it.
+ */
+const DELEGATES = {
+    // Step 8 (2026-08-11) moved each of these writes into the service its REST twin already called,
+    // and the emit went with the write. Each was verified by reading the domain out of the service
+    // rather than trusting the delegation: a tool that hands its write to a silent service is the
+    // same defect as a tool that never emitted, and it hides better.
+    'src/mcp/agent-capabilities.ts': "services/agent-profile-write.ts, which emits 'agent-capabilities'",
+    'src/mcp/agent-management.ts': "services/agent-profile-write.ts, which emits 'agents'",
+    'src/mcp/appdev-pitfalls.ts': "services/memory-write.ts and services/appdev-kb.ts, both emitting 'memory'",
+    'src/mcp/appdev-proofs.ts': "services/contribution-proofs.ts, which writes through "
+        + "services/memory-write.ts and emits 'memory' there. No REST twin exists for this one: the "
+        + 'proof is attached from the appdev tool surface only.',
+    'src/mcp/apps.ts': "services/app-publish.ts and services/app-lifecycle.ts, both emitting 'apps'",
+    'src/mcp/boards.ts': "services/board-write.ts and services/board-post.ts, both emitting 'boards'",
+    'src/mcp/chat-instances.ts': "services/chat-instance-write.ts, which emits 'chat'",
+    'src/mcp/commerce.ts': "services/memory-write.ts ('memory') and services/agent-offers-write.ts ('agents')",
+    'src/mcp/operator-config.ts': "services/memory-write.ts ('memory') and services/agent-profile-write.ts ('agents')",
+    'src/mcp/cortex.ts': "services/cortex-lifecycle.ts, which emits 'cortex'",
+    'src/mcp/extensions.ts': "services/extension-lifecycle.ts, which emits 'extensions'",
+    'src/mcp/knowledge.ts': "services/knowledge-package-entry.ts, which emits 'knowledge'",
+    'src/mcp/organisms-name-invites.ts': "services/invitations.ts, which emits 'organisms' and 'notifications'",
+    'src/mcp/sharing-groups.ts': "services/sharing-group-members.ts, which emits 'groups'",
+    'src/mcp/workspace-create.ts': 'writeRecord() from mcp/workspaces.ts, which emits organisms',
+    'src/mcp/apps-fork.ts': 'emits apps itself',
+    'src/mcp/consent.ts': "services/consent-write.ts, which emits 'consent'",
+    'src/mcp/contacts.ts': "services/contacts.ts, which emits 'messages'",
+    'src/mcp/dm-messages.ts': "services/message-send.ts, which emits 'messages'",
+    'src/mcp/feedback.ts': "services/feedback.ts, which emits 'feedback'",
+    'src/mcp/flags.ts': "services/moderation-flags.ts, which emits 'flags'",
+    'src/mcp/agent-messages.ts': "services/agent-message-send.ts, which emits 'agent-messages' scoped to the owner",
+    'src/mcp/agent-tasks.ts': "services/agent-task-write.ts (create, event, plan and todo) and "
+        + "services/agent-task-fanout.ts (completion and failure), both emitting 'agent-tasks' scoped to the owner",
+    'src/mcp/agent-telemetry.ts': "services/telemetry-buffer.ts ('agents') and usage-metering.ts ('agent-usage')",
+    'src/mcp/core.ts': "services/work-lifecycle.ts ('work' on accept and deliver), routes/work.ts "
+        + "createWorkItem ('work'), services/memory-write.ts ('memory') and services/board-post.ts ('boards')",
+    'src/mcp/core-admin.ts': "services/morsel.ts mintMorsels, which emits 'config' and 'wallet'",
+    'src/mcp/core-storage.ts': "services/storage-file-write.ts, which emits 'files' and 'memory'",
+};
+function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, out);
+        else if (entry.endsWith('.ts'))
+            out.push(full);
+    }
+    return out;
+}
+/** Drop comments so a docblock naming emitChange does not read as a call. */
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+function main() {
+    const strict = process.argv.includes('--strict');
+    const mutating = mutatingTools();
+    const silent = [];
+    let writers = 0;
+    let emitters = 0;
+    for (const file of walk(MCP)) {
+        const rel = relative(ROOT, file).replace(/\\/g, '/');
+        const source = stripComments(readFileSync(file, 'utf-8'));
+        // A file counts as writing if it touches storage directly OR REGISTERS a tool that declares
+        // itself mutating. The second half is what catches a file writing through a service.
+        //
+        // src/mcp/catalog/ is excluded from that half: those files are the metadata tables — tool
+        // descriptions, scope requirements, surface membership — so they NAME every tool without
+        // being any tool's surface. Including them would make the check noise on its first run,
+        // which is how a gate stops being read.
+        const isCatalog = rel.startsWith('src/mcp/catalog/');
+        const registersMutating = !isCatalog && [...mutating].some(t => source.includes(`mcp.tool(
+        '${t}'`)
+            || source.includes(`mcp.tool('${t}'`) || source.includes(`'${t}',
+`) && source.includes('mcp.tool'));
+        if (!WRITEISH.test(source) && !registersMutating)
+            continue;
+        writers++;
+        if (rel in EXEMPT)
+            continue;
+        if (/emitChange\(/.test(source)) {
+            emitters++;
+            continue;
+        }
+        if (rel in DELEGATES) {
+            emitters++;
+            continue;
+        }
+        silent.push(rel);
+    }
+    console.log('');
+    console.log('  An agent writes, and the open page hears about it (SSE parity)');
+    console.log('  ' + '─'.repeat(62));
+    console.log(`  tool-surface files that write            ${String(writers).padStart(4)}`);
+    console.log(`  of those, exempt with a reason           ${String(Object.keys(EXEMPT).length).padStart(4)}`);
+    console.log(`  announcing the change                    ${String(emitters).padStart(4)}`);
+    console.log(`  SILENT                                   ${String(silent.length).padStart(4)}`);
+    console.log('');
+    if (silent.length) {
+        for (const s of silent)
+            console.error(`  ✖ ${s} changes something and emits no change domain`);
+        console.error('');
+        console.error('  Emit the domain the view for this capability listens on, right after the write —');
+        console.error('  the same one its REST twin emits. If it genuinely should not, add it to EXEMPT in');
+        console.error('  this file WITH THE REASON, or to DELEGATES naming the function that emits for it.');
+        console.error('  Which domain is right is measured by test/e2e-mcp-sse-parity.ts against a real stream.');
+        if (strict)
+            process.exit(1);
+        return;
+    }
+    console.log('  ✓ every writing tool surface announces its change');
+}
+main();
+//# sourceMappingURL=check-sse-parity.js.map

package/dist/scripts/check-sse-parity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-sse-parity.js","sourceRoot":"","sources":["../../scripts/check-sse-parity.ts"],"names":[],"mappings":"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"}

package/dist/scripts/check-storage-parity.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=check-storage-parity.d.ts.map

package/dist/scripts/check-storage-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-storage-parity.d.ts","sourceRoot":"","sources":["../../scripts/check-storage-parity.ts"],"names":[],"mappings":""}