@noctcore/lint-meta-rules 0.4.2 → 0.6.0

package/docs/rules/session-mint-callers.md

@@ -0,0 +1,77 @@
+# `session-mint-callers`
+
+> The method that mints a session is callable only from an allowlist of files, so a new sign-in
+> entry point cannot skip the gate in front of it.
+
+Import it from the `session` entry point:
+
+```ts
+import { createSessionMintCallersRule } from '@noctcore/lint-meta-rules/session';
+```
+
+## Why
+
+Most auth stacks have one method that turns an authenticated principal into a session: it writes the
+session store, sets the cookie, rotates CSRF. In front of it sits a gate (a second-factor challenge, an
+epoch capture) that every sign-in is meant to pass through. A new entry point, typically an OAuth
+callback added months later, that calls the mint directly signs the user in with the gate skipped, and
+nothing fails: the flow works, its tests pass, the gate's tests pass. The mint is the one door into a
+session, so this rule fences the door by caller.
+
+## What it flags
+
+A file matched by `sourceGlobs` that calls `.<mintCall>(` (whitespace before the paren allowed) and is
+not in `allowedCallers`.
+
+## What it leaves alone
+
+- The method's definition (`async establishSession(`): the leading dot is required.
+- `.<mintCall>Something(`: only whitespace may sit between the name and the paren.
+- Files ending in an `excludeSuffixes` entry (tests drive the mint directly), and paths with a
+  `skipDirs` segment.
+- Everything outside `sourceGlobs`, including a lint-meta rule module that quotes the call.
+
+With no `mintCall` the rule is inert.
+
+## Factory
+
+```ts
+createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'session-mint-callers'` | Rule id. |
+| `mintCall` | `string` | none (inert) | The method whose call mints a session, matched as `.<mintCall>(`. |
+| `allowedCallers` | `string[]` | `[]` | Repo-relative files that may call it, matched exactly: the method's home, the gate, and flows with no gate to pass (signup, a re-issue to a caller who already holds a session). |
+| `gateCall` | `string` | none | The method a sign-in entry point must call instead, named 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, e.g. a pointer to your auth docs. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: Settly
+
+```ts
+const AUTH = 'apps/api/src/modules/auth/services';
+
+createSessionMintCallersRule({
+  id: 'establish-session-callers',
+  mintCall: 'establishSession',
+  gateCall: 'beginOrEstablish',
+  allowedCallers: [
+    `${AUTH}/auth-shared.service.ts`,
+    `${AUTH}/two-factor-challenge.service.ts`,
+    `${AUTH}/register.service.ts`,
+    `${AUTH}/password-change.service.ts`,
+    `${AUTH}/session-management.service.ts`,
+  ],
+  sourceGlobs: ['apps/*/{src,test,tests,security-spec}/**/*.{ts,tsx}'],
+});
+```
+
+## When not to use it
+
+If sessions are minted by a framework you do not call (a hosted auth provider's middleware), there is no
+method to fence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Portable, parameterized lint-meta rules — whole-repo / cross-file invariants ESLint cannot reach — for the @noctcore/harness lint-meta runner.",
   "license": "MIT",
   "type": "module",
@@ -28,6 +28,16 @@
       "import": "./dist/resolved-config.js",
       "require": "./dist/resolved-config.cjs"
     },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js",
+      "require": "./dist/session.cjs"
+    },
+    "./trpc": {
+      "types": "./dist/trpc.d.ts",
+      "import": "./dist/trpc.js",
+      "require": "./dist/trpc.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -56,13 +66,13 @@
   "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/lint-meta-rules",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
-    "build": "tsup src/index.ts src/i18n.ts src/prisma.ts src/resolved-config.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/i18n.ts src/prisma.ts src/resolved-config.ts src/session.ts src/trpc.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@noctcore/eslint-plugin-contracts": "^0.6.0",
-    "@noctcore/eslint-plugin-prisma": "^0.4.0",
+    "@noctcore/eslint-plugin-contracts": "^0.7.0",
+    "@noctcore/eslint-plugin-prisma": "^0.5.0",
     "@noctcore/harness": "^0.3.0",
     "@typescript-eslint/utils": "^8.61.1"
   },
@@ -79,9 +89,9 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/parser": "^8.61.1",
-    "eslint": "^10.7.0",
+    "@types/node": "^22.20.3",
+    "@typescript-eslint/parser": "^8.70.0",
+    "eslint": "^10.10.0",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0"
   }