@starci/eslint-canon-be 3.0.8 → 3.0.9

package/webhooks.mjs

@@ -0,0 +1,173 @@
+/**
+ * The rules that hold the webhook kind (R182 `BE_WEBHOOK_SHAPE`, R183 `BE_WEBHOOK_UNVERIFIED`).
+ *
+ * A provider webhook (`src/features/webhooks/<provider>/transport/http/<provider>.webhook.ts`, slot `be.feature.webhooks.http`) is a signed intake door. It
+ * proves the delivery came from the provider, then hands it to exactly ONE domain intake method, which records it and
+ * publishes the event inside its own transaction (`eventBus.publish(event, tx)` is called only from `modules/domain`). The door
+ * writes nothing and decides nothing:
+ *
+ *   - `webhook-shape` (R182): the door is one `@Controller` with one `@Post` handler, `@Public({ reason: PublicReason.SignedWebhook })`;
+ *     it injects only the `WebhookSignatureService` of `platform/http-security` and services of `modules/domain`; its handler has no
+ *     branch, loop or `try`, makes exactly one call on a domain service, calls on the signature service only `verify`, and returns
+ *     nothing.
+ *   - `webhook-verify-first` (R183): the first statement of the handler is the unconditional `verify` call, so no path reaches the
+ *     intake with an unproven delivery.
+ *
+ * What a receiver is comes from its TYPE (where the class is declared); what a decorator is comes from the import that binds it.
+ * No rule here tests a directory spelled in a path pattern or a variable name.
+ */
+import { walk } from "./lib/ast.mjs"
+import { callsOf, decoratorsFrom, hasClassDecorator, injectedMembers, methodsDecoratedBy } from "./lib/doors.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { decoratorArguments, decoratorCallee, importOf } from "./lib/import-source.mjs"
+import { baseName, enumMemberOf, isOwnedType } from "./lib/ports.mjs"
+import { typeOrigins } from "./lib/types.mjs"
+
+/** The slot of provider webhook doors. */
+const SLOT = "be.feature.webhooks.http"
+
+/** The HTTP verbs of `@nestjs/common`; only `Post` is a webhook method. */
+const HTTP_VERBS = ["Get", "Post", "Put", "Patch", "Delete", "All", "Options", "Head"]
+
+/** Statements and expressions that are a decision or a repetition: none of them belongs in a door. */
+const DECISION_NODES = new Set(["IfStatement", "SwitchStatement", "ConditionalExpression", "LogicalExpression", "ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "TryStatement", "ThrowStatement"])
+
+/** The `WebhookSignatureService` of `platform/http-security`. */
+const isSignatureType = (context, node) => isOwnedType(context, node, { name: "WebhookSignatureService", capability: "http-security", tier: "platform" })
+
+/** A service of `modules/domain`: a class declared in a `<name>.service.ts` of the domain tier. */
+const isDomainServiceType = (context, hfs, node) =>
+    typeOrigins(context, node).some((origin) => origin.module === null && hfs.tierOf(origin.file) === "domain" && baseName(origin.file).endsWith(".service.ts"))
+
+/** The `@Controller` classes of a webhook file, with their handler methods. */
+const doorsOf = (context, program) => {
+    const doors = []
+    walk(program, (node) => {
+        if (node.type !== "ClassDeclaration") return
+        if (hasClassDecorator(context, node, "@nestjs/common", "Controller")) doors.push(node)
+    })
+    return doors
+}
+
+/** The route methods of a controller: every method carrying an HTTP verb decorator. */
+const routeMethods = (context, controller) => methodsDecoratedBy(context, controller, "@nestjs/common", HTTP_VERBS)
+
+/** The handler of a webhook door: its `@Post` method, or null when it has none. */
+const handlerOf = (context, controller) => methodsDecoratedBy(context, controller, "@nestjs/common", "Post")[0] ?? null
+
+/** True when the method carries `@Public({ reason: PublicReason.SignedWebhook })`: the reason is read from the enum member the argument is. */
+const isSignedWebhookDoor = (context, method) =>
+    (method.decorators ?? []).some((decorator) => {
+        const callee = decoratorCallee(decorator)
+        if (callee?.type !== "Identifier" || importOf(context, callee) === null) return false
+        const options = decoratorArguments(decorator)[0]
+        if (options?.type !== "ObjectExpression") return false
+        const reason = options.properties.find((property) => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "reason")
+        const member = reason ? enumMemberOf(context, reason.value) : null
+        return member !== null && member.enumName === "PublicReason" && member.member === "SignedWebhook"
+    })
+
+/** A provider webhook door: one signed `@Post`, the signature proof, one domain intake call, nothing else. */
+export const webhookShape = {
+    meta: {
+        type: "problem",
+        docs: { description: "A webhook door is one `@Controller` with one `@Public({ reason: PublicReason.SignedWebhook })` `@Post` handler that injects only the `WebhookSignatureService` and domain services, verifies, makes exactly one domain call and returns nothing." },
+        schema: [],
+        messages: {
+            noDoor: "A webhook file declares one `@Controller` class: the door of the provider. Nothing else lives in `<provider>.webhook.ts`.",
+            injects: "`{{what}}` is injected into a webhook door. A webhook injects only the `WebhookSignatureService` of `platform/http-security` and services of `modules/domain`; a bus, a repository, an `EntityManager` or a queue never reaches it. The intake is one domain service method that records the delivery and publishes the event inside its own transaction.",
+            route: "A webhook door has exactly one `@Post` handler (this class has {{count}} route methods{{verbs}}). One provider endpoint is one door; another route belongs in its own provider folder or in an api feature.",
+            notPublic: "`{{name}}` is not `@Public({ reason: PublicReason.SignedWebhook })`. The signature is the authentication of a webhook: it is public by that declaration and no other, so the open doors stay readable and the strict rate tier applies.",
+            branch: "`{{what}}` is a decision or a loop in a webhook door. The door proves the delivery and hands it over: a refusal is the thrown error of `verify`, and every other decision belongs in the domain intake method.",
+            call: "`{{what}}` is a call a webhook door does not make. The handler calls `verify` of the `WebhookSignatureService` once and one method of a domain service once; parsing, mapping and publishing belong in the domain service.",
+            intakeCalls: "`{{name}}` calls domain services {{count}} times. A webhook hands the verified delivery to exactly one domain intake method (it records the delivery and publishes the event in one transaction); a second call is orchestration that belongs in that method.",
+            returns: "`{{name}}` returns a value. A webhook acknowledges with its status and an empty body; it returns nothing of the domain to the provider.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (hfs.slotOf(context.filename) !== SLOT || !baseName(context.filename).endsWith(".webhook.ts")) return {}
+        return {
+            "Program:exit"(program) {
+                const doors = doorsOf(context, program)
+                if (doors.length !== 1) {
+                    context.report({ node: program, messageId: "noDoor" })
+                    return
+                }
+                const door = doors[0]
+                for (const { node, annotation } of injectedMembers(context, door)) {
+                    if (!annotation || !(isSignatureType(context, annotation) || isDomainServiceType(context, hfs, annotation))) context.report({ node, messageId: "injects", data: { what: context.sourceCode.getText(node) } })
+                }
+                const routes = routeMethods(context, door)
+                const handler = handlerOf(context, door)
+                if (routes.length !== 1 || handler === null) {
+                    const verbs = routes.length > 0 ? ` (${routes.map((route) => decoratorsFrom(context, route, "@nestjs/common", HTTP_VERBS).map((decorator) => decoratorCallee(decorator).name ?? "route").join("+")).join(", ")})` : ""
+                    context.report({ node: door, messageId: "route", data: { count: String(routes.length), verbs } })
+                    return
+                }
+                const name = handler.key.type === "Identifier" ? handler.key.name : "the handler"
+                if (!isSignedWebhookDoor(context, handler)) context.report({ node: handler.key, messageId: "notPublic", data: { name } })
+                walk(handler.value.body, (child) => {
+                    if (DECISION_NODES.has(child.type)) context.report({ node: child, messageId: "branch", data: { what: child.type === "LogicalExpression" ? child.operator : child.type.replace(/(Statement|Expression)$/, "").toLowerCase() } })
+                    else if (child.type === "ReturnStatement" && child.argument) context.report({ node: child, messageId: "returns", data: { name } })
+                })
+                let intake = 0
+                for (const { call, receiver, method } of callsOf(handler)) {
+                    if (receiver !== null && isSignatureType(context, receiver) && method === "verify") continue
+                    if (receiver !== null && isDomainServiceType(context, hfs, receiver)) {
+                        intake += 1
+                        continue
+                    }
+                    context.report({ node: call, messageId: "call", data: { what: context.sourceCode.getText(call.callee) } })
+                }
+                if (intake !== 1) context.report({ node: handler.key, messageId: "intakeCalls", data: { name, count: String(intake) } })
+            },
+        }
+    },
+}
+
+/** The first statement of the handler is the unconditional signature proof. */
+export const webhookVerifyFirst = {
+    meta: {
+        type: "problem",
+        docs: { description: "The first statement of a webhook handler is the unconditional `verify` call of the `WebhookSignatureService` (signature and replay window), before anything else runs." },
+        schema: [],
+        messages: {
+            first: "`{{name}}` does not start with `verify` of the `WebhookSignatureService`. The first statement of a webhook handler is `this.<signature>.verify({ rawBody, signature, timestamp })` (awaited when it is async): a delivery that fails the signature or the replay window throws before any other code runs, so no path reaches the intake unproven.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        if (hfs.slotOf(context.filename) !== SLOT || !baseName(context.filename).endsWith(".webhook.ts")) return {}
+        return {
+            "Program:exit"(program) {
+                for (const door of doorsOf(context, program)) {
+                    const handler = handlerOf(context, door)
+                    if (handler === null) continue
+                    const first = handler.value.body?.body[0]
+                    let expression = first?.type === "ExpressionStatement" ? first.expression : null
+                    if (expression?.type === "AwaitExpression") expression = expression.argument
+                    const proven = expression?.type === "CallExpression"
+                        && expression.callee.type === "MemberExpression"
+                        && !expression.callee.computed
+                        && expression.callee.property.type === "Identifier"
+                        && expression.callee.property.name === "verify"
+                        && isSignatureType(context, expression.callee.object)
+                    if (!proven) context.report({ node: handler.key, messageId: "first", data: { name: handler.key.type === "Identifier" ? handler.key.name : "the handler" } })
+                }
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "webhook-shape": webhookShape,
+    "webhook-verify-first": webhookVerifyFirst,
+}
+
+/** Every rule of this law at `error`. */
+export const recommended = {
+    "starci-be/webhook-shape": "error",
+    "starci-be/webhook-verify-first": "error",
+}

package/runtime/scripts/api/sops/decrypt.mjs

@@ -1,16 +0,0 @@
-// decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
-// secrets (scripts/lib/test-secrets.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
-import os from 'node:os';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-
-/**
- * Run `<bin> <args>` with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity. {status, stdout, stderr, error}.
- */
-export function sopsDecrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
-  const r = spawnSync(bin, args, {
-    cwd, encoding: 'utf8', windowsHide: true, maxBuffer,
-    env: { ...env, SOPS_AGE_KEY_FILE: env.SOPS_AGE_KEY_FILE || path.join(os.homedir(), '.starci', 'master.identity') },
-  });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
-}

package/runtime/scripts/lib/test-secrets.mjs

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-// test-secrets.mjs — test credentials follow the product repository's own `.starcistacks` convention (owner ruling
-// push-scan-test-secrets-encrypted, 2026-09-28: they work exactly like the stack custody and a plaintext password is never pushed).
-// There is no store of the runtime's own: a test credential lives at `<repo>/.starcistacks/<stack>/secrets/test/<name>`,
-// its plaintext git-ignored by the repo's `.starcistacks/**` rules and only the sops-encrypted twin `<name>.enc`
-// committed. It is written with the repository's existing command (`node scripts/stack-secret.mjs set
-// <stack>/secrets/test/<name>`, npm run secret:set), which encrypts against the recipients `.sops.yaml` names and
-// removes the plaintext; this module only READS: the local plaintext when present, else the `.enc` decrypted by sops
-// with the shared age identity (SOPS_AGE_KEY_FILE, default ~/.starci/master.identity) into memory.
-// A credential that need not be stable across runs (a disposable account registered per run) is generated per run
-// and stored nowhere. A value is never logged.
-//
-//   node scripts/lib/test-secrets.mjs get <name> --repo <path> [--stack dev] [--reveal]   prints nothing unless --reveal
-//
-// In a script:  import { testSecret } from '<runtime>/scripts/lib/test-secrets.mjs';
-//               const password = testSecret('login-capture-password', { repo });
-// The push secret scan (scripts/supervisor/push-mains.mjs) passes a `.enc` only when isSopsEnvelope holds.
-import fs from 'node:fs';
-import path from 'node:path';
-import { sopsDecrypt } from '../api/sops/decrypt.mjs';
-import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../engine/yaml.mjs';
-
-const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-const STACK = /^[a-z0-9][a-z0-9-]{0,31}$/;
-/** One sops-encrypted leaf: `ENC[AES256_GCM,data:...,iv:...,tag:...,type:...]` (data may be empty). */
-const SOPS_VALUE = /^ENC\[AES256_GCM,data:[A-Za-z0-9+/=]*,iv:[A-Za-z0-9+/=]+,tag:[A-Za-z0-9+/=]+,type:[a-z]+\]$/;
-
-/** Where test credential `name` of `stack` lives in `repo`: {plain, enc, rel}. `rel` is the path the repo's
- *  `stack-secret.mjs set` takes. */
-export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
-  if (!NAME.test(String(name ?? ''))) throw new Error(`test secret name must match ${NAME} (got ${JSON.stringify(name)})`);
-  if (!STACK.test(String(stack ?? ''))) throw new Error(`stack must match ${STACK} (got ${JSON.stringify(stack)})`);
-  if (!repo) throw new Error('test secret needs {repo}: the product repository whose .starcistacks holds it');
-  const rel = `${stack}/secrets/test/${name}`;
-  const plain = path.join(path.resolve(String(repo)), '.starcistacks', stack, 'secrets', 'test', name);
-  return { plain, enc: `${plain}.enc`, rel };
-}
-
-/** The command that stores a test credential, in the product repository's own tooling. */
-export const setCommand = (name = '<name>', stack = 'dev') => `node scripts/stack-secret.mjs set ${stack}/secrets/test/${name}`;
-
-/** sops' format for a plaintext path, as the repository's stack-secret.mjs formatFor decides it. */
-export const sopsFormatFor = (file) => (file.endsWith('.env') ? 'dotenv' : /\.json$/.test(file) ? 'json' : /\.(ya?ml|kubeconfig)$/.test(file) ? 'yaml' : 'binary');
-
-/** The sops binary: PATH, then winget's Links and Packages (spawn without a shell ignores PATHEXT). */
-export function resolveSops(env = process.env) {
-  const win = process.platform === 'win32';
-  const names = win ? ['sops.exe', 'sops'] : ['sops'];
-  const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
-  if (win && env.LOCALAPPDATA) {
-    const winget = path.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
-    dirs.push(path.join(winget, 'Links'));
-    const packages = path.join(winget, 'Packages');
-    try { for (const e of fs.readdirSync(packages)) if (/sops/i.test(e)) dirs.push(path.join(packages, e)); } catch { /* none */ }
-  }
-  for (const dir of dirs) for (const n of names) { const f = path.join(dir, n); try { if (fs.statSync(f).isFile()) return f; } catch { /* next */ } }
-  return null;
-}
-
-/** Read test credential `name`: the local plaintext when present, else its committed `.enc` through sops. */
-export function testSecret(name, { repo, stack = 'dev', env = process.env, sops = null } = {}) {
-  const { plain, enc, rel } = testSecretPaths(name, { repo, stack });
-  if (fs.existsSync(plain)) return fs.readFileSync(plain, 'utf8').replace(/\r?\n$/, '');
-  if (!fs.existsSync(enc)) throw new Error(`test secret ${name} is not in .starcistacks/${rel}.enc; store it with \`${setCommand(name, stack)}\` in ${repo}`);
-  const bin = sops ?? resolveSops(env);
-  if (!bin) throw new Error('sops is not installed (Windows: winget install Mozilla.SOPS)');
-  const format = sopsFormatFor(plain);
-  const r = sopsDecrypt(bin, ['--decrypt', '--input-type', format, '--output-type', format, enc], { cwd: path.resolve(String(repo)), env, maxBuffer: 1024 * 1024 });
-  if (r.status !== 0) throw new Error(`test secret ${name}: sops could not decrypt .starcistacks/${rel}.enc (${String(r.stderr ?? r.error?.message ?? '').trim().split(/\r?\n/).pop()})`);
-  return String(r.stdout).replace(/\r?\n$/, '');
-}
-
-/** Every leaf outside the `sops` block is an ENC[...] value (or null); the block itself carries a mac. */
-const allEncrypted = (node) => {
-  if (node === null) return true;
-  if (Array.isArray(node)) return node.every(allEncrypted);
-  if (typeof node === 'object') return Object.values(node).every(allEncrypted);
-  return typeof node === 'string' && SOPS_VALUE.test(node);
-};
-const sopsTree = (doc) => !!doc && typeof doc === 'object' && !Array.isArray(doc) && !!doc.sops && typeof doc.sops === 'object'
-  && typeof doc.sops.mac === 'string' && SOPS_VALUE.test(doc.sops.mac)
-  && Object.keys(doc).length > 1 && Object.entries(doc).every(([k, v]) => k === 'sops' || allEncrypted(v));
-
-/**
- * True only for a sops-encrypted file with no plaintext value: binary/json form ({"data": ENC[...], "sops": {...}}),
- * yaml form (every value ENC[...] plus the sops block) or dotenv form (KEY=ENC[...] lines plus sops_* metadata).
- * The sops metadata must carry its mac. A key kept plaintext through `unencrypted_suffix` does not pass.
- */
-export function isSopsEnvelope(text) {
-  const src = String(text ?? '').replace(/^/, '');
-  if (!src.trim()) return false;
-  try { return sopsTree(JSON.parse(src)); } catch { /* not JSON */ }
-  const lines = src.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#/.test(l));
-  if (lines.length && lines.every((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l))) {
-    const pairs = lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]);
-    const meta = pairs.filter(([k]) => k.startsWith('sops_'));
-    const vals = pairs.filter(([k]) => !k.startsWith('sops_'));
-    return vals.length > 0 && vals.every(([, v]) => SOPS_VALUE.test(v)) && meta.some(([k, v]) => k === 'sops_mac' && SOPS_VALUE.test(v));
-  }
-  try { return sopsTree(parseYaml(src)); } catch { return false; }
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, name, ...rest] = process.argv.slice(2);
-  const opt = (f) => { const i = rest.indexOf(f); return i >= 0 ? rest[i + 1] : undefined; };
-  try {
-    if (cmd === 'get') {
-      const value = testSecret(name, { repo: opt('--repo'), stack: opt('--stack') ?? 'dev' });
-      if (rest.includes('--reveal')) process.stdout.write(`${value}\n`);
-    } else {
-      console.error(`usage: test-secrets.mjs get <name> --repo <path> [--stack dev] [--reveal]\nstore one with the product repo's own command: ${setCommand()}`);
-      process.exitCode = 2;
-    }
-  } catch (error) { console.error(String(error?.message ?? error)); process.exitCode = 1; }
-}