@nifrajs/cli 4.0.2 → 5.1.0

package/dist/rules/security.js

@@ -1,7 +1,9 @@
+import { BACKEND_APP_FILE } from "../app-files.js";
 import { isBrowserSource } from "../check-scan.js";
 import { diagnostic } from "../diagnostics.js";
+import { createWebAppProbe } from "../internal/nifra-project.js";
 import { scriptKindOf } from "../internal/script-kind.js";
-import { commentBlockHasMarker } from "./comment-markers.js";
+import { commentBlockExpectation, commentBlockHasMarker, MISSING_EXPECTATION_REASON, } from "./comment-markers.js";
 import { loadRuleTypeScript } from "./typescript.js";
 /**
  * A security rule that cannot run says so as an advisory finding instead of silently returning no
@@ -21,36 +23,51 @@ function didNotRun(code, title) {
 }
 const SECRET = /(?:token|secret|apiKey|api_key|signature|hmac|password)/i;
 const PII = /(?:email|phone|ssn|password|token|authorization)/i;
-const REVIEWED = "@nifra-gate-reviewed";
+// Retired in 5.0.0: it silenced any security finding without a reason. It now silences nothing and
+// only makes the finding name the form that replaced it.
+const RETIRED_REVIEW_MARKER = "@nifra-gate-reviewed";
 const parseCache = new WeakMap();
-// The marker counts anywhere in the contiguous comment block above the finding (or trailing on its
-// line) - a human writing the multi-line justification the hatch asks for must not un-suppress the
-// finding by growing the comment past two lines.
-function hasReview(lines, line) {
-    return commentBlockHasMarker(lines, line, REVIEWED);
+/**
+ * The reason a `nifra-expect <code>: <reason>` comment on or above `line` gives for a security
+ * finding. Every security hatch needs the reason: a comment without one silences nothing.
+ */
+function expectedReason(lines, line, code) {
+    return commentBlockExpectation(lines, line, [code])?.reason;
+}
+/** The evidence a silenced finding carries: the comment that silenced it, reason included. */
+function expectationEvidence(lines, line, code) {
+    const reason = expectedReason(lines, line, code);
+    return reason === undefined ? [] : [`nifra-expect ${code}: ${reason}`];
 }
-function reviewedEvidence(lines, line) {
-    return hasReview(lines, line) ? [REVIEWED] : [];
+/** An unsilenced finding's message, plus why a hatch comment written for it does not count. */
+function unexpectedMessage(message, lines, line, code) {
+    if (commentBlockExpectation(lines, line, [code]) !== undefined)
+        return `${message}; ${MISSING_EXPECTATION_REASON}`;
+    if (commentBlockHasMarker(lines, line, RETIRED_REVIEW_MARKER))
+        return `${message}; ${RETIRED_REVIEW_MARKER} no longer silences a finding - after review, write // nifra-expect ${code}: <reason>`;
+    return message;
 }
+const parentOf = (dir) => dir.slice(0, Math.max(dir.lastIndexOf("/"), 0));
 /**
- * NF-S002 severity by file role. Server-side code compares real secret material - a timing oracle
- * there is exploitable, so it fails the gate. Browser code (a route's frontend half, `frontend/`)
- * compares values the client already holds, so the same shape is advisory rather than a gate
- * failure. `shared/` also runs on the server, and a file that cannot be classified is treated as
- * server - fail closed.
+ * Whether NF-S001 and NF-S002 may treat `file` as browser code, where a finding is advisory: a
+ * browser compares values the client already holds, and a gate there that fails open grants nothing
+ * the server does not check again. It must be browser code by path (a route's frontend half,
+ * `frontend/`) and sit inside a nifra web app: a `routes/` folder in an API-only project or a package
+ * without a web dependency runs on the server. `shared/` also runs on the server, and a file that
+ * cannot be classified is treated as server - fail closed.
  */
-function secretComparisonSeverity(file) {
+export function provenBrowserFile(root, file, inWebApp = createWebAppProbe(root)) {
     const path = file.replaceAll("\\", "/");
     if (!isBrowserSource(path) || /\.server\.[cm]?[tj]sx?$/.test(path))
-        return "error";
+        return false;
     if (/\.shared\.[^/]+$/.test(path) || /(?:^|\/)shared\//.test(path))
-        return "error";
-    return "warn";
+        return false;
+    return inWebApp(parentOf(path));
 }
 const CONFIRMATION_NAME = /^(?:confirm|confirmation|confirmPassword|passwordConfirmation|passwordConfirm|passwordRepeat|repeatPassword)$/i;
 /** Client form confirmation compares two values already held by the browser, not secret material. */
-function isClientConfirmationPair(file, left, right) {
-    if (secretComparisonSeverity(file) !== "warn")
+function isClientConfirmationPair(browser, left, right) {
+    if (!browser)
         return false;
     const names = [left, right];
     return (names.some((name) => name?.toLowerCase() === "password") &&
@@ -85,8 +102,9 @@ function secretName(ts, node) {
  * Presence checks (`token === undefined`, `secret == null`, `apiKey !== ""`) and `typeof` guards are
  * not equality over secret material - rewriting them to a timing-safe comparison would break the code.
  * A comparison against a numeric literal (`signature !== 1`, `signatureLength !== 64`) is a
- * length/version/discriminant check, never a secret: secrets are strings or bytes, so a number on
- * either side proves this is not the compare a timing oracle applies to.
+ * length/version/discriminant check, and one against `true`/`false` (`persistRefreshToken === true`)
+ * is a flag check: secrets are strings or bytes, so a number or a boolean on either side proves this
+ * is not the compare a timing oracle applies to.
  */
 function isPresenceComparison(ts, node) {
     for (const side of [node.left, node.right]) {
@@ -94,6 +112,8 @@ function isPresenceComparison(ts, node) {
             return true;
         if (side.kind === ts.SyntaxKind.NullKeyword)
             return true;
+        if (side.kind === ts.SyntaxKind.TrueKeyword || side.kind === ts.SyntaxKind.FalseKeyword)
+            return true;
         if (ts.isStringLiteralLike(side) && side.text === "")
             return true;
         if (ts.isTypeOfExpression(side))
@@ -127,7 +147,131 @@ function parsedFile(ts, sources, file) {
     files.set(file, parsed);
     return parsed;
 }
-function secretComparisons(ts, file, tree) {
+// The last word of a name that states a fact about a secret rather than holding it: `tokenType`,
+// `SECRET_CAP_SQLSTATE`, `apiKeyIds`, `apiKeyHeaderName`. Exact words only, so the secret word anywhere
+// else still matches (`tokenValue`, `passwordHash`, `apiKeyHeader`). `code`, `url`, `path` and `prefix`
+// stay out: an OTP, a capability URL and a prefix compare all leak secret material.
+const NON_MATERIAL_WORD = new Set([
+    "type",
+    "kind",
+    "name",
+    "id",
+    "ids",
+    "length",
+    "len",
+    "count",
+    "size",
+    "mode",
+    "policy",
+    "version",
+    "sqlstate",
+    "status",
+    "enabled",
+    "required",
+    "ttl",
+    "expiry",
+    "expires",
+]);
+function lastWord(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .split(/[\s_$-]+/);
+    return (words.findLast((word) => word !== "") ?? "").toLowerCase();
+}
+function isSecretName(name) {
+    return name !== undefined && SECRET.test(name) && !NON_MATERIAL_WORD.has(lastWord(name));
+}
+/** Whether `name` binds a declaration in `statements` itself (not in a nested scope). */
+function declaresIn(ts, statements, name) {
+    return statements.some((statement) => {
+        if (ts.isVariableStatement(statement))
+            return statement.declarationList.declarations.some((d) => bindsName(ts, d.name, name));
+        if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement))
+            return statement.name?.text === name;
+        return false;
+    });
+}
+function bindsName(ts, binding, name) {
+    if (ts.isIdentifier(binding))
+        return binding.text === name;
+    return binding.elements.some((element) => !ts.isOmittedExpression(element) && bindsName(ts, element.name, name));
+}
+/**
+ * Whether `id` names a plain parameter of an enclosing function, not a value the file builds: the
+ * nearest declaration of the name, walking out, must be that parameter. A loop or catch variable, a
+ * local or a destructured parameter in between disproves it.
+ */
+function isParameterRef(ts, id) {
+    for (let node = id.parent; node !== undefined; node = node.parent) {
+        if (ts.isFunctionLike(node)) {
+            for (const parameter of node.parameters) {
+                if (ts.isIdentifier(parameter.name)) {
+                    if (parameter.name.text === id.text)
+                        return true;
+                }
+                else if (bindsName(ts, parameter.name, id.text))
+                    return false;
+            }
+        }
+        if ((ts.isBlock(node) || ts.isSourceFile(node)) && declaresIn(ts, node.statements, id.text))
+            return false;
+        if ((ts.isForStatement(node) || ts.isForOfStatement(node) || ts.isForInStatement(node)) &&
+            node.initializer !== undefined &&
+            ts.isVariableDeclarationList(node.initializer) &&
+            node.initializer.declarations.some((d) => bindsName(ts, d.name, id.text)))
+            return false;
+        if (ts.isCatchClause(node) &&
+            node.variableDeclaration !== undefined &&
+            bindsName(ts, node.variableDeclaration.name, id.text))
+            return false;
+    }
+    return false;
+}
+const CONFIG_KEY = /^[A-Z][A-Z0-9_]*$/;
+const CONTEXT_NAMES = new Set(["c", "ctx", "context"]);
+/**
+ * Whether `node` reads deployment configuration: `process.env.X`, `Bun.env.X`, `import.meta.env.X`,
+ * `Deno.env.get("X")`, `c.env.UPPER_SNAKE` (also `ctx`/`context`), or `env.X`, where `c` and `env` must
+ * be parameters of an enclosing function, never values the file builds. Comparing two such reads
+ * involves no request value, so it is no timing oracle (a startup "keys must differ" check).
+ */
+function isConfigRead(ts, node) {
+    if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        const [key] = node.arguments;
+        return (ts.isPropertyAccessExpression(callee) &&
+            callee.name.text === "get" &&
+            ts.isPropertyAccessExpression(callee.expression) &&
+            callee.expression.name.text === "env" &&
+            ts.isIdentifier(callee.expression.expression) &&
+            callee.expression.expression.text === "Deno" &&
+            node.arguments.length === 1 &&
+            key !== undefined &&
+            ts.isStringLiteralLike(key));
+    }
+    let key;
+    if (ts.isPropertyAccessExpression(node))
+        key = node.name.text;
+    else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression))
+        key = node.argumentExpression.text;
+    else
+        return false;
+    const object = node.expression;
+    if (ts.isIdentifier(object))
+        return object.text === "env" && isParameterRef(ts, object);
+    if (!ts.isPropertyAccessExpression(object) || object.name.text !== "env")
+        return false;
+    const owner = object.expression;
+    if (ts.isMetaProperty(owner))
+        return owner.name.text === "meta";
+    if (!ts.isIdentifier(owner))
+        return false;
+    if (owner.text === "process" || owner.text === "Bun")
+        return true;
+    return CONTEXT_NAMES.has(owner.text) && CONFIG_KEY.test(key) && isParameterRef(ts, owner);
+}
+function secretComparisons(ts, tree, browser) {
     const operators = [
         ts.SyntaxKind.EqualsEqualsEqualsToken,
         ts.SyntaxKind.ExclamationEqualsEqualsToken,
@@ -141,9 +285,9 @@ function secretComparisons(ts, file, tree) {
             !isPresenceComparison(ts, node)) {
             const left = secretName(ts, node.left);
             const right = secretName(ts, node.right);
-            if (((left !== undefined && SECRET.test(left)) ||
-                (right !== undefined && SECRET.test(right))) &&
-                !isClientConfirmationPair(file, left, right)) {
+            if ((isSecretName(left) || isSecretName(right)) &&
+                !isClientConfirmationPair(browser, left, right) &&
+                !(isConfigRead(ts, node.left) && isConfigRead(ts, node.right))) {
                 const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1;
                 found.push({ node, left, right, line });
             }
@@ -171,11 +315,12 @@ function timingSafeHelper(file) {
  * Rewrite every unreviewed NF-S002 comparison in one file to `nifraTimingSafeEqual(left, right)` and
  * add the helper once. Sites come from the syntax tree, not a reported line: the helper lands above
  * them, so a line number a check run reported no longer names the same statement after the first fix.
+ * `browser` is {@link provenBrowserFile} for the file, so the fix rewrites exactly what check reported.
  */
-export function rewriteSecretComparisons(ts, file, source) {
+export function rewriteSecretComparisons(ts, file, source, browser) {
     const tree = parse(ts, file, source);
     const lines = tree.text.split("\n");
-    const sites = secretComparisons(ts, file, tree).filter((site) => !hasReview(lines, site.line));
+    const sites = secretComparisons(ts, tree, browser).filter((site) => expectedReason(lines, site.line, "NF-S002") === undefined);
     // A comparison nested inside another (`(token === a) === flag`) is left for the next run, so every
     // edit below covers a disjoint range and applying them from the end keeps earlier offsets valid.
     const outer = sites.filter(({ node }) => !sites.some((other) => other.node !== node && other.node.pos >= node.pos && other.node.end <= node.end));
@@ -213,22 +358,27 @@ export const secretComparisonRule = {
         if (ts === undefined)
             return didNotRun("NF-S002", "Non-constant-time secret comparison scan");
         const findings = [];
+        const webDirs = createWebAppProbe(ctx.root);
         for (const file of ctx.project.source.files) {
             const parsed = parsedFile(ts, ctx.project.source, file);
             if (parsed === undefined)
                 continue;
             const { tree, lines } = parsed;
-            for (const { left, right, line } of secretComparisons(ts, file, tree)) {
-                const reviewed = hasReview(lines, line);
+            const browser = provenBrowserFile(ctx.root, file, webDirs);
+            for (const { left, right, line } of secretComparisons(ts, tree, browser)) {
+                const reviewed = expectedReason(lines, line, "NF-S002") !== undefined;
                 findings.push(diagnostic({
                     code: "NF-S002",
-                    severity: reviewed ? "info" : secretComparisonSeverity(file),
+                    severity: reviewed ? "info" : browser ? "warn" : "error",
                     file,
                     line,
                     message: reviewed
-                        ? "secret comparison is explicitly marked as reviewed"
-                        : "secret-like values must use a length check and timing-safe comparison",
-                    evidence: [left ?? right ?? "secret comparison", ...reviewedEvidence(lines, line)],
+                        ? "secret comparison is expected here"
+                        : unexpectedMessage("secret-like values must use a length check and timing-safe comparison", lines, line, "NF-S002"),
+                    evidence: [
+                        left ?? right ?? "secret comparison",
+                        ...expectationEvidence(lines, line, "NF-S002"),
+                    ],
                     ...(reviewed
                         ? {}
                         : {
@@ -271,16 +421,16 @@ export const piiLogRule = {
                             const name = nameOf(ts, arg);
                             if (name !== undefined && PII.test(name)) {
                                 const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1;
-                                const reviewed = hasReview(lines, line);
+                                const reviewed = expectedReason(lines, line, "NF-S003") !== undefined;
                                 findings.push(diagnostic({
                                     code: "NF-S003",
                                     severity: reviewed ? "info" : "warn",
                                     file,
                                     line,
                                     message: reviewed
-                                        ? "sensitive value in log call is explicitly marked as reviewed"
-                                        : "PII-shaped values must not be passed directly to log calls",
-                                    evidence: [name, ...reviewedEvidence(lines, line)],
+                                        ? "sensitive value in log call is expected here"
+                                        : unexpectedMessage("PII-shaped values must not be passed directly to log calls", lines, line, "NF-S003"),
+                                    evidence: [name, ...expectationEvidence(lines, line, "NF-S003")],
                                     verify: "nifra check --lints-only",
                                 }));
                             }
@@ -313,6 +463,89 @@ function functionName(ts, fn) {
         return binding.name.text;
     return undefined;
 }
+/**
+ * A gate's name. `can` only names a gate in camelCase (`canEdit`, `canAccess`) - matching it
+ * case-insensitively swept in `canonicalize…`, `cancel…`, `candidate…`, none of them authorization
+ * decisions. `ensure`/`verify`/`check`/`validate` name one only before what a gate decides on
+ * (`verifyToken`, `ensureLoggedIn`, `checkPermission`), so `ensureDir` and `checkHealth` are not gates.
+ */
+const GATE_NAMES = [
+    /^(?:require|assert|authori[sz]e|authenticate)/i,
+    /^can[A-Z]/,
+    /.Guard$/,
+    /^(?:ensure|verify|check|validate)(?:Auth\w*|LoggedIn|Login|Session|Token|Jwt|JWT|Signatures?|Webhook|Hmac|HMAC|Password|Credentials?|Permissions?|Access|Roles?|Admin(?:istrator)?|Owner(?:ship)?|Scopes?|Csrf|CSRF|ApiKey|Origin|Tenant|User|Member(?:ship)?)(?![a-z])/,
+];
+/** An authenticator returns who is calling, so its "nobody" result (`null`, `undefined`) is a denial. */
+const AUTHENTICATOR = /^authenticate/i;
+/** Result-object fields whose `false` is the denial (`{ ok: false, error }`). */
+const DECISION_FIELDS = new Set([
+    "ok",
+    "allowed",
+    "authorized",
+    "authenticated",
+    "valid",
+    "success",
+    "granted",
+]);
+/** Helpers whose whole job is to fail (`fail(…)`, `deny(…)`, `reject(…)`, …). */
+const FAILING_HELPERS = new Set(["fail", "deny", "reject", "forbid", "unauthorized", "abort"]);
+/**
+ * Whether a gate's catch block fails closed: it throws, returns `false`, a result object whose decision
+ * field is `false`, a `new Response(…)` or a `deny…(…)` call (an authenticator also `null` or
+ * nothing), or hands the failure to a {@link FAILING_HELPERS} helper. The last form is why
+ * conformance/invariant asserts that funnel every error through a `never`-returning `fail()` are not
+ * fail-open - the scanner reads no types, so it trusts the helper by name, the same trade the SQL and
+ * gate-name heuristics already make. Read from the syntax, so a "throw" in a comment or a string counts
+ * for nothing, and a nested function's statements are not the catch's own.
+ */
+function failsClosed(ts, block, gate) {
+    const authenticator = AUTHENTICATOR.test(gate);
+    let closed = false;
+    const visit = (node) => {
+        if (closed || ts.isFunctionLike(node))
+            return;
+        if (ts.isThrowStatement(node) ||
+            (ts.isReturnStatement(node) &&
+                (node.expression === undefined
+                    ? authenticator
+                    : isDenial(ts, node.expression, authenticator))) ||
+            (ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                FAILING_HELPERS.has(node.expression.text))) {
+            closed = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(block);
+    return closed;
+}
+function isDenial(ts, expression, authenticator) {
+    let value = expression;
+    while (ts.isParenthesizedExpression(value) ||
+        ts.isAwaitExpression(value) ||
+        ts.isAsExpression(value) ||
+        ts.isSatisfiesExpression(value))
+        value = value.expression;
+    if (value.kind === ts.SyntaxKind.FalseKeyword)
+        return true;
+    if (authenticator &&
+        (value.kind === ts.SyntaxKind.NullKeyword ||
+            ts.isVoidExpression(value) ||
+            (ts.isIdentifier(value) && value.text === "undefined")))
+        return true;
+    if (ts.isObjectLiteralExpression(value)) {
+        return value.properties.some((property) => ts.isPropertyAssignment(property) &&
+            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+            DECISION_FIELDS.has(property.name.text) &&
+            property.initializer.kind === ts.SyntaxKind.FalseKeyword);
+    }
+    if (ts.isNewExpression(value))
+        return ts.isIdentifier(value.expression) && value.expression.text === "Response";
+    return (ts.isCallExpression(value) &&
+        ts.isIdentifier(value.expression) &&
+        value.expression.text.startsWith("deny"));
+}
 export const failOpenGateRule = {
     code: "NF-S001",
     title: "Fail-open gate",
@@ -324,45 +557,37 @@ export const failOpenGateRule = {
         if (ts === undefined)
             return didNotRun("NF-S001", "Fail-open gate scan");
         const findings = [];
+        const webDirs = createWebAppProbe(ctx.root);
         for (const file of ctx.project.source.files) {
             const parsed = parsedFile(ts, ctx.project.source, file);
             if (parsed === undefined)
                 continue;
             const { tree, lines } = parsed;
+            let browser;
             const visit = (node) => {
                 if (ts.isCatchClause(node)) {
                     let parent = node.parent;
                     while (parent !== undefined && !ts.isFunctionLike(parent))
                         parent = parent.parent;
                     const name = parent === undefined ? undefined : functionName(ts, parent);
-                    // `can` only names a gate in camelCase (`canEdit`, `canAccess`) - matching it
-                    // case-insensitively swept in `canonicalize…`, `cancel…`, `candidate…`, none of them
-                    // authorization decisions. The other roots stay case-insensitive.
-                    const gateName = name !== undefined &&
-                        (/^(?:require|assert|authorize)/i.test(name) || /^can[A-Z]/.test(name));
-                    if (name !== undefined && gateName) {
-                        const text = node.block.getText(tree);
-                        // A catch fails closed when it rethrows, returns an explicit denial, or hands the failure
-                        // to a helper whose whole job is to fail (`fail(…)`, `deny(…)`, `reject(…)`, …). The last
-                        // form is why conformance/invariant asserts that funnel every error through a
-                        // `never`-returning `fail()` are not fail-open - the scanner reads no types, so it trusts
-                        // the helper by name, the same trade the SQL and gate-name heuristics already make.
-                        if (!/\b(?:throw|return\s+(?:false|new\s+Response|deny))/s.test(text) &&
-                            !/(?:^|[^.\w])(?:fail|deny|reject|forbid|unauthorized|abort)\s*\(/s.test(text)) {
+                    if (name !== undefined && GATE_NAMES.some((gate) => gate.test(name))) {
+                        if (!failsClosed(ts, node.block, name)) {
                             const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1;
-                            const reviewed = hasReview(lines, line);
+                            const reviewed = expectedReason(lines, line, "NF-S001") !== undefined;
+                            browser ??= provenBrowserFile(ctx.root, file, webDirs);
                             findings.push(diagnostic({
                                 code: "NF-S001",
-                                severity: reviewed ? "info" : "error",
+                                severity: reviewed ? "info" : browser ? "warn" : "error",
                                 file,
                                 line,
                                 message: reviewed
-                                    ? "gate catch block is explicitly marked as reviewed"
-                                    : "gate catch blocks must rethrow or return an explicit denial",
+                                    ? "gate catch block is expected here"
+                                    : unexpectedMessage("gate catch blocks must rethrow or return an explicit denial", lines, line, "NF-S001"),
                                 evidence: [
                                     name,
                                     "catch block has no denial or rethrow",
-                                    ...reviewedEvidence(lines, line),
+                                    ...(browser ? ["browser code: the server's own gate decides"] : []),
+                                    ...expectationEvidence(lines, line, "NF-S001"),
                                 ],
                                 verify: "nifra check --lints-only",
                             }));
@@ -427,16 +652,19 @@ export const corsOriginPredicateRule = {
                                         : false;
                                 if (ignoresOrigin) {
                                     const line = tree.getLineAndCharacterOfPosition(prop.getStart(tree)).line + 1;
-                                    const reviewed = hasReview(lines, line);
+                                    const reviewed = expectedReason(lines, line, "NF-S004") !== undefined;
                                     findings.push(diagnostic({
                                         code: "NF-S004",
                                         severity: reviewed ? "info" : "warn",
                                         file,
                                         line,
                                         message: reviewed
-                                            ? "constant CORS origin predicate is explicitly marked as reviewed"
-                                            : "CORS origin predicate never inspects the origin - it allows every origin; list explicit origins or use the argument",
-                                        evidence: ["origin predicate", ...reviewedEvidence(lines, line)],
+                                            ? "constant CORS origin predicate is expected here"
+                                            : unexpectedMessage("CORS origin predicate never inspects the origin - it allows every origin; list explicit origins or use the argument", lines, line, "NF-S004"),
+                                        evidence: [
+                                            "origin predicate",
+                                            ...expectationEvidence(lines, line, "NF-S004"),
+                                        ],
                                         verify: "nifra check --lints-only",
                                     }));
                                 }
@@ -477,16 +705,16 @@ export const externalRedirectRule = {
                                 nameOf(ts, prop.name) === "external" &&
                                 prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
                                 const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1;
-                                const reviewed = hasReview(lines, line);
+                                const reviewed = expectedReason(lines, line, "NF-S005") !== undefined;
                                 findings.push(diagnostic({
                                     code: "NF-S005",
                                     severity: reviewed ? "info" : "warn",
                                     file,
                                     line,
                                     message: reviewed
-                                        ? "external redirect is explicitly marked as reviewed"
-                                        : "redirect opts out of the same-origin default - verify the target can never be derived from request input (open-redirect risk)",
-                                    evidence: ["external: true", ...reviewedEvidence(lines, line)],
+                                        ? "external redirect is expected here"
+                                        : unexpectedMessage("redirect opts out of the same-origin default - verify the target can never be derived from request input (open-redirect risk)", lines, line, "NF-S005"),
+                                    evidence: ["external: true", ...expectationEvidence(lines, line, "NF-S005")],
                                     verify: "nifra check --lints-only",
                                 }));
                             }
@@ -527,16 +755,16 @@ export const assuranceEscapeHatchRule = {
                     const consequence = name !== undefined ? ESCAPE_HATCHES[name] : undefined;
                     if (name !== undefined && consequence !== undefined) {
                         const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1;
-                        const reviewed = hasReview(lines, line);
+                        const reviewed = expectedReason(lines, line, "NF-S006") !== undefined;
                         findings.push(diagnostic({
                             code: "NF-S006",
                             severity: reviewed ? "info" : "warn",
                             file,
                             line,
                             message: reviewed
-                                ? `${name} escape hatch is explicitly marked as reviewed`
-                                : `${name}: ${consequence}`,
-                            evidence: [name, ...reviewedEvidence(lines, line)],
+                                ? `${name} escape hatch is expected here`
+                                : unexpectedMessage(`${name}: ${consequence}`, lines, line, "NF-S006"),
+                            evidence: [name, ...expectationEvidence(lines, line, "NF-S006")],
                             verify: "nifra check --lints-only",
                         }));
                     }
@@ -599,6 +827,21 @@ export const unprefixedSecureCookieRule = {
         return findings;
     },
 };
+/** Reads the backend the contract-lock check loaded; this rule runs no project code of its own. */
+export const inputBeforeAuthenticationRule = {
+    code: "NF-S008",
+    title: "Authenticated route validates input before authentication",
+    async scan(ctx) {
+        return (ctx.project.check.contracts.inputBeforeAuth ?? []).map((route) => diagnostic({
+            code: "NF-S008",
+            severity: "warn",
+            file: BACKEND_APP_FILE,
+            message: `${route} authenticates in a hook that runs after its declared input is validated, so an unauthenticated caller reaches the body parser and reads the validation issues. Authenticate with \`app.authenticate()\` (the first-party auth middleware already does), or set \`validationOrder: "auth-before-validation"\` on the route so its hooks run first`,
+            evidence: [route],
+            verify: "nifra check --lints-only",
+        }));
+    },
+};
 export const securityRules = Object.freeze([
     failOpenGateRule,
     secretComparisonRule,
@@ -607,5 +850,6 @@ export const securityRules = Object.freeze([
     externalRedirectRule,
     assuranceEscapeHatchRule,
     unprefixedSecureCookieRule,
+    inputBeforeAuthenticationRule,
 ]);
 //# sourceMappingURL=security.js.map