@starci/eslint-canon-be 3.3.0 → 3.4.0

package/default-deny.mjs

@@ -9,17 +9,61 @@
  *   - `public-needs-reason` refuses `@Public()` without `{ reason: PublicReason.X }`, where `PublicReason` is the enum
  *     `domain/identity` exports (judged by the enum's declaring owner, type-aware). An open door states why it is open
  *     from a closed list, so the open doors can be read and reviewed; a string or another enum is refused.
+ *   - `public-reason-closed` holds `PublicReason` to Health, AuthHandshake, SignedWebhook and CatalogRead.
+ *     API-key and tool-token doors authenticate through their own guard instead of extending this enum.
  *
  * The `APP_GUARD` registration and the app-level guard live in the composition check, not here: a rule reading
  * one file cannot see which module the app registered.
  */
 import { isTransportSlot } from "./lib/transport-slots.mjs"
 import { decoratorName, keyName } from "./lib/ast.mjs"
-import { isOwnedEnumMember } from "./lib/declared.mjs"
+import { isOwnedBy, isOwnedEnumMember, isOwnedType, partsOf, typeOf } from "./lib/declared.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { isDeclarationFile, normalizePath } from "./lib/path.mjs"
+import { typed } from "./lib/types.mjs"
 
 const BODY_DECORATORS = new Set(["Body", "Args"])
+const PUBLIC_REASONS = new Set(["Health", "AuthHandshake", "SignedWebhook", "CatalogRead"])
+const REASON_WRAPPERS = new Set(["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression"])
+
+/** The reason expression supplied to a public decorator, or null when it supplies none. */
+const publicReasonOf = (node) => {
+    const expression = node.expression
+    const argument = expression.type === "CallExpression" ? expression.arguments[0] : undefined
+    if (argument?.type !== "ObjectExpression") return null
+    const property = argument.properties.find((item) => item.type === "Property" && !item.computed && keyName(item.key) === "reason")
+    return property ? property.value : null
+}
+
+/** A static member name; a computed identifier is an expression rather than the member's name. */
+const staticMemberName = (node) => {
+    if (node.computed && node.property.type !== "Literal") return null
+    return keyName(node.property)
+}
+
+/** All declared names of the enum, including TypeScript's merged declarations. */
+const publicReasonNames = (context, node) => {
+    const { checker, toTs } = typed(context)
+    const declaration = toTs(node)
+    const symbol = checker.getSymbolAtLocation(declaration.name)
+    const members = (symbol?.declarations ?? []).flatMap((part) => part.members ?? [])
+    return new Set(members.map((member) => member.name.text))
+}
+
+/** Reject added enum members even when the expression is an alias or a union of reasons. */
+const hasAddedPublicReason = (context, reason) => {
+    let value = reason
+    while (REASON_WRAPPERS.has(value.type)) value = value.expression
+    // A stale or not-yet-declared member has an error type, but its enum receiver still has an owner.
+    if (value.type === "MemberExpression" && isOwnedType(context, value.object, "PublicReason", "domain", "identity")) {
+        const name = staticMemberName(value)
+        if (name !== null && !PUBLIC_REASONS.has(name)) return true
+    }
+    if (isOwnedEnumMember(context, reason, "PublicReason", "domain", "identity")) {
+        return partsOf(typeOf(context, reason)).some((part) => !PUBLIC_REASONS.has(part.getSymbol()?.name))
+    }
+    return false
+}
 
 const isUntyped = (annotation) => {
     if (!annotation) return true
@@ -95,27 +139,54 @@ export const publicNeedsReason = {
         return {
             Decorator(node) {
                 if (decoratorName(node) !== "Public") return
-                const expression = node.expression
-                const argument = expression.type === "CallExpression" ? expression.arguments[0] : undefined
-                let reason = null
-                if (argument?.type === "ObjectExpression") {
-                    const property = argument.properties.find((item) => item.type === "Property" && !item.computed && keyName(item.key) === "reason")
-                    reason = property ? property.value : null
-                }
+                const reason = publicReasonOf(node)
                 if (reason === null || !isOwnedEnumMember(context, reason, "PublicReason", "domain", "identity")) context.report({ node, messageId: "reason" })
             },
         }
     },
 }
 
+/** The identity enum and each public door use exactly the canon's four reasons. */
+export const publicReasonClosed = {
+    meta: {
+        type: "problem",
+        docs: { description: "`PublicReason` is closed to Health, AuthHandshake, SignedWebhook and CatalogRead in both editions." },
+        schema: [],
+        messages: {
+            closed: "BE_PUBLIC_REASON_CLOSED: `PublicReason` has exactly Health, AuthHandshake, SignedWebhook and CatalogRead. An API-key or tool-token route authenticates with its own guard; do not add a public reason.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        const inIdentity = isOwnedBy(hfsOf(context), filename, "domain", "identity")
+        return {
+            TSEnumDeclaration(node) {
+                if (!inIdentity || node.id.name !== "PublicReason") return
+                const names = publicReasonNames(context, node)
+                if (names.size !== PUBLIC_REASONS.size || [...PUBLIC_REASONS].some((name) => !names.has(name))) {
+                    context.report({ node, messageId: "closed" })
+                }
+            },
+            Decorator(node) {
+                if (decoratorName(node) !== "Public") return
+                const reason = publicReasonOf(node)
+                if (reason !== null && hasAddedPublicReason(context, reason)) context.report({ node, messageId: "closed" })
+            },
+        }
+    },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
     "no-untyped-body": noUntypedBody,
     "public-needs-reason": publicNeedsReason,
+    "public-reason-closed": publicReasonClosed,
 }
 
-/** Both start at error: an untyped door and an unexplained open door are the failures this law exists for. */
+/** Every rule starts at error: public doors and typed inputs hold the default-deny boundary. */
 export const recommended = {
     "starci-be/no-untyped-body": "error",
     "starci-be/public-needs-reason": "error",
+    "starci-be/public-reason-closed": "error",
 }

package/edge-hardening.mjs

@@ -0,0 +1,139 @@
+/** R261: every API entrypoint declares its browser and proxy boundary. */
+import { keyName, staticText, walk } from "./lib/ast.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+
+const unwrap = (node) => {
+    while (node && ["TSAsExpression", "TSTypeAssertion", "TSSatisfiesExpression", "TSNonNullExpression", "AwaitExpression", "ChainExpression"].includes(node.type)) node = node.expression ?? node.argument
+    return node
+}
+const property = (node, name, constants = new Map(), seen = new Set()) => {
+    if (node?.type !== "ObjectExpression") return undefined
+    for (const entry of [...node.properties].reverse()) {
+        if (entry.type === "SpreadElement") {
+            const spread = resolve(entry.argument, constants, seen)
+            if (spread?.type !== "ObjectExpression") return undefined
+            const value = property(spread, name, constants, seen)
+            if (value !== undefined) return value
+        } else {
+            const key = entry.computed ? staticText(entry.key) : keyName(entry.key)
+            if (key === null) return undefined
+            if (key === name) return entry.value
+        }
+    }
+    return undefined
+}
+const method = (node) => node?.type === "MemberExpression" ? (node.computed ? staticText(node.property) : keyName(node.property)) : null
+
+/** Only declared API entrypoints are judged; workers have no browser edge. */
+const isApiMain = (context) => {
+    const hfs = hfsOf(context)
+    const file = hfs.relative(context.filename ?? context.getFilename())
+    return hfs.slotOf(context.filename ?? context.getFilename()) === "be.app.api"
+        && hfs.apps.some((app) => app.kind === "api" && file === `apps/${app.name}/src/main.ts`)
+}
+
+/** Resolve local constants without making an identifier's spelling a security proof. */
+const resolve = (node, constants, seen = new Set()) => {
+    node = unwrap(node)
+    if (node?.type === "Identifier" && constants.has(node.name) && !seen.has(node.name)) return resolve(constants.get(node.name), constants, new Set([...seen, node.name]))
+    if (node?.type === "MemberExpression" && method(node) !== null) {
+        const value = property(resolve(node.object, constants, seen), method(node), constants, seen)
+        if (value !== undefined) return resolve(value, constants, seen)
+    }
+    return node
+}
+
+const allowedOrigin = (node) => {
+    const value = staticText(node)
+    if (value === null || value.includes("*") || value.endsWith("/")) return false
+    try {
+        const url = new URL(value)
+        return value === url.origin && (url.protocol === "https:" || (url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+    } catch { return false }
+}
+
+/** Config owns a dynamic allowlist; literal lists must contain exact origins. */
+const allowlist = (node, constants) => {
+    node = resolve(node, constants)
+    if (node?.type === "MemberExpression") return method(node) === "allowedOrigins"
+    if (node?.type !== "ArrayExpression" || node.elements.length === 0) return false
+    return node.elements.every((entry) => entry?.type === "SpreadElement"
+        ? allowlist(entry.argument, constants)
+        : allowedOrigin(resolve(entry, constants)))
+}
+
+const hopCount = (node, constants) => {
+    node = resolve(node, constants)
+    return node?.type === "Literal" && Number.isSafeInteger(node.value) && node.value >= 0
+}
+
+const audit = (program) => {
+    const constants = new Map()
+    const helpers = new Set()
+    const middleware = new Set()
+    const factories = new Set()
+    const applications = new Set()
+    const calls = []
+    walk(program, (node) => {
+        if (node.type === "ImportDeclaration") {
+            if (node.source.value === "@nestjs/core") {
+                for (const specifier of node.specifiers) if (specifier.imported?.name === "NestFactory") factories.add(specifier.local.name)
+            }
+            if (/^@modules\/platform\/http-security(?:\/|$)/.test(node.source.value)) {
+                for (const specifier of node.specifiers) {
+                    if (["applyHttpSecurity", "configureHttpSecurity"].includes(specifier.imported?.name)) helpers.add(specifier.local.name)
+                    if (["securityHeaders", "createSecurityHeadersMiddleware"].includes(specifier.imported?.name)) middleware.add(specifier.local.name)
+                }
+            }
+        }
+        if (node.type === "VariableDeclarator" && node.id.type === "Identifier" && node.init) constants.set(node.id.name, node.init)
+        if (node.type === "CallExpression") calls.push(node)
+    })
+    for (const [name, initializer] of constants) {
+        const node = resolve(initializer, constants)
+        if (node?.type === "CallExpression" && method(node.callee) === "create" && factories.has(node.callee.object.name)) applications.add(name)
+    }
+    const isApplication = (node) => {
+        if (node?.type === "Identifier" && applications.has(node.name)) return true
+        node = resolve(node, constants)
+        if (node?.type !== "CallExpression") return false
+        if (method(node.callee) === "create" && factories.has(node.callee.object.name)) return true
+        return ["getInstance", "getHttpAdapter"].includes(method(node.callee)) && isApplication(node.callee.object)
+    }
+    const direct = calls.filter((call) => call.callee.type === "MemberExpression" && isApplication(call.callee.object))
+    const applied = calls.filter((call) => call.callee.type === "Identifier" && helpers.has(call.callee.name) && isApplication(call.arguments[0]))
+    const helperCors = applied.some((call) => {
+        const config = resolve(call.arguments[1], constants)
+        return config?.type === "MemberExpression" || allowlist(property(config, "allowedOrigins", constants), constants)
+    })
+    const corsCalls = direct.filter((call) => method(call.callee) === "enableCors")
+    const cors = (helperCors || corsCalls.length > 0) && corsCalls.every((call) => allowlist(property(resolve(call.arguments[0], constants), "origin", constants), constants))
+    const headers = applied.length > 0 || direct.some((call) => method(call.callee) === "use" && call.arguments.some((argument) => {
+        const candidate = resolve(argument, constants)
+        return (candidate?.type === "Identifier" && middleware.has(candidate.name))
+            || (candidate?.type === "CallExpression" && candidate.callee.type === "Identifier" && middleware.has(candidate.callee.name))
+    }))
+    const poweredCalls = direct.filter((call) => ["set", "enable", "disable"].includes(method(call.callee)) && staticText(call.arguments[0])?.toLowerCase() === "x-powered-by")
+    const poweredOff = (applied.length > 0 || poweredCalls.some((call) => method(call.callee) === "disable" || (method(call.callee) === "set" && call.arguments[1]?.value === false)))
+        && poweredCalls.every((call) => method(call.callee) === "disable" || (method(call.callee) === "set" && call.arguments[1]?.value === false))
+    const proxyCalls = direct.filter((call) => method(call.callee) === "set" && staticText(call.arguments[0]) === "trust proxy")
+    const proxy = (proxyCalls.length > 0 || applied.length > 0)
+        && proxyCalls.every((call) => hopCount(call.arguments[1], constants))
+        && applied.every((call) => hopCount(property(resolve(call.arguments[2], constants), "trustProxy", constants), constants))
+    return { cors, headers: headers && poweredOff, proxy }
+}
+
+const edgeRule = (field, code, description) => ({
+    meta: { type: "problem", docs: { description }, schema: [], messages: { boundary: `${code}: ${description}` } },
+    create(context) {
+        if (!isApiMain(context)) return {}
+        return { "Program:exit"(node) { if (!audit(node)[field]) context.report({ node, messageId: "boundary" }) } }
+    },
+})
+
+export const corsAllowlist = edgeRule("cors", "BE_CORS_ALLOWLIST", "Configure CORS with an explicit origin allowlist from http-security config; wildcard, open and missing origins are refused.")
+export const securityHeaders = edgeRule("headers", "BE_SECURITY_HEADERS", "Apply the platform/http-security response middleware and disable x-powered-by.")
+export const trustProxy = edgeRule("proxy", "BE_TRUST_PROXY", "Declare trust proxy as a nonnegative integer hop count; blanket trust and undeclared proxy trust are refused.")
+
+export const rules = { "cors-allowlist": corsAllowlist, "security-headers": securityHeaders, "trust-proxy": trustProxy }
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-be/${name}`, "error"]))

package/feature-thin.mjs

@@ -1,5 +1,6 @@
 /**
- * The rule that holds the thin-feature law (R203 `BE_FEATURE_THIN`).
+ * The rules that hold the thin-feature law (R203 `BE_FEATURE_THIN`) and close the support-role escape
+ * (R264 `HFS_FEATURE_LOGIC_ROLE`).
  *
  * A file of the feature tier whose role is one of `ruleParams.be.thinRoles` of the slot manifest
  * (`<name>.handler.ts`, `<name>.resolver.ts`, `<name>.consumer.ts`, `<name>.processor.ts`, `<name>.step.ts`,
@@ -22,7 +23,7 @@
 import { keyName, walk } from "./lib/ast.mjs"
 import { aliasTarget, callsOf, decoratorsFrom, injectedMembers } from "./lib/doors.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
-import { importOf } from "./lib/import-source.mjs"
+import { importOf, isImportedFrom } from "./lib/import-source.mjs"
 import { baseName, isLoggerType, isOwnedType } from "./lib/ports.mjs"
 import { firstWebhookVerification, isWebhookDomainServiceType } from "./lib/webhook-verifiers.mjs"
 import { isWebhookForbiddenReceiver } from "./lib/webhook-handoff.mjs"
@@ -268,12 +269,87 @@ export const featureThin = {
     },
 }
 
+/** A declaration's signed numeric literal is still data, including an enum member or a constant. */
+const isSignedNumericLiteral = (node) => node.type === "UnaryExpression" && ["+", "-"].includes(node.operator)
+    && node.argument.type === "Literal" && typeof node.argument.value === "number"
+
+/** A DTO's decorator application declares metadata; calls inside its arguments remain ordinary executable calls. */
+const isDecoratorApplication = (node) => node.parent?.type === "Decorator" && node.parent.expression === node
+
+/** A Nest command/query constructor initializes its data base through the required, argument-free super call. */
+const isCqrsDataConstructor = (context, node) => {
+    if (node.callee.type !== "Super" || node.arguments.length !== 0) return false
+    for (let parent = node.parent; parent; parent = parent.parent) {
+        if (parent.type === "MethodDefinition") {
+            const declaration = parent.parent?.parent
+            return parent.kind === "constructor" && isImportedFrom(context, declaration?.superClass, "@nestjs/cqrs", ["Command", "Query"])
+        }
+        if (["FunctionDeclaration", "ArrowFunctionExpression"].includes(parent.type)) return false
+    }
+    return false
+}
+
+/**
+ * `registerEnumType(...)` of `@nestjs/graphql` at module top level of a `<name>.type.ts` file of the GraphQL transport slot
+ * (`be.transport.graphql`). It declares a schema enum: `starci app emit` loads only the resolver, scalar and `include` module files, so the
+ * registration must sit in a file the resolver imports, and the `.type.ts` is that file (owner ruling 2026-10-16 "Theo y tro", docs/microservices.md#r264).
+ * The same call in any other role or slot, or nested in a function, stays executable logic.
+ */
+const isEnumRegistration = (context, hfs, node, role) => role === "type"
+    && hfs.slotOf(context.filename) === "be.transport.graphql"
+    && node.parent?.type === "ExpressionStatement" && node.parent.parent?.type === "Program"
+    && isImportedFrom(context, node.callee, "@nestjs/graphql", ["registerEnumType"])
+
+/** Non-door feature roles declare data; renaming a policy or a guard must never hide business logic from R203. */
+export const featureLogicRole = {
+    meta: {
+        type: "problem",
+        docs: { description: "Non-door roles in the feature tier may declare data, types and DTO metadata, but cannot hold decisions, computation or executable calls." },
+        schema: [],
+        messages: {
+            logic: "[HFS_FEATURE_LOGIC_ROLE] {{what}} puts executable logic in a feature `<name>.{{role}}.ts` support or data file. Keep its declarations and data here; put business logic in the tested modules and delegate through a declared thin feature role.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const name = baseName(context.filename)
+        if (name.endsWith(".spec.ts") || name.endsWith(".d.ts")) return {}
+        const role = roleOf(name)
+        if (role === null || (hfs.ruleParams.thinRoles ?? []).includes(role)) return {}
+        if (hfs.tierOf(context.filename) !== "feature") return {}
+        // The feature's Nest composition is governed by the module laws. A module suffix in support/ is still support.
+        if (["module", "module-definition"].includes(role) && hfs.slotOf(context.filename) !== "be.feature.application.support") return {}
+
+        const report = (node, what) => context.report({ node, messageId: "logic", data: { what, role } })
+        const visitors = {}
+        for (const type of BRANCH_NODES) {
+            visitors[type] = (node) => report(node, type === "LogicalExpression" ? `a \`${node.operator}\`` : BRANCH_WHAT[type])
+        }
+        for (const type of COMPUTE_NODES) {
+            visitors[type] = (node) => {
+                if (!isSignedNumericLiteral(node)) report(node, `an \`${node.operator}\``)
+            }
+        }
+        visitors.TemplateLiteral = (node) => {
+            if (node.expressions.length > 0) report(node, "a template literal with an expression")
+        }
+        visitors.CallExpression = (node) => {
+            if (!isDecoratorApplication(node) && !isCqrsDataConstructor(context, node) && !isEnumRegistration(context, hfs, node, role)) report(node, `the call \`${context.sourceCode.getText(node.callee)}\``)
+        }
+        visitors.TaggedTemplateExpression = (node) => report(node, `the tagged call \`${context.sourceCode.getText(node.tag)}\``)
+        visitors.NewExpression = (node) => report(node, `the construction \`${context.sourceCode.getText(node.callee)}\``)
+        return visitors
+    },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
     "feature-thin": featureThin,
+    "feature-logic-role": featureLogicRole,
 }
 
 /** Every rule of this law at `error`. */
 export const recommended = {
     "starci-be/feature-thin": "error",
+    "starci-be/feature-logic-role": "error",
 }

package/function-budget.mjs

@@ -0,0 +1,49 @@
+/**
+ * R291 HFS_FUNCTION_BUDGET: every function body stays within the common line budget.
+ *
+ * Count the physical span of the body, including braces, comments, blank lines and nested functions.
+ * Signatures and parameters are outside the body. An expression arrow has an expression body and
+ * counts the expression and its wrapping parentheses, including comments and blanks inside them.
+ */
+import { hfsOf } from "./lib/hfs.mjs"
+
+/** Functions, methods, constructors, accessors and callbacks all receive the same body budget. */
+export const functionLineBudget = {
+    meta: {
+        type: "problem",
+        docs: { description: "A function body stays within ruleParams.functionLines, counting comments and blank lines." },
+        schema: [],
+        messages: {
+            lines: "HFS_FUNCTION_BUDGET: this function body has {{lines}} lines; the budget is {{max}}. Split the work into functions with one responsibility each.",
+        },
+    },
+    create(context) {
+        // C08 adds this common parameter to the shipped manifest; keep the owner-decided cap while it lands.
+        const max = hfsOf(context).ruleParams.functionLines ?? 80
+        if (!Number.isInteger(max) || max < 1) throw new RangeError("ruleParams.functionLines must be a positive integer")
+        const source = context.sourceCode || context.getSourceCode()
+        const check = (node) => {
+            if (!node.body) return
+            let start = node.body.loc.start.line
+            let end = node.body.loc.end.line
+            if (node.type === "ArrowFunctionExpression" && node.body.type !== "BlockStatement") {
+                const arrow = source.getTokenBefore(node.body, { filter: (token) => token.value === "=>" })
+                start = source.getTokenAfter(arrow, { includeComments: true }).loc.start.line
+                end = node.loc.end.line
+            }
+            const lines = end - start + 1
+            if (lines > max) context.report({ node: node.body, messageId: "lines", data: { lines, max } })
+        }
+        return {
+            FunctionDeclaration: check,
+            FunctionExpression: check,
+            ArrowFunctionExpression: check,
+        }
+    },
+}
+
+/** The rule this law contributes to the plugin. */
+export const rules = { "function-line-budget": functionLineBudget }
+
+/** The function budget is an error in both editions. */
+export const recommended = { "starci-be/function-line-budget": "error" }