@stapel/eslint-plugin 0.2.0 → 0.3.0

package/README.md

@@ -31,8 +31,10 @@ The `recommended` preset:
 - turns the rules on for `**/*.{ts,tsx,js,jsx,mjs,…}` (JSX-only rules on `*.{tsx,jsx}`);
 - **overrides** `no-raw-token-import` **off** in theme-config / showcase / demo / scripts,
   `no-raw-fetch` and `no-string-paths` **off** in the codegen api layer
-  (`**/api/**`, `*client.ts`, `generated/`), and `query-keys-from-factory`
-  **off** in the key-factory file (`**/queryKeys.*`);
+  (`**/api/**`, `*client.ts`, `generated/`), `query-keys-from-factory`
+  **off** in the key-factory file (`**/queryKeys.*`), `no-raw-storage` **off**
+  in core's storage/repository internals, and `no-adhoc-401` **off** in core's
+  client/session (each rule's one legal home);
 - **overrides** the content rules off in tests and fixtures (they exercise the
   anti-patterns on purpose).
 
@@ -54,6 +56,8 @@ The `recommended` preset:
 | `stapel/known-event` (warn) | `track()`/`tracked()` with an event name absent from the generated `events.json` — registry drift; run `pnpm gen:events` (§3) |
 | `stapel/no-direct-analytics-provider` | importing an analytics vendor SDK (posthog-js, mixpanel, `@amplitude/*`, `@segment/*`, …) outside the core facade's provider adapters (`analytics/providers.*`) — bypasses consent/PII/queue (§3). Extend the vendor list via `options.providers` or `settings.stapel.providerModules` |
 | `stapel/demo-literal-meta` | `defineDemo()` with non-literal meta (dynamic `id`/`title`/`description`/`covers`) — breaks static extraction into `demos.json`/`manifest.demos` (§4.2) |
+| `stapel/no-raw-storage` | direct `localStorage`/`sessionStorage`/`indexedDB` (bare or via `window.`/`globalThis.`/`self.`) or importing `idb-keyval` outside `@stapel/core`'s repository layer — raw storage is neither wiped on logout nor encrypted; persist through `createRepository()` (frontend-core-architecture-v2 §43.4). Off in core's `storage.ts`/`repository.ts`/`query.ts` (the one legal home) and in tests. Extend the banned module list via `options.modules` or `settings.stapel.storageModules` |
+| `stapel/no-adhoc-401` | comparing a status to the literal `401` (`===`/`!==`/`case 401:`) or wiring an axios-style `*.interceptors` chain — ad hoc 401 handling bypasses the single-flight refresh + logout-hook registry; 401s are handled ONCE, in core's `createStapelClient` (`onAuthRefresh` seam) + `SessionManager` (§43.2). Off in core's `client.ts`/`session.ts` and in tests |
 
 ### Settings
 
@@ -66,6 +70,7 @@ settings: {
     i18nKeys: ["auth.otp.…"],   // or i18nManifests: [manifest, …]
     httpModules: ["my-http"],   // extra banned HTTP clients
     rawModules: ["@x/raw"],     // extra raw-token entry points
+    storageModules: ["level"],  // extra banned storage-backend packages
     eventsManifests: [manifest],// or eventNames: ["pricing.plan.selected", …]
     operationsManifests: [manifest], // or operationPaths: ["/auth/api/me/", …]
     httpVerbs: ["get","post"],   // client methods no-string-paths inspects

package/index.js

@@ -18,6 +18,8 @@ import eventLiteralMeta from "./rules/event-literal-meta.js";
 import knownEvent from "./rules/known-event.js";
 import noDirectAnalyticsProvider from "./rules/no-direct-analytics-provider.js";
 import demoLiteralMeta from "./rules/demo-literal-meta.js";
+import noRawStorage from "./rules/no-raw-storage.js";
+import noAdhoc401 from "./rules/no-adhoc-401.js";
 
 const rules = {
   "no-raw-colors": noRawColors,
@@ -37,6 +39,9 @@ const rules = {
   "no-direct-analytics-provider": noDirectAnalyticsProvider,
   // Showcase guardrail (frontend-guardrails §4, task G7).
   "demo-literal-meta": demoLiteralMeta,
+  // Session-substrate guardrails (frontend-core-architecture-v2 §43).
+  "no-raw-storage": noRawStorage,
+  "no-adhoc-401": noAdhoc401,
 };
 
 const plugin = {
@@ -81,6 +86,7 @@ const FETCH_ALLOWED = [
   "**/api/**",
   "**/*client.{ts,js}",
   "**/analytics/providers.{ts,js}",
+  "**/analytics/src/providers.{ts,js}",
   "**/scripts/**",
 ];
 
@@ -101,6 +107,23 @@ const KEY_FACTORY = [
   "**/query-keys.{ts,tsx,js,mjs}",
 ];
 
+// @stapel/core's storage/repository internals — the ONE legal home of direct
+// localStorage/indexedDB access (§43.4 override; everything else persists
+// through createRepository, which is what makes wipe-at-logout mechanical).
+const STORAGE_ALLOWED = [
+  "**/core/src/storage.{ts,js}",
+  "**/core/src/repository.{ts,js}",
+  "**/core/src/query.{ts,js}",
+];
+
+// @stapel/core's client + session internals — the ONE legal home of 401
+// handling (§43.2 override; the onAuthRefresh seam + SessionManager.refresh()
+// are where the single-flight retry lives).
+const ADHOC_401_ALLOWED = [
+  "**/core/src/client.{ts,js}",
+  "**/core/src/session.{ts,js}",
+];
+
 /**
  * Flat-config `recommended` preset. Consumers spread it AFTER their parser
  * config:
@@ -132,6 +155,11 @@ const recommended = [
       "stapel/no-direct-analytics-provider": "error",
       // Showcase (§4): defineDemo meta must stay literal (extractable).
       "stapel/demo-literal-meta": "error",
+      // Session substrate (frontend-core-architecture-v2 §43): persistence
+      // only through createRepository; 401 handling only in core's client
+      // + SessionManager.
+      "stapel/no-raw-storage": "error",
+      "stapel/no-adhoc-401": "error",
     },
   },
   {
@@ -158,10 +186,22 @@ const recommended = [
     files: KEY_FACTORY,
     rules: { "stapel/query-keys-from-factory": "off" },
   },
+  {
+    // Core's storage/repository internals — the one legal home of raw
+    // storage access (§43.4 override).
+    files: STORAGE_ALLOWED,
+    rules: { "stapel/no-raw-storage": "off" },
+  },
+  {
+    // Core's client + session — the one legal home of 401 handling
+    // (§43.2 override).
+    files: ADHOC_401_ALLOWED,
+    rules: { "stapel/no-adhoc-401": "off" },
+  },
   {
     // The facade's provider adapters — the ONE legal home of vendor SDK
     // imports (§2.2 override; mirrors the FETCH_ALLOWED api-layer carve-out).
-    files: ["**/analytics/providers.{ts,js}", "**/analytics/providers/**"],
+    files: ["**/analytics/providers.{ts,js}", "**/analytics/src/providers.{ts,js}", "**/analytics/providers/**"],
     rules: { "stapel/no-direct-analytics-provider": "off" },
   },
   {
@@ -183,6 +223,10 @@ const recommended = [
       "stapel/known-event": "off",
       "stapel/no-direct-analytics-provider": "off",
       "stapel/demo-literal-meta": "off",
+      // Tests legitimately assert on raw storage state (the wipe-at-logout
+      // contract test greps localStorage directly) and on 401 fixtures.
+      "stapel/no-raw-storage": "off",
+      "stapel/no-adhoc-401": "off",
       // require-disable-description stays ON — disable hygiene applies everywhere.
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/eslint-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Stapel frontend guardrails as static lint rules (frontend-guardrails §2): no raw colours, no raw fetch, no raw-ramp imports, i18n-key existence, no hardcoded user-facing text — every rule reads the same generated artifacts (tokens manifest, i18n key registries) as the codegen, so lint and code never drift. Ships a flat-config `recommended` preset plus a self-contained stylelint preset for CSS.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@stapel/tokens": "^0.2.0"
+    "@stapel/tokens": "^0.4.0"
   },
   "peerDependencies": {
     "eslint": ">=9",

package/rules/no-adhoc-401.js

@@ -0,0 +1,68 @@
+// stapel/no-adhoc-401 — frontend-core-architecture-v2 §43.2.
+// 401 handling (single-flight refresh → retry once → SessionManager.sessionLost())
+// lives in ONE place: `@stapel/core`'s `createStapelClient` (`onAuthRefresh`
+// seam) + `SessionManager`. A module/service writing its own "if status is
+// 401, refresh/redirect/retry" branch bypasses the single-flight coalescing
+// and the logout-hook registry silently — the failure mode is invisible until
+// two concurrent requests both refresh and race each other. The recommended
+// preset turns this rule OFF for `@stapel/core`'s own client/session
+// internals (the ONE legal home), mirroring the no-raw-fetch api-layer
+// carve-out.
+
+// Named constant (not an inline literal in the comparison below) so the rule
+// passes ITSELF — its own `value === HTTP_UNAUTHORIZED` check must not read
+// as ad hoc 401 handling when the monorepo lints this file.
+const HTTP_UNAUTHORIZED = 401;
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow ad hoc 401 handling / auth interceptors outside @stapel/core's client and SessionManager.",
+    },
+    schema: [],
+    messages: {
+      literal401:
+        "Ad hoc 401 handling. 401s are handled ONCE, in @stapel/core's createStapelClient (onAuthRefresh seam) + SessionManager.refresh() — single-flight refresh, retry once, SessionManager.sessionLost() on failure (frontend-core-architecture-v2 §43.2). Wire onAuthRefresh to your SessionManager instead of branching on the status code here.",
+      interceptor:
+        "Ad hoc auth interceptor ({{what}}). Requests already go through createStapelClient, whose onAuthRefresh/onVerificationChallenge seams are the one legal place to intercept auth failures — see §43.2.",
+    },
+  },
+  create(context) {
+    function isNumeric401(node) {
+      return node.type === "Literal" && node.value === HTTP_UNAUTHORIZED;
+    }
+
+    return {
+      BinaryExpression(node) {
+        if (!["==", "===", "!=", "!=="].includes(node.operator)) return;
+        if (isNumeric401(node.left) || isNumeric401(node.right)) {
+          context.report({ node, messageId: "literal401" });
+        }
+      },
+
+      SwitchCase(node) {
+        if (node.test && isNumeric401(node.test)) {
+          context.report({ node, messageId: "literal401" });
+        }
+      },
+
+      // `client.interceptors.response.use(...)` / `axios.interceptors...` —
+      // axios-shaped ad hoc auth interceptors, regardless of the object.
+      MemberExpression(node) {
+        if (
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "interceptors"
+        ) {
+          context.report({
+            node,
+            messageId: "interceptor",
+            data: { what: "*.interceptors" },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-direct-analytics-provider.js

@@ -1,5 +1,6 @@
 // stapel/no-direct-analytics-provider — frontend-guardrails §2.2 / §3.
-// Analytics goes through the @stapel/core facade (consent gate, PII guard,
+// Analytics goes through the Stapel facade (the @stapel/core type seam,
+// implemented by @stapel/analytics): consent gate, PII guard,
 // offline queue, fan-out), NEVER straight into a vendor SDK. Importing a
 // provider package anywhere but the facade's provider-adapter module bypasses
 // consent and PII enforcement in one line — the cheapest F9 violation there
@@ -49,7 +50,7 @@ export default {
     ],
     messages: {
       directProvider:
-        'Direct analytics provider import "{{source}}". Emit through the @stapel/core facade instead — analytics.track(event, props) / tracked(event, props, handler) — which owns consent, PII guarding, and the offline queue (§3). Provider SDKs are wired ONCE, in the facade\'s provider adapter (analytics/providers.ts). See @stapel/core/llms.txt §analytics.',
+        'Direct analytics provider import "{{source}}". Emit through the Stapel analytics facade instead — analytics.track(event, props) / tracked(event, props, handler) — which owns consent, PII guarding, and the offline queue (§3). Provider SDKs are wired ONCE, in the facade\'s provider adapter (analytics/providers.ts — implementation: @stapel/analytics; type seam: @stapel/core).',
     },
   },
   create(context) {

package/rules/no-raw-storage.js

@@ -0,0 +1,126 @@
+// stapel/no-raw-storage — frontend-core-architecture-v2 §43.4.
+// `createRepository` (@stapel/core) is the ONE sanctioned client-side
+// persistence primitive: `scope: "user"` repositories auto-wipe on logout
+// (no opt-out) and are encrypted by default — a guarantee that only holds if
+// nothing else in the app reaches `localStorage`/`sessionStorage`/`indexedDB`
+// directly, since that data would never be torn down or encrypted. Direct
+// access is banned everywhere except `@stapel/core`'s own storage/repository
+// internals (the recommended preset turns this rule OFF there via a file
+// override, mirroring the no-raw-fetch api-layer carve-out).
+import { stapelSettings } from "../lib/data.js";
+
+const STORAGE_GLOBALS = new Set(["localStorage", "sessionStorage"]);
+const IDB_GLOBALS = new Set(["indexedDB"]);
+const GLOBAL_HOSTS = new Set(["window", "self", "globalThis"]);
+const BANNED_IMPORTS = new Set(["idb-keyval"]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow direct localStorage/sessionStorage/indexedDB access outside @stapel/core's repository layer.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          modules: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      rawStorage:
+        'Direct {{what}} access. Persist through createRepository(namespace, { scope, storage, encrypted }) (@stapel/core) instead — it is the one sanctioned client-side store: scope "user" auto-wipes on logout (no opt-out) and is encrypted by default, scope "app" survives logout. Raw storage is neither wiped nor encrypted (frontend-core-architecture-v2 §43.4).',
+      rawImport:
+        'Import of storage-backend package "{{source}}". Use createRepository() (@stapel/core) instead of building on this directly — see §43.4.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const extraModules = context.options[0]?.modules ?? [];
+    const bannedModules = new Set([
+      ...BANNED_IMPORTS,
+      ...(settings.storageModules ?? []),
+      ...extraModules,
+    ]);
+
+    function report(node, what) {
+      context.report({ node, messageId: "rawStorage", data: { what } });
+    }
+
+    function identifierName(node) {
+      return node.type === "Identifier" ? node.name : null;
+    }
+
+    function isStorageName(name) {
+      return STORAGE_GLOBALS.has(name) || IDB_GLOBALS.has(name);
+    }
+
+    return {
+      // Bare `localStorage` / `sessionStorage` / `indexedDB` uses — resolved
+      // through scope analysis so a local binding that merely SHARES the name
+      // (`function f(indexedDB) {…}`) is never flagged: only references that
+      // resolve to a global (env/globals config) or to nothing at all (the
+      // usual appearance of browser globals) are the real storage globals.
+      "Program:exit"(node) {
+        const globalScope = context.sourceCode.getScope(node);
+        // Unresolved references — no declaration anywhere in the file.
+        for (const ref of globalScope.through) {
+          const name = ref.identifier.name;
+          if (isStorageName(name)) report(ref.identifier, name);
+        }
+        // References that RESOLVE to a declared ambient global (a variable
+        // with no defs, injected via languageOptions.globals).
+        for (const name of [...STORAGE_GLOBALS, ...IDB_GLOBALS]) {
+          const variable = globalScope.set.get(name);
+          if (!variable || variable.defs.length > 0) continue;
+          for (const ref of variable.references) {
+            report(ref.identifier, name);
+          }
+        }
+      },
+
+      // `window.localStorage`, `self.indexedDB`, `globalThis.sessionStorage`.
+      MemberExpression(node) {
+        if (node.computed) return;
+        const objectName = identifierName(node.object);
+        const propertyName = identifierName(node.property);
+        if (
+          objectName &&
+          GLOBAL_HOSTS.has(objectName) &&
+          propertyName &&
+          (STORAGE_GLOBALS.has(propertyName) || IDB_GLOBALS.has(propertyName))
+        ) {
+          report(node, `${objectName}.${propertyName}`);
+        }
+      },
+
+      ImportDeclaration(node) {
+        if (bannedModules.has(node.source.value)) {
+          context.report({
+            node,
+            messageId: "rawImport",
+            data: { source: node.source.value },
+          });
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "require" &&
+          node.arguments[0]?.type === "Literal" &&
+          bannedModules.has(node.arguments[0].value)
+        ) {
+          context.report({
+            node,
+            messageId: "rawImport",
+            data: { source: node.arguments[0].value },
+          });
+        }
+      },
+    };
+  },
+};