@starci/eslint-canon-be 3.6.8 → 3.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/dist/app-composition.d.ts +1 -1
  3. package/dist/app-composition.js +18 -5
  4. package/dist/auth-passport.d.ts +14 -0
  5. package/dist/auth-passport.js +106 -0
  6. package/dist/index.js +4 -0
  7. package/dist/jwt-alg.js +1 -1
  8. package/dist/lib/hfs-view.d.ts +9 -0
  9. package/dist/module-layering.js +17 -4
  10. package/dist/no-raw-sql.d.ts +9 -0
  11. package/dist/no-raw-sql.js +78 -0
  12. package/package.json +1 -1
  13. package/runtime/knowledge/hfs/canon-pins.yaml +44 -24
  14. package/runtime/knowledge/hfs/fe-stack.yaml +4 -11
  15. package/runtime/knowledge/hfs/rules.yaml +179 -157
  16. package/runtime/knowledge/hfs/slots.yaml +185 -172
  17. package/runtime/scripts/hfs/architecture/canon-clones.mjs +1 -1
  18. package/runtime/scripts/hfs/architecture/entity-registry.mjs +53 -0
  19. package/runtime/scripts/hfs/architecture/{supabase-be.mjs → identity.mjs} +45 -15
  20. package/runtime/scripts/hfs/architecture/index.mjs +2 -3
  21. package/runtime/scripts/hfs/architecture/{supabase-ast.mjs → jwt-ast.mjs} +2 -103
  22. package/runtime/scripts/hfs/architecture/owners.mjs +11 -0
  23. package/runtime/scripts/hfs/architecture/register-once.mjs +1 -1
  24. package/runtime/scripts/hfs/architecture/schema-owner.mjs +29 -4
  25. package/runtime/scripts/hfs/architecture/server-action.mjs +3 -4
  26. package/runtime/scripts/hfs/architecture/side-boundary.mjs +1 -1
  27. package/runtime/scripts/hfs/architecture/{supabase-keys.mjs → sql-keys.mjs} +1 -1
  28. package/runtime/scripts/hfs/architecture/sql-owner.mjs +25 -27
  29. package/runtime/scripts/hfs/architecture/tiers.mjs +14 -3
  30. package/runtime/scripts/hfs/architecture/transport-owner.mjs +7 -3
  31. package/runtime/scripts/hfs/declaration-shape.mjs +15 -18
  32. package/runtime/scripts/hfs/manifest-shape.mjs +9 -5
  33. package/runtime/scripts/hfs/rule-params-shape.mjs +4 -1
  34. package/runtime/scripts/hfs/rules/database-constants.mjs +8 -10
  35. package/runtime/scripts/hfs/rules/database-migrations.mjs +3 -3
  36. package/runtime/scripts/hfs/slot-app-view.mjs +1 -1
  37. package/runtime/scripts/hfs/slots.mjs +8 -2
  38. package/runtime/scripts/lib/secret-patterns.mjs +2 -2
  39. package/runtime/scripts/hfs/architecture/supabase-tables.mjs +0 -50
  40. package/runtime/scripts/hfs/architecture/supabase.mjs +0 -226
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.7.1 - 2026-10-29
4
+
5
+ - Changed: the entity registry (persistence.md BE-PERSISTENCE-3, Debug ruling on lite-persistence-typeorm-entities): the bundled slot manifest 3.10.0 adds the lite slot `be.platform.database.entities`, the entity registry (slot fields `role: entity-registry` and `importedBy`, validated by the manifest shape); the bundled architecture machine reads it (`architecture/entity-registry.mjs`): `tier-direction` (R26 `BE_TIER_DIRECTION`) admits the registry's import of a domain or platform capability's `index.ts` that binds only that capability's `<c>Entities`, and `owner-export-bypass` (R30 `ARCH_OWNER_EXPORT_BYPASS`) admits a direct import of the registry from the files `importedBy` names (`apps/*/src/compose/*.ts`, `apps/*/src/app.module.ts`, `src/tests/world/**`); every other import of either shape stays refused, and full has no registry. `import-owner-entry` (R30) admits the deep path `@modules/platform/database/entities` from the same importers only. Spec: `src/entity-registry.spec.ts`.
6
+ - Changed: the bundled canon pins name hfs 4.10.1, eslint-canon-be 3.7.1, eslint-canon-fe 9.5.1 and the Grammar family 0.15.12.
7
+ - Changed: the owner-cycle check (R27 `ARCH_OWNER_CYCLE`) counts the entity registry as a unit of its own, not part of `platform/database`, so naming every `<c>Entities` closes no cycle among capabilities while any other platform/database file importing a domain still does (spec in `src/entity-registry.spec.ts`); the bundled rule catalog's R26 and R30 laws name the entity registry.
8
+
9
+ ## 3.7.0 - 2026-10-29
10
+
11
+ - Added: the `auth-passport` law (contexts/code/be/api-auth.md BE-AUTH-2): `own-jwks-only` (R329 `BE_AUTH_JWT_OWN_JWKS`) refuses `createRemoteJWKSet`, `decodeJwt` and `decodeProtectedHeader` of jose anywhere and `jwtVerify` outside `integrations/passport`; `refresh-token-cookie-only` (R330 `BE_AUTH_REFRESH_COOKIE`) refuses a `refreshToken`/`refresh_token` property or member and a refresh cookie set or cleared outside `integrations/passport`.
12
+ - Added: `no-raw-sql` (R334 `BE_PERSISTENCE_NO_RAW_SQL`, lite): no `.query(` and no `sql` template outside `platform/database`, and `callDbFunction` names only a listed database function.
13
+ - Changed: `no-raw-sql` also refuses a query builder that names no entity (`createQueryBuilder("orders", "o")`, `createQueryBuilder()`) and `getRepository(...)` outside `platform/database`: a builder is `createQueryBuilder(Entity, "alias")` on the injected EntityManager.
14
+ - Changed: `no-folder-reexport` admits, in lite only, a capability's `persistence/entities/index.ts` that declares its `<c>Entities` list (BE-PERSISTENCE-3); the machine `schema-owner` (R35) checks the lite shape (the list and its name in `PRIMARY_ENTITIES`), and the dead-export count already counts `<c>Entities` once `PRIMARY_ENTITIES` names it (spec added).
15
+ - Changed: `app-file-budget` (R246 `BE_APP_COMPOSITION_BUDGET`) counts a slot file's lines excluding import declarations, a multi-line import included, so naming one more capability costs no budget; the numbers are unchanged (`<app>.env.ts` 150 in both editions).
16
+ - Changed: the bundled slot manifest 3.9.0 replaces the lite `app.supabase*` slots with `app.db` (`db/migrations`, `db/migrations/archive`, `db/seed.sql`, the managed `db/bootstrap.sql`), `be.integrations.supabase` with `be.integrations.passport` and `be.integrations.object-storage`, removes `fe.route.callback`, sets lite `schemaAuthority: sql`, gives lite TypeORM entities in `be.persistence`, adds `ruleParams.be.dbFunctions`, and moves the S3 SDKs to `integrations/object-storage` and the identity libraries to `integrations/passport` in `infraOwners` (`@supabase/*`, `minio` and `bcrypt` nowhere); the bundled rule catalog retires R216, R217, R219, R254 and R287 and adds R328-R334, so `infra-import-owner` holds R328 `BE_AUTH_PASSPORT_OWNER` and R331 `BE_STORAGE_OWNER`; R36 runs in full only; `jwt-alg-pinned` reads `architecture/jwt-ast.mjs`; the bundled canon pins name hfs 4.10.0, eslint-canon-be 3.7.0, eslint-canon-fe 9.5.0 and the Grammar family 0.15.11, pin `@nestjs/passport` 11.0.5 (CommonJS on the Nest 11 line), `passport` 0.7.0, `passport-google-oauth20` 2.0.0, `passport-local` 1.0.0, `bcryptjs` 3.0.3 and their types (tokens are signed and verified with `jose`; `@nestjs/jwt` stays allowed in `integrations/passport` but unpinned), and drop `@supabase/ssr`, `@supabase/supabase-js` and the `supabase` CLI.
17
+
18
+
3
19
  ## 3.6.8 - 2026-10-29
4
20
 
5
21
  - Added: the `ai-gateway` law (contexts/code/be/ai.md). `provider-key-custody` (R326 `BE_AI_KEY_CUSTODY`) refuses an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, the one list: `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and the rest, with their `_FILE` twins) named in a literal, a member or a property anywhere but the gateway's custody owner `integrations/ai-gateway`, specs and the test world included. `ai-client-through-gateway` (R327 `BE_AI_GATEWAY_CLIENT`) lets code build only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai` (found by import), each from an inline options object with no spread, `configuration.baseURL` a member of a `<c>.options.ts` type and `apiKey` the `reveal()` of a `platform/config` `Secret`.
@@ -7,7 +7,7 @@ export declare const appCompositionTyped: RuleModule;
7
7
  export declare const appEnvRequired: RuleModule;
8
8
  /** R289: module lists in the app root contain only spreads of its own compose groups. */
9
9
  export declare const appModuleListInline: RuleModule;
10
- /** Each composition file of an app stays within the line budget its app slot names. */
10
+ /** Each composition file of an app stays within the line budget its app slot names, counted without its import lines. */
11
11
  export declare const appFileBudget: RuleModule;
12
12
  /** The rules this law contributes to the plugin. */
13
13
  export declare const rules: {
@@ -14,7 +14,9 @@
14
14
  * options files and composition groups receive the typed result of `read<App>Env(env: EnvSource)`.
15
15
  * - `app-file-budget` (`BE_APP_COMPOSITION_BUDGET`) holds each composition file to the line budget its app slot names
16
16
  * (`budget` of the slot, keyed by the same entry: `app.module.ts` 250, `<app>.env.ts` 150, `<app>.options.ts` 200, `compose/<area>.ts` 120,
17
- * `main.ts` 80). The budget is absolute, not a ratchet: an app root that outgrows it moves an area into a new group.
17
+ * `main.ts` 80), counted in lines EXCLUDING import declarations (a multi-line import counts none of its lines): an import
18
+ * is the cost of naming a capability, not composition. The budget is absolute, not a ratchet: an app root that outgrows it moves
19
+ * an area into a new group.
18
20
  *
19
21
  * R265 resolves composition from types, including renamed constructors, factories, maps and scheduler tables. All
20
22
  * three rules ask the slot view which entry a file matches; none keeps a path of its own.
@@ -564,14 +566,25 @@ export const appModuleListInline = {
564
566
  };
565
567
  },
566
568
  };
567
- /** Each composition file of an app stays within the line budget its app slot names. */
569
+ /** The lines of a source text that no import declaration (`import ...` or `import x = require(...)`) covers, one or many lines each. */
570
+ const linesExcludingImports = (text, body) => {
571
+ const covered = new Set();
572
+ for (const statement of body) {
573
+ if ((statement.type !== "ImportDeclaration" && statement.type !== "TSImportEqualsDeclaration") || !statement.loc)
574
+ continue;
575
+ for (let line = statement.loc.start.line; line <= statement.loc.end.line; line += 1)
576
+ covered.add(line);
577
+ }
578
+ return lineCount(text) - covered.size;
579
+ };
580
+ /** Each composition file of an app stays within the line budget its app slot names, counted without its import lines. */
568
581
  export const appFileBudget = {
569
582
  meta: {
570
583
  type: "problem",
571
- docs: { description: "`main.ts`, `app.module.ts`, `<app>.env.ts`, `<app>.options.ts` and `compose/<area>.ts` stay within the line budget of their app slot." },
584
+ docs: { description: "`main.ts`, `app.module.ts`, `<app>.env.ts`, `<app>.options.ts` and `compose/<area>.ts` stay within the line budget of their app slot, counted without import lines." },
572
585
  schema: [],
573
586
  messages: {
574
- over: "This {{role}} has {{lines}} lines, over its budget of {{max}} (the `budget` of slot {{slot}}). {{fix}}",
587
+ over: "This {{role}} has {{lines}} lines excluding imports, over its budget of {{max}} (the `budget` of slot {{slot}}). {{fix}}",
575
588
  },
576
589
  },
577
590
  create(context) {
@@ -592,7 +605,7 @@ export const appFileBudget = {
592
605
  : "Move one area of the composition into its own group `apps/<app>/src/compose/<area>.ts` and spread it in `app.module.ts`.";
593
606
  return {
594
607
  "Program:exit"(node) {
595
- const lines = lineCount((context.sourceCode || context.getSourceCode()).text);
608
+ const lines = linesExcludingImports((context.sourceCode || context.getSourceCode()).text, node.body);
596
609
  if (lines > max)
597
610
  context.report({ node, loc: { line: 1, column: 0 }, messageId: "over", data: { role: role.entry, lines, max, slot: role.slot, fix } });
598
611
  },
@@ -0,0 +1,14 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** The owner id (`<tier>/<capability>`) of the lite identity integration. */
3
+ export declare const PASSPORT_OWNER = "integrations/passport";
4
+ /** A lite principal comes only from the app's own verified token. */
5
+ export declare const ownJwksOnly: RuleModule;
6
+ /** A refresh token lives only in the integration's httpOnly cookie. */
7
+ export declare const refreshTokenCookieOnly: RuleModule;
8
+ /** The rules of the lite identity law, by name. */
9
+ export declare const rules: {
10
+ "own-jwks-only": RuleModule;
11
+ "refresh-token-cookie-only": RuleModule;
12
+ };
13
+ /** Both rules on at error. */
14
+ export declare const recommended: Recommended;
@@ -0,0 +1,106 @@
1
+ /**
2
+ * The rules of the lite identity (catalog R329 `BE_AUTH_JWT_OWN_JWKS`, R330 `BE_AUTH_REFRESH_COOKIE`; contexts/code/be/api-auth.md
3
+ * BE-AUTH-2 and BE-AUTH-3). Which owner may import the identity and S3 libraries at all is the infrastructure table of the slot
4
+ * manifest (`ruleParams.be.infraOwners`, judged by `infra-import-owner`: R328 `BE_AUTH_PASSPORT_OWNER`, R331 `BE_STORAGE_OWNER`).
5
+ *
6
+ * - `own-jwks-only`: the app verifies only its own access tokens. `createRemoteJWKSet` (a remote identity provider's key set),
7
+ * `decodeJwt` and `decodeProtectedHeader` (a token read without its signature) are refused wherever jose is imported, and
8
+ * `jwtVerify` is imported only by `integrations/passport`. The architecture machine (`own-jwks-principal`) proves the rest:
9
+ * the verifier checks `createLocalJWKSet` over the app's keys with issuer, audience and algorithms pinned.
10
+ * - `refresh-token-cookie-only`: a refresh token never travels in a body. Outside `integrations/passport` no object literal,
11
+ * class property or type member is named `refreshToken` or `refresh_token`, and no `.cookie()`/`.clearCookie()` call names a
12
+ * refresh cookie: the cookie is set, rotated and cleared only by the integration's `setRefreshCookie`/`clearRefreshCookie`.
13
+ * Its attributes (httpOnly, Secure, SameSite=Strict, the refresh path) are `response-cookie-attributes` (R141) and the
14
+ * integration's own spec; rotation with reuse detection is held by the identity domain's spec and review.
15
+ */
16
+ import { keyName, staticText } from "./lib/ast.js";
17
+ import { hfsOf } from "./lib/hfs.js";
18
+ /** The owner id (`<tier>/<capability>`) of the lite identity integration. */
19
+ export const PASSPORT_OWNER = "integrations/passport";
20
+ /** The jose exports no file uses: a remote key set and the unverified decoders. */
21
+ const FORBIDDEN_JOSE = new Set(["createRemoteJWKSet", "decodeJwt", "decodeProtectedHeader"]);
22
+ const REFRESH_NAME = /^refresh_?token$/i;
23
+ const REFRESH_COOKIE = /refresh/i;
24
+ /** The owner id of a file: the last two segments of its owner root, or null when no owner holds it. */
25
+ const ownerIdOf = (context, filename) => {
26
+ const root = hfsOf(context).ownerOf(filename);
27
+ return root === null ? null : root.split("/").slice(-2).join("/");
28
+ };
29
+ /** A lite principal comes only from the app's own verified token. */
30
+ export const ownJwksOnly = {
31
+ meta: {
32
+ type: "problem",
33
+ docs: { description: "Only integrations/passport verifies a token (jose jwtVerify over the app's own key set); no remote JWKS and no unverified decode anywhere." },
34
+ schema: [],
35
+ messages: {
36
+ forbidden: "`{{name}}` of jose {{why}}. The app verifies only its own access tokens through the token kit of `integrations/passport` (jwtVerify over createLocalJWKSet).",
37
+ verifier: "`jwtVerify` is imported outside `integrations/passport`. Verify a token through the integration's verifier (`OWN_TOKEN_VERIFIER`), which domain/identity turns into the principal.",
38
+ },
39
+ },
40
+ create(context) {
41
+ const owner = ownerIdOf(context, context.filename) === PASSPORT_OWNER;
42
+ return {
43
+ ImportDeclaration(node) {
44
+ if (node.source.value !== "jose")
45
+ return;
46
+ for (const specifier of node.specifiers) {
47
+ if (specifier.type !== "ImportSpecifier")
48
+ continue;
49
+ const name = keyName(specifier.imported);
50
+ if (name !== null && FORBIDDEN_JOSE.has(name)) {
51
+ context.report({ node: specifier, messageId: "forbidden", data: { name, why: name === "createRemoteJWKSet" ? "trusts another issuer's key set" : "reads a token without proving its signature" } });
52
+ }
53
+ else if (name === "jwtVerify" && !owner)
54
+ context.report({ node: specifier, messageId: "verifier" });
55
+ }
56
+ },
57
+ };
58
+ },
59
+ };
60
+ /** A refresh token lives only in the integration's httpOnly cookie. */
61
+ export const refreshTokenCookieOnly = {
62
+ meta: {
63
+ type: "problem",
64
+ docs: { description: "A refresh token never appears as a body field, and only integrations/passport sets or clears the refresh cookie." },
65
+ schema: [],
66
+ messages: {
67
+ field: "`{{name}}` carries a refresh token in a body. The refresh token lives only in the httpOnly, Secure, SameSite=Strict cookie that `integrations/passport` rotates (`setRefreshCookie`).",
68
+ cookie: "`{{call}}` names the refresh cookie outside `integrations/passport`. Set and clear it only through `setRefreshCookie` and `clearRefreshCookie`.",
69
+ },
70
+ },
71
+ create(context) {
72
+ if (ownerIdOf(context, context.filename) === PASSPORT_OWNER)
73
+ return {};
74
+ const field = (node, key, computed) => {
75
+ const name = computed ? null : keyName(key);
76
+ if (name !== null && REFRESH_NAME.test(name))
77
+ context.report({ node, messageId: "field", data: { name } });
78
+ };
79
+ return {
80
+ Property(node) {
81
+ field(node, node.key, node.computed);
82
+ },
83
+ PropertyDefinition(node) {
84
+ field(node, node.key, node.computed);
85
+ },
86
+ TSPropertySignature(node) {
87
+ field(node, node.key, node.computed);
88
+ },
89
+ CallExpression(node) {
90
+ if (node.callee.type !== "MemberExpression" || node.callee.computed)
91
+ return;
92
+ const method = keyName(node.callee.property);
93
+ if (method !== "cookie" && method !== "clearCookie")
94
+ return;
95
+ const [first] = node.arguments;
96
+ const name = first === undefined ? null : staticText(first);
97
+ if (name !== null && REFRESH_COOKIE.test(name))
98
+ context.report({ node, messageId: "cookie", data: { call: `.${method}("${name}")` } });
99
+ },
100
+ };
101
+ },
102
+ };
103
+ /** The rules of the lite identity law, by name. */
104
+ export const rules = { "own-jwks-only": ownJwksOnly, "refresh-token-cookie-only": refreshTokenCookieOnly };
105
+ /** Both rules on at error. */
106
+ export const recommended = { "starci-be/own-jwks-only": "error", "starci-be/refresh-token-cookie-only": "error" };
package/dist/index.js CHANGED
@@ -19,6 +19,8 @@
19
19
  import { buildBeConfig } from "./lib/config.js";
20
20
  import { pluginForEdition } from "./lib/edition.js";
21
21
  import { recommended as aiGatewayRecommended, rules as aiGatewayRules } from "./ai-gateway.js";
22
+ import { recommended as authPassportRecommended, rules as authPassportRules } from "./auth-passport.js";
23
+ import { recommended as noRawSqlRecommended, rules as noRawSqlRules } from "./no-raw-sql.js";
22
24
  import { recommended as ambientIdRecommended, rules as ambientIdRules } from "./ambient-id.js";
23
25
  import { recommended as appCompositionRecommended, rules as appCompositionRules } from "./app-composition.js";
24
26
  import { recommended as asyncDisciplineRecommended, rules as asyncDisciplineRules } from "./async-discipline.js";
@@ -74,6 +76,8 @@ import { recommended as sonarParityRecommended, rules as sonarParityRules } from
74
76
  const CONTRIBUTIONS = [
75
77
  { law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
76
78
  { law: "ai-gateway", rules: aiGatewayRules, recommended: aiGatewayRecommended },
79
+ { law: "auth-passport", rules: authPassportRules, recommended: authPassportRecommended },
80
+ { law: "no-raw-sql", rules: noRawSqlRules, recommended: noRawSqlRecommended },
77
81
  { law: "ambient-id", rules: ambientIdRules, recommended: ambientIdRecommended },
78
82
  { law: "app-composition", rules: appCompositionRules, recommended: appCompositionRecommended },
79
83
  { law: "async-discipline", rules: asyncDisciplineRules, recommended: asyncDisciplineRecommended },
package/dist/jwt-alg.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import ts from "typescript";
3
3
  import { typed } from "./lib/types.js";
4
4
  import { isDeclarationFile } from "./lib/path.js";
5
- import { jwtPolicyProblems } from "../runtime/scripts/hfs/architecture/supabase-ast.mjs";
5
+ import { jwtPolicyProblems } from "../runtime/scripts/hfs/architecture/jwt-ast.mjs";
6
6
  /** The text of a module specifier (a string literal), or undefined for any other expression. */
7
7
  const specifierText = (specifier) => ("text" in specifier ? specifier.text : undefined);
8
8
  /** Recognize jose imports and aliases through their declarations, including namespace imports. */
@@ -51,6 +51,10 @@ export interface HfsSlot {
51
51
  readonly trigger?: string;
52
52
  readonly coverage?: string;
53
53
  readonly allows?: readonly string[];
54
+ /** The one special part a file slot plays that a rule reads: `entity-registry` (persistence.md BE-PERSISTENCE-3). */
55
+ readonly role?: string;
56
+ /** The side-relative path patterns of the only files that may import this file by deep path. */
57
+ readonly importedBy?: readonly string[];
54
58
  }
55
59
  /** A unit-tested role (`ruleParams.be.unitRoles`). */
56
60
  export interface HfsUnitRole {
@@ -98,6 +102,11 @@ export interface HfsRuleParams {
98
102
  readonly logicRoles?: readonly string[];
99
103
  readonly valueRoles?: readonly string[];
100
104
  readonly thinRoles?: readonly string[];
105
+ /** The database functions `callDbFunction` of platform/database may call, each with its reason (`ruleParams.be.dbFunctions` plus hfs.json `sides.be.dbFunctions`). */
106
+ readonly dbFunctions?: readonly {
107
+ readonly name: string;
108
+ readonly reason: string;
109
+ }[];
101
110
  }
102
111
  /** The frozen view of one side of an app. */
103
112
  export interface HfsView {
@@ -7,12 +7,16 @@
7
7
  *
8
8
  * - `import-owner-entry` - a cross-owner import targets the owner's `index.ts` (`@modules/domain/plan`,
9
9
  * `@features/api/plan`), never a file inside it, and an alias that names a tier but no owner (`@modules/domain`) names
10
- * nothing importable. A same-owner import is relative and never goes through the owner's own `index.ts`.
10
+ * nothing importable. A same-owner import is relative and never goes through the owner's own `index.ts`. The entity
11
+ * registry (slot role `entity-registry`, `@modules/platform/database/entities`) is the one file reached by deep path, and only
12
+ * from the files its slot's `importedBy` names (persistence.md BE-PERSISTENCE-3).
11
13
  * - `no-self-module-alias` - inside an owner, imports are relative, never the owner's own alias.
12
14
  * - `no-relative-capability-escape` - a relative import never walks out of its own owner.
13
15
  * - `no-folder-reexport` - a specifier that names a directory is refused; a nested `index.ts` (any index that is not
14
16
  * at its owner's root) is refused; an owner's `index.ts` holds only named `export { }` / `export type { }` lines
15
- * re-exporting from files, never `export *`, never a declaration, and at most `budget.indexExports` names.
17
+ * re-exporting from files, never `export *`, never a declaration, and at most `budget.indexExports` names. One
18
+ * sanctioned exception, lite only: `<owner>/persistence/entities/index.ts` imports its entity files and declares the
19
+ * owner's `<c>Entities` array, the list `platform/database/entities.ts` names (persistence.md BE-PERSISTENCE-3).
16
20
  *
17
21
  * "Which owner does this file belong to" is `hfs.ownerOf`; "which owner does this specifier reach" is the same question
18
22
  * asked of the file the specifier resolves to. Nothing here touches disk.
@@ -21,6 +25,7 @@ import { posix } from "node:path";
21
25
  import { hfsOf } from "./lib/hfs.js";
22
26
  import { baseName } from "./lib/ports.js";
23
27
  import { resolveAlias } from "./lib/specifier.js";
28
+ import { ENTITY_REGISTRY_ROLE, registryImporter } from "../runtime/scripts/hfs/architecture/entity-registry.mjs";
24
29
  /** The tiers whose files belong to an owner with a root `index.ts`. */
25
30
  const OWNER_TIERS = new Set(["feature", "domain", "platform", "integrations"]);
26
31
  /**
@@ -62,6 +67,12 @@ const onSpecifiers = (check) => ({
62
67
  /** The public-surface width: the file's slot budget, else its tier's owner-slot budget, else a back-end owner default. */
63
68
  const indexExportBudget = (hfs, filename) => [hfs.slotOf(filename), `be.${hfs.tierOf(filename)}`, "be.domain", "be.feature"].map((id) => (id ? hfs.slot(id)?.budget?.indexExports : undefined)).find(Number.isInteger);
64
69
  // -- R30: import-owner-entry -----------------------------------------------------------------------
70
+ /** Whether `filename` may reach the import path `target` (absolute, no extension) by deep path: it is the entity registry and its slot's `importedBy` names the importer. */
71
+ const importsRegistry = (hfs, filename, target) => {
72
+ const id = hfs.slotOf(`${target}.ts`);
73
+ const slot = id ? hfs.slot(id) : undefined;
74
+ return slot?.role === ENTITY_REGISTRY_ROLE && registryImporter(null, slot, hfs.relative(filename));
75
+ };
65
76
  /**
66
77
  * A cross-owner import targets the owner's public entry: the alias and the owner, nothing deeper. A same-owner import
67
78
  * is relative and never goes through the owner's own `index.ts` (BE-CONVENTION 2.4).
@@ -109,7 +120,7 @@ export const importOwnerEntry = {
109
120
  return;
110
121
  const ownerAbsolute = absolute(hfs, owner);
111
122
  const inside = alias.target === ownerAbsolute ? "" : alias.target.slice(ownerAbsolute.length + 1);
112
- if (inside !== "" && inside !== "index")
123
+ if (inside !== "" && inside !== "index" && !importsRegistry(hfs, filename, alias.target))
113
124
  context.report({ node, messageId: "deep", data: { specifier } });
114
125
  });
115
126
  },
@@ -140,6 +151,8 @@ export const noSelfModuleAlias = {
140
151
  },
141
152
  };
142
153
  // -- no-folder-reexport ----------------------------------------------------------------------------
154
+ /** The lite entity list of a capability: `<owner>/persistence/entities/index.ts` (BE-PERSISTENCE-3). */
155
+ const LITE_ENTITY_LIST = /(?:^|\/)persistence\/entities\/index\.ts$/;
143
156
  /** Whether a file is an index by its role name. */
144
157
  const isIndexFile = (filename) => /^index\.[cm]?[jt]sx?$/.test(baseName(filename));
145
158
  /**
@@ -170,7 +183,7 @@ export const noFolderReexport = {
170
183
  create(context) {
171
184
  const filename = context.filename || context.getFilename();
172
185
  const hfs = hfsOf(context);
173
- const isIndex = isIndexFile(filename);
186
+ const isIndex = isIndexFile(filename) && !(hfs.edition === "lite" && LITE_ENTITY_LIST.test(hfs.relative(filename)));
174
187
  const max = indexExportBudget(hfs, filename);
175
188
  let count = 0;
176
189
  return {
@@ -0,0 +1,9 @@
1
+ import type { RuleModule, Recommended } from "./lib/rule.js";
2
+ /** No raw SQL in lite domain or feature code: entities on the EntityManager carry every read and write. */
3
+ export declare const noRawSql: RuleModule;
4
+ /** The rule of the lite persistence law, by name. */
5
+ export declare const rules: {
6
+ "no-raw-sql": RuleModule;
7
+ };
8
+ /** On at error; the catalog limits it to lite. */
9
+ export declare const recommended: Recommended;
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The lite persistence law (catalog R334 `BE_PERSISTENCE_NO_RAW_SQL`; contexts/code/be/persistence.md BE-PERSISTENCE-1 and -2):
3
+ * domain and feature code reads and writes through TypeORM entities on the injected EntityManager (`find`, `save`, `update`,
4
+ * `delete`, `upsert`, `createQueryBuilder(Entity, "alias")` with named parameters), never through raw SQL.
5
+ *
6
+ * - `no-raw-sql` refuses, outside `platform/database`, every `.query(` call and every `sql` tagged template. A database function
7
+ * TypeORM cannot express is called through the typed helpers of `platform/database` (`callDbFunction(manager, name, args)`,
8
+ * `advisoryXactLock(manager, key)`, `notify(manager, channel, payload)`), and a literal function name handed to
9
+ * `callDbFunction` must be one `ruleParams.be.dbFunctions` lists (the canon's pg built-ins plus hfs.json `sides.be.dbFunctions`).
10
+ * The allow-list governs WHICH functions may be called, the helper WHERE the SQL is built. A query builder names its entity
11
+ * (`createQueryBuilder(Entity, "alias")`): a builder over a table-name string, a builder with no entity, and a
12
+ * `getRepository(...)` are refused, because they bypass the entity mapping. The rule runs in lite only (the
13
+ * catalog's `editions`); full keeps R36.
14
+ *
15
+ * Schema authority stays `db/migrations/*.sql`; whether the entities match it is `BE_ENTITY_SCHEMA_DRIFT` of `starci app db drift`.
16
+ */
17
+ import { staticText } from "./lib/ast.js";
18
+ import { hfsOf } from "./lib/hfs.js";
19
+ /** The owner id (`<tier>/<capability>`) that keeps the migration runner and the database-function helpers. */
20
+ const DATABASE_OWNER = "platform/database";
21
+ /** The helper of platform/database whose second argument names the function it calls. */
22
+ const CALL_HELPER = "callDbFunction";
23
+ /** True when a builder's first argument can be an entity class: neither absent nor a string. */
24
+ const namesEntity = (argument) => {
25
+ if (argument === undefined || argument === null || typeof argument !== "object")
26
+ return false;
27
+ const node = argument;
28
+ return !((node.type === "Literal" && typeof node.value === "string") || node.type === "TemplateLiteral");
29
+ };
30
+ /** No raw SQL in lite domain or feature code: entities on the EntityManager carry every read and write. */
31
+ export const noRawSql = {
32
+ meta: {
33
+ type: "problem",
34
+ docs: { description: "Lite domain and feature code uses TypeORM entities on the EntityManager; `.query(` and `sql` templates stay in platform/database, and callDbFunction names only listed functions." },
35
+ schema: [],
36
+ messages: {
37
+ query: "`.query(` runs raw SQL outside `platform/database`. Read and write through the entity on the EntityManager (`find`, `save`, `update`, `upsert`, `createQueryBuilder(Entity, \"alias\")` with named parameters); call a database function TypeORM cannot express through `callDbFunction(manager, name, args)` (or `advisoryXactLock`, `notify`) of `platform/database`.",
38
+ template: "A `sql` template outside `platform/database`. Lite persistence maps tables with TypeORM entities; build the query with the EntityManager or `createQueryBuilder`, or call a database function through `callDbFunction`.",
39
+ builder: "A query builder must name its entity: `manager.createQueryBuilder(Entity, \"alias\")` on the injected EntityManager. A table-name string, a builder with no entity and a Repository bypass the entity mapping.",
40
+ unlisted: "`{{name}}` is not a listed database function. Add it to hfs.json `sides.be.dbFunctions` with the reason TypeORM cannot express it, or map the work with an entity.",
41
+ },
42
+ },
43
+ create(context) {
44
+ const hfs = hfsOf(context);
45
+ const root = hfs.ownerOf(context.filename);
46
+ const inDatabase = root !== null && root.split("/").slice(-2).join("/") === DATABASE_OWNER;
47
+ const listed = new Set((hfs.ruleParams.dbFunctions ?? []).map((entry) => entry.name));
48
+ return {
49
+ CallExpression(node) {
50
+ const callee = node.callee;
51
+ if (callee.type === "Identifier" && callee.name === CALL_HELPER) {
52
+ const name = node.arguments[1] === undefined ? null : staticText(node.arguments[1]);
53
+ if (name !== null && !listed.has(name))
54
+ context.report({ node, messageId: "unlisted", data: { name } });
55
+ return;
56
+ }
57
+ if (inDatabase || callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier")
58
+ return;
59
+ const method = callee.property.name;
60
+ if (method === "query")
61
+ context.report({ node, messageId: "query" });
62
+ else if (method === "getRepository")
63
+ context.report({ node, messageId: "builder" });
64
+ else if (method === "createQueryBuilder" && !namesEntity(node.arguments[0]))
65
+ context.report({ node, messageId: "builder" });
66
+ },
67
+ TaggedTemplateExpression(node) {
68
+ if (inDatabase || node.tag.type !== "Identifier" || node.tag.name !== "sql")
69
+ return;
70
+ context.report({ node, messageId: "template" });
71
+ },
72
+ };
73
+ },
74
+ };
75
+ /** The rule of the lite persistence law, by name. */
76
+ export const rules = { "no-raw-sql": noRawSql };
77
+ /** On at error; the catalog limits it to lite. */
78
+ export const recommended = { "starci-be/no-raw-sql": "error" };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.6.8",
3
+ "version": "3.7.1",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
33
33
  '@starci/grammar':
34
- version: 0.15.10
34
+ version: 0.15.12
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.6.8
41
+ version: 3.7.1
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.4.9
48
+ version: 9.5.1
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.15.10
55
+ version: 0.15.12
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.15.10
62
+ version: 0.15.12
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -85,12 +85,12 @@ pins:
85
85
  side: both
86
86
  source: packages/prettier-config/package.json
87
87
  '@starci/jest-preset':
88
- version: 2.4.1
88
+ version: 2.5.0
89
89
  group: starci
90
90
  install: registry
91
91
  side: be
92
92
  source: packages/jest-preset/package.json
93
- why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
93
+ why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
94
94
  '@starci/test-world':
95
95
  version: 1.2.3
96
96
  group: starci
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
108
108
  '@starci/hfs':
109
- version: 4.9.11
109
+ version: 4.10.1
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -543,7 +543,7 @@ pins:
543
543
  version: 3.1150.0
544
544
  group: framework
545
545
  side: be
546
- why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces, Supabase Storage); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
546
+ why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
547
547
  '@aws-sdk/s3-request-presigner':
548
548
  version: 3.1150.0
549
549
  group: framework
@@ -594,27 +594,47 @@ pins:
594
594
  group: framework
595
595
  side: be
596
596
  why: 'the Express 5 integration @nestjs/apollo loads at boot (R111 nestjs-apollo-express5, knowledge/hfs/peer-integrations.yaml); every api app that serves GraphQL installs it; the latest registry version on 2026-10-13.'
597
- # --- Supabase lite
598
- '@supabase/ssr':
599
- version: 0.12.7
597
+ # --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
598
+ '@nestjs/passport':
599
+ version: 11.0.5
600
600
  group: framework
601
- side: fe
602
- why: the one server/browser client factory for a lite Next app; exact version registry-checked for the lite scaffold.
603
- '@supabase/supabase-js':
604
- version: 2.117.2
601
+ side: be
602
+ why: 'PassportStrategy of integrations/passport; 11.0.5 is CommonJS on the Nest 11 line (12.0.0 is ESM-only and breaks Nest 11 jest under the CommonJS transform of @starci/jest-preset), as nivo-lite runs it.'
603
+ passport:
604
+ version: 0.7.0
605
605
  group: framework
606
- side: both
607
- why: the generated Database-typed client used by the FE data owner and the BE Auth/Storage integration.
606
+ side: be
607
+ why: the strategy runtime under @nestjs/passport (its peer range ^0.5 || ^0.6 || ^0.7).
608
+ passport-google-oauth20:
609
+ version: 2.0.0
610
+ group: framework
611
+ side: be
612
+ why: Google OAuth 2.0 (authorization code with state and PKCE) of integrations/passport.
613
+ passport-local:
614
+ version: 1.0.0
615
+ group: framework
616
+ side: be
617
+ why: the email and password strategy of integrations/passport.
618
+ bcryptjs:
619
+ version: 3.0.3
620
+ group: framework
621
+ side: be
622
+ why: 'bcrypt in pure JavaScript (no native build on the alpine image); verifies the $2a$/$2b$ hashes auth.users carries over.'
623
+ '@types/passport-google-oauth20':
624
+ version: 2.0.17
625
+ group: framework
626
+ side: be
627
+ why: types of passport-google-oauth20.
628
+ '@types/passport-local':
629
+ version: 1.0.38
630
+ group: framework
631
+ side: be
632
+ why: types of passport-local.
608
633
  jose:
609
634
  version: 6.2.12
610
635
  group: framework
611
636
  side: be
612
- why: verifies Supabase access tokens against the project JWKS with issuer, audience, expiry and algorithm checks.
613
- supabase:
614
- version: 2.119.0
615
- group: tooling
616
- side: both
617
- why: the root CLI wrapper owns local schema lifecycle and generates the committed database types.
637
+ why: signs the app's own ES256 access tokens and verifies them against its own key set (createLocalJWKSet) in integrations/passport.
618
638
  class-transformer:
619
639
  version: 0.5.1
620
640
  group: framework
@@ -37,10 +37,10 @@ concerns:
37
37
  - id: rest
38
38
  tier: core
39
39
  packages: [axios]
40
- home: [fe.modules.api]
40
+ home: [fe.modules.api, fe.modules.auth]
41
41
  pattern: FE-API-REST
42
42
  forbids: [ky, superagent, node-fetch, cross-fetch, isomorphic-fetch]
43
- why: modules/api/rest/<area>/*.ts for uploads, presigned URLs and auth endpoints only; GraphQL carries every other call.
43
+ why: modules/api/rest/<area>/*.ts for uploads and presigned URLs, and modules/auth/auth-door.ts for the app's own auth doors only; GraphQL carries every other call.
44
44
  - id: data
45
45
  tier: core
46
46
  packages: [swr]
@@ -99,8 +99,8 @@ concerns:
99
99
  packages: []
100
100
  home: [fe.modules.auth]
101
101
  pattern: FE-AUTH
102
- forbids: []
103
- why: modules/auth is the identity-provider client (lite - the @supabase/supabase-js auth client; full - the app's IdP client); it yields the session and the access token for the Apollo link and never reads data.
102
+ forbids: ['@supabase/supabase-js', '@supabase/ssr', '@supabase/auth-js']
103
+ why: modules/auth is the session issuer's client (lite - auth-door.ts over the app's own back-end auth doors with the in-memory token store; full - the app's IdP client); it yields the session and the access token for the Apollo link and never reads data.
104
104
  - id: i18n
105
105
  tier: core
106
106
  packages: [next-intl]
@@ -256,13 +256,6 @@ concerns:
256
256
  pattern: FE-RULE-OWNERSHIP
257
257
  forbids: []
258
258
  why: The selected Grammar family's lint package runs beside the universal front-end canon; the family catalog declares the package and factory.
259
- - id: auth-supabase
260
- tier: opt
261
- packages: ['@supabase/supabase-js', '@supabase/ssr']
262
- home: [fe.modules.auth]
263
- pattern: FE-AUTH
264
- forbids: []
265
- why: the lite auth provider client and PKCE server cookie adapter, confined to modules/auth; data still goes through the back end.
266
259
  - id: framework-support
267
260
  tier: opt
268
261
  packages: [server-only, rxjs]