create-astram-app 0.7.0 → 0.8.0

package/README.md

@@ -64,9 +64,14 @@ my-app/
 └── README.md                  how to run + how to add features the framework way
 ```
 
-`server/` scripts: `dev`, `build`, `start`, `test`, `lint`, `migration:run`,
+`server/` scripts: `dev`, `build`, `start`, `test`, `lint`, `lint:wall`, `migration:run`,
 `migration:status`, `migration:revert`, `guide:sync`.
 
+The wall (`eslint.config.mjs`, plus the `lint:wall` grep for `/internal` and
+`node_modules/@astram` imports under `src/features`, run by `lint`) catches accidental use;
+deliberate bypass (`.call`/`.apply`, a computed `pool[m]()`, an aliased `require`) is a
+code-review matter.
+
 ## The frontend (`--with-frontend` / `astram-add-frontend`)
 
 A Vite + React + shadcn/ui app whose views you own and edit; the auth and API logic comes from
@@ -96,7 +101,6 @@ Redis). Its header comment shows the full wiring. In short:
 
 ```ts
 const rootIds: string[] = [/* platform-admin user uuids, read from your config */];
-const authzPool = createIdentityAuthzPool();         // from @astram/identity/internal; never export it
 
 imports: [
   ShieldModule.forRoot({
@@ -105,12 +109,15 @@ imports: [
     rootIds,
     identityActionKeys: identityAuthActionKeys,
     identityControlPlaneKeys,
-    recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]),
   }),
   IdentityFeatureModule.forRoot({ rootIds, extraObjects: [/* YourType */] }),
 ],
 ```
 
+`IdentityFeatureModule` builds the record authorization from its `extraObjects` and `ShieldModule`
+decides with it, so your own object types are listed once. Do not pass `recordAuthorization` or
+`decisionAuthority` to `ShieldModule` next to it: boot fails.
+
 ## Production requirements
 
 With `auth: true`, check every item before the first production deploy.
@@ -134,12 +141,32 @@ With `auth: true`, check every item before the first production deploy.
   check your production ACL).
 - **A custom `credentialResolver`** (`ShieldModule.forRoot({ credentialResolver })`) replaces the
   framework's resolver, and with it three login checks that you then own:
-  - **MFA enforcement:** return `requiredFactors: ['totp']` for every user with a confirmed MFA
-    device. Return `[]` and that user signs in with the password alone.
+  - **MFA enforcement:** return `requiredFactors: [{ factor: 'totp', secret }]` for every user
+    with a confirmed MFA device, where `secret` is the device's TOTP shared secret (several
+    devices: one entry, secrets joined with `\n`, as the built-in resolver does). A plain
+    `['totp']` does not type-check and leaves the user stuck at `mfa_required`. Return `[]` (or
+    omit the field) and that user signs in with the password alone.
   - **Disabled accounts:** return `null` for an account that must not sign in (the built-in
     resolver does this for `shield_app.users.u_status` other than `active`).
   - **Lockout keying:** the per-account lockout is keyed on the `id` you return, so return the
     same stable id for every spelling of the user's login hint.
+  ```ts
+  import type { CredentialResolver, ResolvedCredential } from '@astram/guard';
+
+  export class DirectoryCredentialResolver implements CredentialResolver {
+    async resolve(identityHint: string): Promise<ResolvedCredential | null> {
+      const user = await directory.findByLogin(identityHint.trim().toLowerCase());
+      if (!user || user.status !== 'active') return null; // unknown or disabled: same answer
+      const secrets = await directory.confirmedTotpSecrets(user.id);
+      return {
+        passwordHash: user.passwordHash,
+        claims: { id: user.id, tenantId: user.companyId, roleIds: user.roleIds }, // stable id
+        requiredFactors: secrets.length ? [{ factor: 'totp', secret: secrets.join('\n') }] : [],
+      };
+    }
+  }
+  ```
+
   The authenticator's other protections (decoy verify, no account enumeration, no secret leaks,
   TOTP limiter and replay guard) still apply.
 - **`rootIds`.** Pass the same platform-administrator user uuids to `ShieldModule.forRoot` and
@@ -166,6 +193,81 @@ With `auth: true`, check every item before the first production deploy.
   in-flight `/auth/refresh` per session). Concurrent refreshes of the same token can trip reuse
   detection, which revokes the session (the user must sign in again).
 
+## Upgrading from 0.7.x
+
+create-astram-app 0.8 pairs with `@astram/identity` 0.7 and `@astram/guard` 0.10 (breaking wiring
+change). `IdentityFeatureModule` now builds the record authorization itself, from its own
+`extraObjects`, and `ShieldModule` decides with it. Before, the app built it separately with
+`buildIdentityRecordAuthorization(authzPool, extraObjects)`, and an app could pass different object
+types to the two calls, or skip the second call and get the deny-everything authority.
+
+**1. Bump the ranges** in `server/package.json` to `@astram/identity` ^0.7.0, `@astram/guard`
+^0.10.0, `@astram/engine` ^0.5.1, `@astram/migrate` ^0.3.2 and `@astram/guide` ^0.2.2, and
+`frontend/package.json` to `@astram/frontend-core` ^0.5.2, then `npm install` in both. Every package now requires `mariadb` ^3.5.4 (driver SQL-injection advisories). No new
+migrations.
+
+**2. Change `server/src/app.module.ts`:**
+
+- Delete `recordAuthorization: buildIdentityRecordAuthorization(...)` from `ShieldModule.forRoot`
+  (and from a `forRootAsync` factory). `buildIdentityRecordAuthorization` no longer exists.
+- Pass your own object types only to `IdentityFeatureModule.forRoot({ extraObjects })`.
+- Delete `createIdentityAuthzPool()` and its import from `@astram/identity/internal` unless another
+  wiring line still uses the pool (for example `new DbScopeSubtreeResolver(authzPool)`).
+
+```ts
+// before
+const authzPool = createIdentityAuthzPool();
+ShieldModule.forRoot({ auth: true, /* … */, recordAuthorization: buildIdentityRecordAuthorization(authzPool, [Note]) }),
+IdentityFeatureModule.forRoot({ rootIds, extraObjects: [Note] }),
+// after
+ShieldModule.forRoot({ auth: true, /* … */ }),
+IdentityFeatureModule.forRoot({ rootIds, extraObjects: [Note] }),
+```
+
+**Boot checks:** `ShieldModule` fails the boot if it receives `recordAuthorization` or
+`decisionAuthority` while `IdentityFeatureModule` is imported (two sources), and
+`IdentityFeatureModule` fails the boot if the request path would use the deny-everything authority
+(for example with an older `@astram/guard`).
+
+**Behaviour changes:** your `extraObjects` types are now also known to cross-tenant grants (offerable
+types, the offer/accept check) and to the guided rule-builder's policy check. The identity module
+opens one pool fewer (the request path uses the identity module's authz pool).
+
+**3. Copy the lint-wall files** from a fresh scaffold: `server/eslint.config.mjs`, the new
+`server/scripts/check-wall.mjs`, and the `lint` and `lint:wall` scripts in `server/package.json`.
+The wall now also rejects any `node_modules/` or `@astram/<pkg>/dist|src` deep import, banned names
+imported under an alias, computed `import()`/`require()` specifiers, and the driver methods
+`execute`, `batch`, `queryStream` and `beginTransaction` (so `CommandBus.execute()` from
+`@nestjs/cqrs` is flagged too). `lint:wall` fails on any `/internal` or `node_modules/@astram`
+import under `src/features`; run it in CI. The wall catches accidental use; deliberate bypass
+(`.call`, `Reflect.apply`, computed method names, an aliased `require`) is a code-review matter.
+
+**More behaviour changes:**
+
+- Change-password answers a wrong current password with 400 `invalid_current_password` (was 401)
+  and a locked account with 429 (was 401). The frontend shows clear messages for 429 and 503.
+- Login, `/auth/mfa`, change-password and the code-gated MFA account routes count each attempt
+  before verifying it (parallel guesses can no longer slip past the limit) and answer 503 when the
+  limiter's Redis call fails (before: login let the attempt through). A refused attempt counts too.
+  An app that overrides a limiter token with its own object must implement `consume` and `refund`.
+- A role delete the engine refuses no longer strips the role's grants. Revoking a grant needs
+  authority over every service account holding the role (403 otherwise).
+- Renaming another user needs authority over that user. A new posting's department and branch must
+  be linked to the membership's company (400 otherwise). A non-root admin cannot change the status
+  of their own root company (403).
+
+**4. Check for agent keys that never expire.** Keys issued before an expiry became mandatory
+(identity < 0.5) have none. `@astram/identity` 0.7 ships a read-only report; run it in `server/`
+with the app's `APP_DB_*` variables set:
+
+```sh
+npx astram-sa-keys-report                  # lists agent label, company, key version, issue date
+npx astram-sa-keys-report --fail-on-found  # exit 1 if any are listed (CI)
+```
+
+Rotate each listed agent's key with an expiry in the service-accounts page. The report never prints
+secrets, hashes or ids.
+
 ## Upgrading from 0.6.x
 
 create-astram-app 0.7 (2026-10-09) pairs with a framework release that moves raw pools off the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/README.md

@@ -70,9 +70,10 @@ boot-pool assertion (ADR-0018), and the Core decision-authority token. With no o
 needs no database or Redis. To turn on login, sessions, MFA and the identity admin
 (`/auth/*`, `/account/*`, `/identity/*`), follow the commented wiring in the header of
 `server/src/app.module.ts`: `ShieldModule.forRoot({ auth: true, emailSender, rootIds,
-identityActionKeys, identityControlPlaneKeys, recordAuthorization })` plus
-`IdentityFeatureModule.forRoot({ rootIds, extraObjects })`. The framework provides the
-credential store, MFA, session handling and the decision authority; you write none of them.
+identityActionKeys, identityControlPlaneKeys })` plus
+`IdentityFeatureModule.forRoot({ rootIds, extraObjects })`, which builds the record
+authorization `ShieldModule` decides with (pass no `recordAuthorization`). The framework provides
+the credential store, MFA, session handling and the decision authority; you write none of them.
 
 ### Before you deploy with auth on
 

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.5.1",
+    "@astram/frontend-core": "^0.5.2",
     "@astram/sdk": "^0.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/server/eslint.config.mjs

@@ -17,19 +17,26 @@
 // which only the composition root (`src/app.module.ts`, `src/main.ts`) may import.
 //
 // THIS lint config is the BACKSTOP: it fails the build if any app file under `src/**`
-// (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`) imports a raw DB symbol or an `/internal`
-// subpath, or calls a raw DB method — also as `x['query']()` or a destructured `{ query }`.
-// The composition root may wire the framework but may not re-export anything (no
+// (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`) imports a raw DB symbol (also under an
+// alias), an `/internal` subpath or a deep path (`node_modules/…`, `@astram/*/dist/…`), or
+// calls a raw DB method (query, execute, batch, queryStream, beginTransaction, …) — also as
+// `x['query']()` or a destructured `{ query }`. `import()`/`require()` must take a static
+// specifier. The composition root may wire the framework but may not re-export anything (no
 // `export … from`, no `export { X as Y }`, no exported variables), and features may not
 // import it. Tests (`*.spec.*`) are exempt from the DB rules but NOT from the `/internal`
-// ban. Keep raw-DB wiring in the composition root; a `src/lib/db.ts` helper is linted like
-// a feature. `scripts/` (dev runner, guide sync) is build tooling that never ships in
-// `dist/` or runs in the request path, so it is not walled.
+// and deep-path bans. Keep raw-DB wiring in the composition root; a `src/lib/db.ts` helper
+// is linted like a feature. `scripts/` (dev runner, guide sync) is build tooling that never
+// ships in `dist/` or runs in the request path, so it is not walled. `npm run lint:wall`
+// (`scripts/check-wall.mjs`, part of `npm run lint`) also greps `src/features/**` for any
+// `/internal` or `node_modules/@astram` specifier, independent of this config.
 //
-// What lint cannot see: a name built at runtime (`ns['MariaDb' + 'UnitOfWork']`). That is
-// moot because the package entry points no longer carry those symbols (the lookup finds
-// `undefined`). Deliberately reaching into framework internals some other way (a deep
-// `node_modules` path via a computed `require`, a private field) is a code-review matter.
+// SCOPE: the wall catches ACCIDENTAL use. Deliberate bypass is a CODE-REVIEW matter, not a
+// lint matter — no static rule can stop code that sets out to evade it. Known, by design
+// not linted: indirect calls (`fn.call(pool, …)`, `.apply`, `.bind`, `Reflect.apply`),
+// method names computed at runtime (`pool[m]()`, `ns['MariaDb' + 'UnitOfWork']` — the
+// latter is moot, the package entry points no longer carry those symbols), an aliased
+// `require` (`const r = require; r(…)`), `module.require`, `createRequire`, private fields.
+// Reviewers: treat any of these in feature code as a wall violation.
 //
 // The old names (`createIdentityAuthzPool`, `MariaDbUnitOfWork`, `SHIELD_DB_POOL`, …) are
 // still banned by NAME below, so an app pinned to an older framework is caught too.
@@ -127,15 +134,69 @@ const INTERNAL_SUBPATHS = {
     'Wall: @astram/*/internal (raw pools, units of work) is for src/app.module.ts and src/main.ts only — features use the RecordEngine (@astram/engine).',
 };
 const INTERNAL_SPECIFIER = '/^@astram\\u002F[^\\u002F]+\\u002Finternal(\\u002F|$)/';
-/** `import('@astram/x/internal')` / `require('@astram/x/internal')` — not seen by no-restricted-imports. */
-const INTERNAL_DYNAMIC = [
+
+/**
+ * Selectors for a module specifier matching `re` in the forms no-restricted-imports does not
+ * see: `import(…)` and `require(…)`, each as a string or a template literal with no
+ * `${…}` (which is just a string). With `statics`, also `import`/`export … from` and TS
+ * `import x = require(…)` (for specifiers checked here instead of by no-restricted-imports).
+ */
+function specifierBan(re, message, { statics = false } = {}) {
+  const sources = statics
+    ? 'ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration, ImportExpression'
+    : 'ImportExpression';
+  return [
+    { selector: `:matches(${sources}) > Literal.source[value=${re}]`, message },
+    {
+      selector: `ImportExpression > TemplateLiteral.source[expressions.length=0] > TemplateElement[value.cooked=${re}]`,
+      message,
+    },
+    { selector: `CallExpression[callee.name='require'] > Literal.arguments[value=${re}]`, message },
+    {
+      selector: `CallExpression[callee.name='require'] > TemplateLiteral.arguments[expressions.length=0] > TemplateElement[value.cooked=${re}]`,
+      message,
+    },
+    ...(statics
+      ? [{ selector: `TSExternalModuleReference > Literal.expression[value=${re}]`, message }]
+      : []),
+  ];
+}
+
+/** `import('@astram/x/internal')` / `require(\`@astram/x/internal\`)` — not seen by no-restricted-imports. */
+const INTERNAL_DYNAMIC = specifierBan(INTERNAL_SPECIFIER, INTERNAL_SUBPATHS.message);
+
+/**
+ * Deep paths into installed packages, in every import form: any `node_modules/` segment
+ * (`../../../node_modules/@astram/identity/dist/internal.js`, `node_modules/mariadb/…`) and
+ * `@astram/<pkg>/dist|src/…`. They skip the package `exports` map, so the `/internal` and
+ * driver bans above would never see them.
+ */
+const DEEP_SPECIFIER =
+  '/(^|\\u002F)node_modules(\\u002F|$)|^@astram\\u002F[^\\u002F]+\\u002F(dist|src)(\\u002F|$)/';
+const DEEP_PATHS = specifierBan(
+  DEEP_SPECIFIER,
+  'Wall: no deep paths into installed packages (node_modules/…, @astram/*/dist|src/…) — import the package entry point; features use the RecordEngine (@astram/engine).',
+  { statics: true },
+);
+
+/**
+ * `import()` / `require()` in walled code take a STATIC specifier (a string, or a template
+ * literal without `${…}`): a specifier computed at runtime (`import(\`@astram/${p}/internal\`)`,
+ * `require(spec)`) cannot be checked by any rule above, so it is rejected outright. App code
+ * has no need for computed module names; a plugin loader belongs in the composition root.
+ */
+const NON_STATIC_SPECIFIER_MESSAGE =
+  'Wall: import()/require() in app code take a static specifier (a string literal) so the wall can check it — load computed modules from the composition root.';
+const NON_STATIC_SPECIFIERS = [
   {
-    selector: `ImportExpression[source.value=${INTERNAL_SPECIFIER}]`,
-    message: INTERNAL_SUBPATHS.message,
+    selector:
+      "ImportExpression:not([source.type='Literal']):not([source.type='TemplateLiteral'][source.expressions.length=0])",
+    message: NON_STATIC_SPECIFIER_MESSAGE,
   },
   {
-    selector: `CallExpression[callee.name='require'][arguments.0.value=${INTERNAL_SPECIFIER}]`,
-    message: INTERNAL_SUBPATHS.message,
+    selector:
+      "CallExpression[callee.name='require']:not([arguments.0.type='Literal']):not([arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0])",
+    message: NON_STATIC_SPECIFIER_MESSAGE,
   },
 ];
 
@@ -147,10 +208,21 @@ const COMPOSITION_ROOT_IMPORTS = {
 };
 
 /** Raw driver methods: banned as calls, also reached by a computed key or destructuring. */
-const RAW_METHODS = ['query', 'getConnection', 'createPool', 'createQueryRunner', 'getRepository'];
+/** (Calls to the first five also have their own messages below; the rest use RAW_METHOD_MESSAGE.) */
+const RAW_METHODS = [
+  'query',
+  'getConnection',
+  'createPool',
+  'createQueryRunner',
+  'getRepository',
+  'execute',
+  'batch',
+  'queryStream',
+  'beginTransaction',
+];
 const RAW_METHOD_RE = `/^(${RAW_METHODS.join('|')})$/`;
-const RAW_METHOD_MESSAGE =
-  'Wall: no raw driver method (query/getConnection/createPool/createQueryRunner/getRepository) in app code, however it is reached — use the RecordEngine (@astram/engine).';
+const MORE_RAW_METHOD_RE = `/^(${RAW_METHODS.slice(5).join('|')})$/`;
+const RAW_METHOD_MESSAGE = `Wall: no raw driver method (${RAW_METHODS.join('/')}) in app code, however it is reached — use the RecordEngine (@astram/engine).`;
 
 /** App source files: TypeScript and plain JavaScript in every module flavour. */
 const SRC_FILES = ['src/**/*.{ts,mts,cts,js,mjs,cjs}'];
@@ -177,9 +249,10 @@ export default tseslint.config(
             INTERNAL_SUBPATHS,
             COMPOSITION_ROOT_IMPORTS,
             {
-              group: ['**/adapters/mariadb-*', '@astram/*/dist/**', '@astram/*/src/**'],
+              // (Deep `@astram/*/dist|src` and `node_modules/` paths: DEEP_PATHS, every import form.)
+              group: ['**/adapters/mariadb-*'],
               message:
-                'Wall: framework internals (pool/uow/audit adapters, deep dist/src paths) are off-limits — features use the RecordEngine facade only.',
+                'Wall: framework internals (pool/uow/audit adapters) are off-limits — features use the RecordEngine facade only.',
             },
           ],
         },
@@ -209,6 +282,10 @@ export default tseslint.config(
           message:
             'Wall: no raw .getConnection() in app code — use the RecordEngine (@astram/engine).',
         },
+        {
+          selector: `CallExpression > MemberExpression.callee[computed=false][property.name=${MORE_RAW_METHOD_RE}]`,
+          message: RAW_METHOD_MESSAGE,
+        },
         // The same methods by COMPUTED key: `pool['query']()`, pool[`getConnection`]().
         {
           selector: `CallExpression > MemberExpression.callee[computed=true][property.value=${RAW_METHOD_RE}]`,
@@ -231,22 +308,28 @@ export default tseslint.config(
           selector: `ObjectPattern > Property[computed=true] > TemplateLiteral.key[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
           message: RAW_METHOD_MESSAGE,
         },
-        {
-          selector: `ImportExpression[source.value=${DRIVER_SPECIFIER}]`,
-          message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
-        },
-        {
-          selector: `CallExpression[callee.name='require'][arguments.0.value=${DRIVER_SPECIFIER}]`,
-          message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
-        },
+        ...specifierBan(
+          DRIVER_SPECIFIER,
+          'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
+        ),
         ...INTERNAL_DYNAMIC,
+        ...DEEP_PATHS,
+        ...NON_STATIC_SPECIFIERS,
         // The banned framework names however they are reached: `ns.SHIELD_DB_POOL`,
         // `require('@astram/guard').SHIELD_DB_POOL`, `(await import('@astram/engine')).TableRegistry`.
-        // (A named import is already reported by no-restricted-imports, so it is skipped here.)
-        ...FORBIDDEN_FRAMEWORK_NAMES.map((name) => ({
-          selector: `Identifier[name='${name}']:not(ImportSpecifier > Identifier)`,
-          message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
-        })),
+        // (A named import from the listed package is already reported by no-restricted-imports,
+        // so plain import specifiers are skipped here; an ALIASED one is reported below, from
+        // any module, because the alias hides the name from every later use.)
+        ...FORBIDDEN_FRAMEWORK_NAMES.flatMap((name) => [
+          {
+            selector: `Identifier[name='${name}']:not(ImportSpecifier > Identifier)`,
+            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+          },
+          {
+            selector: `ImportSpecifier[imported.name='${name}'][local.name!='${name}']`,
+            message: `Wall: ${name} is framework-internal DB access (imported under an alias) — use the RecordEngine (@astram/engine).`,
+          },
+        ]),
         // …and reached by STRING: `ns['SHIELD_DB_POOL']`, ns[`TableRegistry`],
         // `const { ['MariaDbUnitOfWork']: x } = ns`. (Import sources are other strings, so the
         // module specifiers themselves never match.)
@@ -263,13 +346,13 @@ export default tseslint.config(
       ],
     },
   },
-  // ── Tests: exempt from the DB wall, but not from the /internal ban ──────────
+  // ── Tests: exempt from the DB wall, but not from the /internal and deep-path bans ──
   // (A spec that re-exported an internal pool factory would launder it to feature code.)
   {
     files: ['src/**/*.{spec,test}.{ts,mts,cts,js,mjs,cjs}', 'test/**/*.{ts,mts,cts,js,mjs,cjs}'],
     rules: {
       'no-restricted-imports': ['error', { patterns: [INTERNAL_SUBPATHS] }],
-      'no-restricted-syntax': ['error', ...INTERNAL_DYNAMIC],
+      'no-restricted-syntax': ['error', ...INTERNAL_DYNAMIC, ...DEEP_PATHS],
     },
   },
   // ── The composition root: may wire raw pools, may not hand them out ────────

package/template/server/package.json

@@ -14,17 +14,18 @@
     "migration:run": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate",
     "migration:status": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:status",
     "migration:revert": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:revert",
-    "lint": "eslint \"src/**/*.{ts,mts,cts,js,mjs,cjs}\" \"test/**/*.ts\"",
+    "lint": "node scripts/check-wall.mjs && eslint \"src/**/*.{ts,mts,cts,js,mjs,cjs}\" \"test/**/*.ts\"",
+    "lint:wall": "node scripts/check-wall.mjs",
     "guide:sync": "node scripts/sync-astram-guide.mjs",
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
     "@astram/core": "^1.4.0",
-    "@astram/engine": "^0.5.0",
-    "@astram/guard": "^0.9.0",
-    "@astram/guide": "^0.2.1",
-    "@astram/identity": "^0.6.0",
-    "@astram/migrate": "^0.3.1",
+    "@astram/engine": "^0.5.1",
+    "@astram/guard": "^0.10.0",
+    "@astram/guide": "^0.2.2",
+    "@astram/identity": "^0.7.0",
+    "@astram/migrate": "^0.3.2",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

package/template/server/scripts/check-wall.mjs

@@ -0,0 +1,66 @@
+/**
+ * Feature-wall grep — `npm run lint:wall` (also the first step of `npm run lint`).
+ *
+ * Fails when any file under `src/features/**` names a framework-internal module:
+ * an `@astram/<pkg>/internal` subpath, or any path through `node_modules/@astram`
+ * (e.g. `../../../node_modules/@astram/identity/dist/internal.js`). Those carry the raw
+ * pools and units of work that only the composition root (`src/app.module.ts`,
+ * `src/main.ts`) may wire; features use the RecordEngine (@astram/engine).
+ *
+ * This is a plain text scan, independent of the ESLint config, so a weakened or
+ * mis-scoped eslint.config.mjs still cannot let such an import through. It reads every
+ * quoted string after `from`, `import`, `require` or `import(` (comments included —
+ * a false positive there is cheap to reword). No dependencies; runs on macOS and Linux.
+ *
+ * Usage: node scripts/check-wall.mjs [appRoot ...]   (default: the current directory).
+ * An app root without `src/features` is skipped. Exit 1 on any hit.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const EXTENSIONS = /\.(ts|mts|cts|tsx|js|mjs|cjs|jsx)$/;
+/** A module specifier: the quoted string after `from` / `import` / `require(` / `import(`. */
+const SPECIFIER = /\b(?:from|import|require)\s*\(?\s*(['"`])([^'"`\n]+)\1/g;
+/** What a feature may never name. */
+const FORBIDDEN = /^@astram\/[^/]+\/internal(\/|\.|$)|node_modules\/@astram(\/|$)/;
+
+function walk(dir, out) {
+  for (const name of readdirSync(dir)) {
+    if (name === 'node_modules') continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else if (EXTENSIONS.test(name)) out.push(full);
+  }
+  return out;
+}
+
+const roots = process.argv.length > 2 ? process.argv.slice(2) : ['.'];
+const hits = [];
+for (const root of roots) {
+  const features = resolve(root, 'src', 'features');
+  if (!existsSync(features)) {
+    console.log(`lint:wall: ${relative(process.cwd(), features) || features} absent, skipped`);
+    continue;
+  }
+  for (const file of walk(features, [])) {
+    const text = readFileSync(file, 'utf8');
+    for (const m of text.matchAll(SPECIFIER)) {
+      const spec = m[2].replace(/\\/g, '/');
+      if (FORBIDDEN.test(spec)) {
+        const line = text.slice(0, m.index).split('\n').length;
+        hits.push(`${relative(process.cwd(), file)}:${line}  ${spec}`);
+      }
+    }
+  }
+}
+
+if (hits.length > 0) {
+  console.error(
+    'lint:wall: features may not import @astram/*/internal or node_modules/@astram paths — ' +
+      'those are for src/app.module.ts and src/main.ts only; use the RecordEngine (@astram/engine).',
+  );
+  for (const h of hits) console.error(`  ${h}`);
+  process.exit(1);
+}
+console.log('lint:wall: no /internal or node_modules/@astram imports under src/features');

package/template/server/src/app.module.ts

@@ -49,41 +49,35 @@ import { DemoController } from './health/demo.controller';
  * ONE module. `@astram/guard` never imports `@astram/identity` (the dependency graph is
  * identity → guard), so the consumer wires it (ADR-0026):
  *   1. Turn auth on (above), pass the identity permission keys (so the frontend admin
- *      nav lights up), AND pass `recordAuthorization` (so the decision guard actually
- *      GRANTS — without it, decide() denies every classified route):
- *        import { identityAuthActionKeys, identityControlPlaneKeys, IdentityFeatureModule,
- *                 buildIdentityRecordAuthorization } from '@astram/identity';
- *        import { createIdentityAuthzPool } from '@astram/identity/internal';
- *        const authzPool = createIdentityAuthzPool();   // keep it in this file: never export it
- *   (`@astram/identity/internal` holds the raw-pool factory; the lint wall lets only this file
- *   and `main.ts` import it, and forbids re-exporting anything from them.)
+ *      nav lights up), and import the identity module:
+ *        import { identityAuthActionKeys, identityControlPlaneKeys,
+ *                 IdentityFeatureModule } from '@astram/identity';
  *        imports: [
  *          ShieldModule.forRoot({ auth: true,
- *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys,
- *            recordAuthorization: buildIdentityRecordAuthorization(authzPool) }),
+ *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys }),
  *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles,…}
  *        ],
  *   `IdentityFeatureModule.forRoot()` self-wires the engine from your `APP_DB_*` env
- *   (no separate engine setup). Every route is `@Classified` — enforced by the same
- *   deny-by-default guard; `recordAuthorization` makes that guard render REAL decisions
- *   from your roles' grants. Omit the module and login still works; the admin pages 404.
+ *   (no separate engine setup) and builds the record authorization `ShieldModule` decides
+ *   with, so the guard renders REAL decisions from your roles' grants. Do NOT also pass
+ *   `recordAuthorization` or `decisionAuthority` to `ShieldModule`: boot fails (one source).
+ *   Every route is `@Classified` — enforced by the same deny-by-default guard. Omit the
+ *   module and login still works; the admin pages 404.
  *
- *   ⛔ IF YOU REGISTER YOUR OWN OWNED OBJECT TYPES (e.g. a `Note`): pass them BOTH to
- *   `buildIdentityRecordAuthorization(authzPool, [Note])` (so their action keys project
- *   into gate-5 grants) AND to `IdentityFeatureModule.forRoot({ extraObjects: [Note] })`
- *   (so the GUIDED RULE-BUILDER schema + the OWNER-SHARE resolver know them — else a
- *   record of your type is NOT policy-authorable and NOT shareable: "type '…' is not
- *   registered — cannot share"). The frontend ships the matching pages/widget
- *   (RecordPoliciesPage, ShareDialog) already wired to `useAuth().recordPolicy` /
- *   `.recordShare`.
+ *   ⛔ IF YOU REGISTER YOUR OWN OWNED OBJECT TYPES (e.g. a `Note`): pass them to
+ *   `IdentityFeatureModule.forRoot({ extraObjects: [Note] })` (the ONE place: their action
+ *   keys then project into gate-5 grants, and the GUIDED RULE-BUILDER schema, the
+ *   OWNER-SHARE resolver and cross-tenant grants know them — else a record of your type is
+ *   denied, NOT policy-authorable and NOT shareable: "type '…' is not registered — cannot
+ *   share"). The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
+ *   already wired to `useAuth().recordPolicy` / `.recordShare`.
  */
 @Module({
   // Enforcement-only by default (boots with no config). For real login + the identity
   // admin console (incl. the guided rule-builder + owner shares), use (see the OPTIONAL
   // blocks above for the full form + the extraObjects note for your OWN owned types):
   //   imports: [
-  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys,
-  //       recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]) }),
+  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys }),
   //     IdentityFeatureModule.forRoot({ /* extraObjects: [YourType] */ }),
   //   ],
   imports: [ShieldModule.forRoot()],