@vantageos/backend-doctor 0.3.0 → 0.4.0

package/dist/detectors/source/credential-hygiene.js

@@ -0,0 +1,619 @@
+// R-56 — a credential is held only as a one-way digest of a high-entropy secret,
+// a refresh token is single-use, every bearer is revocable and a bearer minted from
+// a session is bounded, and a verification token is matched in full.
+//
+// Standard bacc54a §4 R-56 and its Detector spec, read literally. Four clauses,
+// one site kind each (the tag opens the site's note):
+//   (1)  at rest. A `ctx.db.insert|patch|replace` object whose key is a credential
+//        (`code`, `token`, `secret`, `apiKey`, `password`, `refreshToken`, …) and whose
+//        value holds no one-way digest is plaintext at rest. A digest of a value
+//        that traces to a chosen secret — a door argument named like a secret
+//        (`callerToken`, `secret`, …) or an environment secret — that reaches a
+//        stored row is an offline-checkable copy of that secret. A digest of a
+//        value the backend generated, or of an identity, is conformant.
+//   (2)  refresh. A table named like a refresh-token store, read by a hash index in
+//        some function, with no function in the tree that reads it by hash AND marks
+//        the token consumed or revoked (or deletes it), leaves a stolen token
+//        replayable for its whole life.
+//   (3a) revocable. A table whose inserted rows carry `tokenHash` and `expiresAt`
+//        holds bearers; if no function in the tree reads that table and revokes
+//        (a revoked flag or timestamp) or deletes a row of it, no bearer can be
+//        withdrawn.
+//   (3b) bounded. The function that inserts such a row, into a table with no code
+//        or refresh-token linkage, holds neither a revoke-prior (a patch/delete on
+//        the same table) nor a cap (a read of the table whose result a refusal
+//        bounds). A row that links the grant it was exchanged from
+//        (`refreshTokenHash`, `codeHash`, `familyId`, …) belongs to a family that
+//        clause 2 bounds, and a refresh-token table is clause 2's.
+//   (4)  verification. A request-supplied commit/hash/token identifier matched
+//        against stored text by `.includes` / `.startsWith` / `.indexOf` with no
+//        full-length check (a 40- or 64-digit pattern, or a length compared with 40
+//        or 64) lets a one-character prefix verify; (4e) a response body that
+//        echoes stored content (`hint`, `noteExcerpt`, `excerpt`, `got`, …) from a
+//        function that verifies a token.
+//
+// NOT DECIDED HERE, stated. The entropy of a secret generated outside the backend;
+// the binding of a minted bearer to a session's verified claims rather than a
+// body-declared value. A control reads that a digest is stored, not how strong the
+// input was.
+import * as ts from "typescript";
+import { lineOf, parseFile, unwrap, walk } from "./_ast.js";
+import { decide, emptyScan, isJudgeable, } from "./_scan.js";
+export const R56_ID = "R-56 credentials held as digests of generated secrets, refresh tokens single-use, bearers revocable and session-minted bearers bounded, verification tokens matched in full";
+const R56_CHECK = "a credential-named column holds a digest of a generated value; a refresh-token table read by hash has a consuming door; a bearer table has a revocation door and its mint revokes prior bearers or caps them (or exchanges a code or refresh token); a request-supplied commit identifier is length-checked before it is matched";
+export const R56_STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa §4 R-56";
+const CRED_KEY = /^(code|token|secret|apiKey|api_key|password|passphrase|refreshToken|accessToken|bearer|rawToken|authorizationCode|clientSecret|privateKey|sessionToken|otp)$/i;
+const SECRET_ARG = /^(callerToken|masterSecret|masterToken|secret|password|passphrase|apiKey|adminSecret|bearerSecret)$/i;
+const DIGEST_FN = /^(sha(1|224|256|384|512)\w*|hash\w*|digest\w*|hmac\w*|md5\w*|createHash|bcrypt\w*|argon\w*|scrypt\w*|pbkdf2\w*)$/i;
+const REVOKED_KEY = /^(revoked|revokedAt|consumedAt|usedAt|used|consumed|deletedAt)$/i;
+const FAMILY_KEY = /^(refreshTokenHash|codeHash|authorizationCodeHash|familyId|grantId|parentTokenHash)$/i;
+const ECHO_KEY = /^(hint|noteExcerpt|excerpt|got|preview|snippet)$/i;
+const CAP_WORDS = /cap|limit|max|too many|exceed/i;
+const ID_NAME = /(sha|commit|hash|digest)/i;
+const isConvexFile = (f) => /(^|\/)convex\//.test(f.rel);
+function unitsOf(p) {
+    const out = [];
+    for (const st of p.sf.statements) {
+        if (ts.isFunctionDeclaration(st) && st.name && st.body)
+            out.push({ name: st.name.text, rel: p.rel, line: lineOf(st), node: st });
+        else if (ts.isVariableStatement(st))
+            for (const d of st.declarationList.declarations)
+                if (ts.isIdentifier(d.name) && d.initializer)
+                    out.push({
+                        name: d.name.text,
+                        rel: p.rel,
+                        line: lineOf(d),
+                        node: d.initializer,
+                    });
+        if (ts.isExpressionStatement(st) && ts.isCallExpression(st.expression)) {
+            const c = unwrap(st.expression.expression);
+            if (ts.isPropertyAccessExpression(c) && c.name.text === "route") {
+                const cfg = st.expression.arguments[0];
+                let path = "route";
+                let method = "";
+                if (cfg && ts.isObjectLiteralExpression(cfg))
+                    for (const pr of cfg.properties)
+                        if (ts.isPropertyAssignment(pr) && ts.isIdentifier(pr.name)) {
+                            if (pr.name.text === "path" &&
+                                ts.isStringLiteralLike(pr.initializer))
+                                path = pr.initializer.text;
+                            if (pr.name.text === "method" &&
+                                ts.isStringLiteralLike(pr.initializer))
+                                method = pr.initializer.text;
+                        }
+                out.push({
+                    name: `${method ? `${method} ` : ""}${path}`,
+                    rel: p.rel,
+                    line: lineOf(st),
+                    node: st,
+                });
+            }
+        }
+    }
+    return out;
+}
+// ---- small readers ---------------------------------------------------------------
+function strArg(c, i = 0) {
+    const a = c.arguments[i];
+    return a && ts.isStringLiteralLike(a) ? a.text : undefined;
+}
+function methodOf(c) {
+    const e = unwrap(c.expression);
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text;
+    if (ts.isIdentifier(e))
+        return e.text;
+    return undefined;
+}
+function isDigestCall(c) {
+    const e = unwrap(c.expression);
+    if (ts.isIdentifier(e))
+        return DIGEST_FN.test(e.text);
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text === "digest" || DIGEST_FN.test(e.name.text);
+    return false;
+}
+function holdsDigest(e) {
+    let hit = false;
+    walk(e, (x) => {
+        if (!hit && ts.isCallExpression(x) && isDigestCall(x))
+            hit = true;
+    });
+    return hit;
+}
+function localInits(unit) {
+    const m = new Map();
+    walk(unit, (x) => {
+        if (ts.isVariableDeclaration(x) && ts.isIdentifier(x.name) && x.initializer)
+            m.set(x.name.text, x.initializer);
+    });
+    return m;
+}
+function isDigestValue(e, inits, depth = 0) {
+    if (holdsDigest(e))
+        return true;
+    const x = unwrap(e);
+    if (ts.isIdentifier(x) && depth < 4) {
+        const init = inits.get(x.text);
+        return init !== undefined && isDigestValue(init, inits, depth + 1);
+    }
+    return false;
+}
+function isLiteral(e) {
+    const x = unwrap(e);
+    return (ts.isStringLiteralLike(x) ||
+        ts.isNumericLiteral(x) ||
+        x.kind === ts.SyntaxKind.TrueKeyword ||
+        x.kind === ts.SyntaxKind.FalseKeyword ||
+        x.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(x) && x.text === "undefined"));
+}
+function dbWrites(unit) {
+    const out = [];
+    walk(unit, (x) => {
+        if (!ts.isCallExpression(x))
+            return;
+        const e = unwrap(x.expression);
+        if (!ts.isPropertyAccessExpression(e))
+            return;
+        const m = e.name.text;
+        if (!/^(insert|patch|replace|delete)$/.test(m))
+            return;
+        if (!/\bdb\b/.test(e.expression.getText()))
+            return;
+        const objArg = m === "insert" ? x.arguments[1] : x.arguments[1];
+        const obj = objArg && ts.isObjectLiteralExpression(unwrap(objArg))
+            ? unwrap(objArg)
+            : undefined;
+        out.push({
+            kind: m,
+            ...(m === "insert" ? { table: strArg(x, 0) } : {}),
+            ...(obj ? { obj } : {}),
+            node: x,
+        });
+    });
+    return out;
+}
+function objectKeys(o) {
+    const out = [];
+    for (const p of o.properties) {
+        if (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p)) {
+            const n = p.name;
+            if (ts.isIdentifier(n) || ts.isStringLiteralLike(n))
+                out.push(n.text);
+        }
+        if (ts.isSpreadAssignment(p)) {
+            // `...(cond ? { agentId } : {})` — read the literal keys inside the spread
+            walk(p.expression, (x) => {
+                if (ts.isObjectLiteralExpression(x))
+                    out.push(...objectKeys(x));
+            });
+        }
+    }
+    return out;
+}
+/** Tables a unit queries: `ctx.db.query("T")`. */
+function queriedTables(unit) {
+    const out = new Set();
+    walk(unit, (x) => {
+        if (ts.isCallExpression(x) && methodOf(x) === "query") {
+            const t = strArg(x);
+            if (t)
+                out.add(t);
+        }
+    });
+    return out;
+}
+/** A query chain `ctx.db.query("T")…withIndex(name, cb)` that selects by a hash. */
+function readsByHash(unit) {
+    const out = new Set();
+    walk(unit, (x) => {
+        if (!ts.isCallExpression(x) || methodOf(x) !== "withIndex")
+            return;
+        const idx = strArg(x, 0) ?? "";
+        const cbText = x.arguments[1]?.getText() ?? "";
+        if (!/hash/i.test(idx) && !/hash/i.test(cbText))
+            return;
+        let t;
+        let cur = x;
+        for (;;) {
+            const c = unwrap(cur);
+            if (ts.isCallExpression(c)) {
+                if (methodOf(c) === "query") {
+                    t = strArg(c);
+                    break;
+                }
+                cur =
+                    unwrap(c.expression).expression ?? c;
+                if (cur === c)
+                    break;
+            }
+            else if (ts.isPropertyAccessExpression(c))
+                cur = c.expression;
+            else
+                break;
+        }
+        if (t)
+            out.add(t);
+    });
+    return out;
+}
+function marksRevokedOrDeletes(unit) {
+    return dbWrites(unit).some((w) => w.kind === "delete" ||
+        ((w.kind === "patch" || w.kind === "replace") &&
+            w.obj !== undefined &&
+            objectKeys(w.obj).some((k) => REVOKED_KEY.test(k))));
+}
+export function scanR56(files) {
+    const scan = emptyScan();
+    const ps = files
+        .filter((f) => isJudgeable(f) && isConvexFile(f))
+        .map(parseFile);
+    const units = ps.flatMap(unitsOf);
+    scan.units = units.length;
+    // ---- clause 1 --------------------------------------------------------------
+    for (const u of units) {
+        const inits = localInits(u.node);
+        const writes = dbWrites(u.node).filter((w) => w.kind !== "delete" && w.obj);
+        // secret seeds: args.<SECRET_ARG>, a destructured SECRET_ARG, process.env.*SECRET*
+        const secretSrc = new Map();
+        walk(u.node, (x) => {
+            if (ts.isPropertyAccessExpression(x)) {
+                const base = x.expression.getText();
+                if (/^args$/.test(base) && SECRET_ARG.test(x.name.text))
+                    secretSrc.set(`${base}.${x.name.text}`, `${base}.${x.name.text}`);
+                if (/process\.env$/.test(base) &&
+                    /SECRET|TOKEN|PASSWORD|KEY/.test(x.name.text))
+                    secretSrc.set(`${base}.${x.name.text}`, `${base}.${x.name.text}`);
+            }
+            if (ts.isVariableDeclaration(x) &&
+                ts.isObjectBindingPattern(x.name) &&
+                x.initializer?.getText() === "args")
+                for (const el of x.name.elements)
+                    if (ts.isIdentifier(el.name) && SECRET_ARG.test(el.name.text))
+                        secretSrc.set(el.name.text, `args.${el.name.text}`);
+        });
+        const tainted = new Map();
+        const mentionsSecret = (e) => {
+            let found;
+            walk(e, (x) => {
+                if (found)
+                    return;
+                if (ts.isPropertyAccessExpression(x)) {
+                    const k = x.getText();
+                    if (secretSrc.has(k))
+                        found = secretSrc.get(k);
+                }
+                if (ts.isIdentifier(x)) {
+                    if (secretSrc.has(x.text))
+                        found = secretSrc.get(x.text);
+                    else if (tainted.has(x.text))
+                        found = tainted.get(x.text);
+                }
+            });
+            return found;
+        };
+        for (let pass = 0; pass < 4; pass++)
+            for (const [name, init] of inits) {
+                if (tainted.has(name))
+                    continue;
+                const s = mentionsSecret(init);
+                if (s && !holdsDigest(init))
+                    tainted.set(name, s);
+            }
+        // variables that hold a digest OF a secret
+        const digestOfSecret = new Map();
+        for (const [name, init] of inits) {
+            let src;
+            walk(init, (x) => {
+                if (src || !ts.isCallExpression(x) || !isDigestCall(x))
+                    return;
+                for (const a of x.arguments) {
+                    const s = mentionsSecret(a);
+                    if (s)
+                        src = s;
+                }
+            });
+            if (src)
+                digestOfSecret.set(name, src);
+        }
+        for (const w of writes) {
+            const obj = w.obj;
+            for (const p of obj.properties) {
+                let key;
+                let value;
+                if (ts.isPropertyAssignment(p) &&
+                    (ts.isIdentifier(p.name) || ts.isStringLiteralLike(p.name))) {
+                    key = p.name.text;
+                    value = p.initializer;
+                }
+                else if (ts.isShorthandPropertyAssignment(p)) {
+                    key = p.name.text;
+                    value = p.name;
+                }
+                if (key === undefined || value === undefined)
+                    continue;
+                // (1) a digest of a chosen secret reaches a stored row
+                let viaSecret;
+                walk(value, (x) => {
+                    if (viaSecret)
+                        return;
+                    if (ts.isIdentifier(x) && digestOfSecret.has(x.text))
+                        viaSecret = digestOfSecret.get(x.text);
+                    if (ts.isCallExpression(x) && isDigestCall(x))
+                        for (const a of x.arguments) {
+                            const s = mentionsSecret(a);
+                            if (s)
+                                viaSecret = s;
+                        }
+                });
+                if (viaSecret) {
+                    scan.violate.push({
+                        rel: u.rel,
+                        n: lineOf(p),
+                        note: `${u.name}: (1) persists ${key} as a digest of ${viaSecret}, a chosen secret — an unsalted digest of a chosen secret is an offline-checkable copy of it`,
+                    });
+                    continue;
+                }
+                if (!CRED_KEY.test(key))
+                    continue;
+                if (isLiteral(value))
+                    continue;
+                if (isDigestValue(value, inits)) {
+                    scan.conform.push({
+                        rel: u.rel,
+                        n: lineOf(p),
+                        note: `${u.name}: (1) stores ${key} as a digest`,
+                    });
+                    continue;
+                }
+                const origin = /^args\./.test(unwrap(value).getText())
+                    ? unwrap(value).getText()
+                    : ts.isIdentifier(unwrap(value)) &&
+                        inits.has(unwrap(value).text)
+                        ? `a value built in this function (${inits
+                            .get(unwrap(value).text)
+                            ?.getText()
+                            .replace(/\s+/g, " ")
+                            .slice(0, 40)})`
+                        : unwrap(value).getText().slice(0, 40);
+                scan.violate.push({
+                    rel: u.rel,
+                    n: lineOf(p),
+                    note: `${u.name}: (1) stores the credential ${key} without a digest — ${origin}; a code, token or key is held only as a digest of itself`,
+                });
+            }
+        }
+    }
+    // ---- clause 2: refresh tables ----------------------------------------------
+    const lookups = new Map();
+    const consumers = new Map();
+    for (const u of units) {
+        const byHash = readsByHash(u.node);
+        for (const t of byHash) {
+            if (!/refresh/i.test(t))
+                continue;
+            (lookups.get(t) ?? lookups.set(t, []).get(t))?.push(u);
+            if (marksRevokedOrDeletes(u.node))
+                (consumers.get(t) ?? consumers.set(t, []).get(t))?.push(u);
+        }
+    }
+    for (const [t, ls] of lookups) {
+        const cs = consumers.get(t) ?? [];
+        if (cs.length === 0) {
+            const readers = ls.filter((l) => !marksRevokedOrDeletes(l.node));
+            for (const l of readers)
+                scan.violate.push({
+                    rel: l.rel,
+                    n: l.line,
+                    note: `${l.name}: (2) ${t} is read by hash here and no function in the tree reads it by hash and marks the token consumed or revoked (or deletes it); a stolen refresh token stays replayable for its whole life`,
+                });
+        }
+        else {
+            scan.conform.push({
+                rel: cs[0].rel,
+                n: cs[0].line,
+                note: `${cs[0].name}: (2) ${t} is consumed by hash (${cs.map((c) => c.name).join(", ")})`,
+            });
+        }
+    }
+    const mints = [];
+    for (const u of units)
+        for (const w of dbWrites(u.node)) {
+            if (w.kind !== "insert" || !w.table || !w.obj)
+                continue;
+            const keys = objectKeys(w.obj);
+            if (keys.includes("tokenHash") &&
+                keys.includes("expiresAt") &&
+                !/refresh/i.test(w.table))
+                mints.push({ unit: u, table: w.table, keys, line: lineOf(w.node) });
+        }
+    const revokers = new Map();
+    for (const u of units) {
+        if (!marksRevokedOrDeletes(u.node))
+            continue;
+        for (const t of queriedTables(u.node))
+            (revokers.get(t) ?? revokers.set(t, []).get(t))?.push(u);
+    }
+    const family = new Set(mints
+        .filter((m) => m.keys.some((k) => FAMILY_KEY.test(k)))
+        .map((m) => m.table));
+    const seenMint = new Set();
+    for (const m of mints) {
+        const key = `${m.unit.rel}:${m.unit.name}:${m.table}`;
+        if (seenMint.has(key))
+            continue;
+        seenMint.add(key);
+        const rs = revokers.get(m.table) ?? [];
+        let ok = true;
+        if (rs.length === 0) {
+            ok = false;
+            scan.violate.push({
+                rel: m.unit.rel,
+                n: m.line,
+                note: `${m.unit.name}: (3a) ${m.table} holds bearers (rows with tokenHash and expiresAt) and no function in the tree revokes or deletes a row of it; no bearer can be withdrawn`,
+            });
+        }
+        if (!family.has(m.table)) {
+            const reads = queriedTables(m.unit.node).has(m.table);
+            const revokePrior = reads && marksRevokedOrDeletes(m.unit.node);
+            let cap = false;
+            if (reads) {
+                walk(m.unit.node, (x) => {
+                    if (cap || !ts.isThrowStatement(x))
+                        return;
+                    if (CAP_WORDS.test(x.getText()))
+                        cap = true;
+                    for (let up = x.parent; up && up !== m.unit.node; up = up.parent)
+                        if (ts.isIfStatement(up) &&
+                            /\.length|count/i.test(up.expression.getText()) &&
+                            /\d/.test(up.expression.getText()))
+                            cap = true;
+                });
+            }
+            if (!revokePrior && !cap) {
+                ok = false;
+                scan.violate.push({
+                    rel: m.unit.rel,
+                    n: m.line,
+                    note: `${m.unit.name}: (3b) mints into ${m.table} with neither a revoke-prior nor a cap on a principal's live bearers, and no code or refresh-token exchange links it to a family`,
+                });
+            }
+        }
+        if (ok)
+            scan.conform.push({
+                rel: m.unit.rel,
+                n: m.line,
+                note: `${m.unit.name}: (3) ${m.table} has a revocation door (${rs.map((r) => r.name).join(", ")}) and its mint is bounded${family.has(m.table) ? " by its family (clause 2)" : " (revoke-prior or cap)"}`,
+            });
+    }
+    // ---- clause 4: verification tokens ------------------------------------------
+    for (const u of units) {
+        // request-derived identifiers: params named request/req/args, bodies, and
+        // bindings destructured from them
+        const tainted = new Set(["args", "request", "req", "body"]);
+        for (let pass = 0; pass < 4; pass++)
+            walk(u.node, (x) => {
+                if (!ts.isVariableDeclaration(x) || !x.initializer)
+                    return;
+                const init = x.initializer.getText();
+                const fromReq = /\.json\(\)|\bargs\b|\brequest\b|\breq\b|\bbody\b/.test(init) ||
+                    [...tainted].some((t) => new RegExp(`\\b${t}\\b`).test(init));
+                if (!fromReq)
+                    return;
+                const add = (b) => {
+                    if (ts.isIdentifier(b))
+                        tainted.add(b.text);
+                    else
+                        for (const e of b.elements)
+                            if (!ts.isOmittedExpression(e))
+                                add(e.name);
+                };
+                add(x.name);
+            });
+        const idents = new Set();
+        walk(u.node, (x) => {
+            if (ts.isIdentifier(x) && tainted.has(x.text) && ID_NAME.test(x.text))
+                idents.add(x.text);
+        });
+        if (idents.size === 0)
+            continue;
+        // substring matches of such an identifier
+        const hits = [];
+        walk(u.node, (x) => {
+            if (!ts.isCallExpression(x))
+                return;
+            const m = methodOf(x);
+            if (m !== "includes" && m !== "startsWith" && m !== "indexOf")
+                return;
+            const e = unwrap(x.expression);
+            if (!ts.isPropertyAccessExpression(e))
+                return;
+            const arg = x.arguments[0];
+            if (!arg)
+                return;
+            walk(arg, (y) => {
+                if (ts.isIdentifier(y) && idents.has(y.text))
+                    hits.push({ id: y.text, method: m, node: x });
+            });
+        });
+        const guarded = (id) => {
+            let g = false;
+            walk(u.node, (x) => {
+                if (g)
+                    return;
+                if (ts.isCallExpression(x) && methodOf(x) === "test") {
+                    const re = unwrap(x.expression);
+                    if (ts.isPropertyAccessExpression(re) &&
+                        ts.isRegularExpressionLiteral(re.expression) &&
+                        /\{(40|64)(,\d*)?\}/.test(re.expression.text) &&
+                        new RegExp(`\\b${id}\\b`).test(x.arguments.map((a) => a.getText()).join(" ")))
+                        g = true;
+                }
+                if (ts.isBinaryExpression(x)) {
+                    const both = `${x.left.getText()} ${x.right.getText()}`;
+                    if (new RegExp(`\\b${id}\\b`).test(both) &&
+                        /\.length/.test(both) &&
+                        /\b(40|64)\b/.test(both) &&
+                        both.length < 200)
+                        g = true;
+                }
+            });
+            return g;
+        };
+        const reported = new Set();
+        for (const h of hits) {
+            if (reported.has(h.id))
+                continue;
+            reported.add(h.id);
+            if (guarded(h.id))
+                scan.conform.push({
+                    rel: u.rel,
+                    n: lineOf(h.node),
+                    note: `${u.name}: (4) matches ${h.id} after a full-length (40 or 64 digit) check`,
+                });
+            else
+                scan.violate.push({
+                    rel: u.rel,
+                    n: lineOf(h.node),
+                    note: `${u.name}: (4) matches the request-supplied ${h.id} against stored text with .${h.method}() and no full-length (40 or 64 digit) check; a one-character prefix that occurs anywhere in the text verifies`,
+                });
+        }
+        if (hits.length > 0 || [...idents].some((i) => /sha|commit/i.test(i))) {
+            const echoes = [];
+            walk(u.node, (x) => {
+                if (!ts.isCallExpression(x))
+                    return;
+                const callee = x.expression.getText();
+                if (!/Response/.test(callee))
+                    return;
+                walk(x, (y) => {
+                    if (ts.isPropertyAssignment(y) &&
+                        ts.isIdentifier(y.name) &&
+                        ECHO_KEY.test(y.name.text) &&
+                        !isLiteral(y.initializer))
+                        echoes.push(`${y.name.text} (line ${lineOf(y)})`);
+                });
+            });
+            if (echoes.length)
+                scan.violate.push({
+                    rel: u.rel,
+                    n: u.line,
+                    note: `${u.name}: (4e) a verification response discloses stored content — ${[...new Set(echoes)].slice(0, 6).join(", ")}; a refused verification names a reason code and nothing stored`,
+                });
+        }
+    }
+    return scan;
+}
+export const R56 = {
+    id: R56_ID,
+    run: (tree) => {
+        const s = scanR56(tree.files);
+        const n = tree.files.filter((f) => isJudgeable(f) && isConvexFile(f)).length;
+        const empty = `R-56: no applicable site — ${n} convex file(s) read (${s.units} unit(s)); none stores a credential-named column, reads a refresh-token table by hash, inserts a bearer row (tokenHash and expiresAt), or matches a request-supplied commit identifier. NOT a clean bill.`;
+        return decide("R-56", R56_ID, R56_CHECK, s, empty);
+    },
+};
+export const SOURCE_CREDENTIAL_HYGIENE_DETECTORS = [
+    { detector: R56, ruleId: "R-56", standardPin: R56_STANDARD_PIN },
+];

package/dist/detectors/source/local-identity.js

@@ -15,6 +15,11 @@
 // doctor-owned control: own section, own sidecar entry, drives the exit code.
 // CR-2 is the next free number of that family. Upstreaming it as R-N is a
 // separate change to the standard document in its own repository.
+// UPSTREAMED: the standard at bacc54a (fixtures/backend-standard-bacc54a.md)
+// defines this rule as R-57. The key stays CR-2 because the vantage-peers
+// deploy-gate baseline reads CR-2; R-57 is listed in src/not-checkable.ts with
+// that reason so one defect is never counted as two rules. Renaming the key to
+// R-57 is a follow-up that moves that baseline in the same delivery.
 //
 // WHAT IS A SITE. One site per function that DEFINES a primitive: the innermost
 // named function holding the deciding node (a helper, an MCP tool handler, or a
@@ -61,7 +66,7 @@
 // nowhere (neither here nor through R-53), never counted as a pass. An empty
 // population is could-not-judge, never a clean bill.
 //
-// CEILING 0. CR-2 is mechanical (fixtures/rule-classes-2825122.json): any
+// CEILING 0. CR-2 is mechanical (fixtures/rule-classes-bacc54a.json): any
 // violation is a mechanical violation, counted in mechanical_rule_counts with a
 // per-module split, and gives a non-zero exit.
 import * as ts from "typescript";

package/dist/detectors/source/narrow-then-bound.d.ts

@@ -0,0 +1,11 @@
+import type { Detector } from "../../engine-types.js";
+import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+export declare const R55_ID = "R-55 a read narrows by every predicate before it bounds the result; an aggregate is computed over the narrowed set";
+export declare const R55_STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa \u00A74 R-55";
+export interface R55Scan extends Scan {
+    /** functions read that hold a bounded read. */
+    bounded: number;
+}
+export declare function scanR55(files: SrcFile[]): R55Scan;
+export declare const R55: Detector;
+export declare const SOURCE_NARROW_THEN_BOUND_DETECTORS: SourceDetectorEntry[];