create-astram-app 0.6.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
 
 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.
@@ -132,6 +139,36 @@ With `auth: true`, check every item before the first production deploy.
   requests fail closed (401) and refresh answers 503, within `REDIS_COMMAND_TIMEOUT_MS` (default
   2000). The app's Redis user must be allowed `EVAL` (the shipped `infra/redis` ACL allows it;
   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: [{ 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
   `IdentityFeatureModule.forRoot`, from config. Without them nobody logs in as root and the
   identity module logs a boot warning. The generated `app.module.ts` does not pass them yet; add
@@ -156,6 +193,116 @@ 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 entry points (breaking: `@astram/engine` 0.5, `@astram/identity` 0.6, `@astram/guard` 0.9)
+and ships the follow-up security fixes (see each package's CHANGELOG).
+
+**1. Bump the ranges** in `server/package.json` to `@astram/engine` ^0.5.0,
+`@astram/identity` ^0.6.0, `@astram/guard` ^0.9.0, `@astram/migrate` ^0.3.1, `@astram/guide` ^0.2.1,
+and `frontend/package.json` to `@astram/frontend-core` ^0.5.1, then `npm install` in both. No new
+migrations.
+
+**2. Change these files** (or copy them from a fresh scaffold and merge by hand):
+
+| File | Change |
+|---|---|
+| `server/src/app.module.ts` | `import { createIdentityAuthzPool } from '@astram/identity/internal'` (it is no longer exported from `@astram/identity`). Keep the pool inside this file: do not export it. |
+| `server/eslint.config.mjs`, `lint` script in `server/package.json` | the wall also lints `.js`/`.mjs`/`.cjs` under `src/`, rejects `@astram/*/internal` outside `app.module.ts`/`main.ts` (specs included), `x['query']()` and destructured `{ query }`, re-exports from `app.module.ts`/`main.ts`, and features importing either file |
+
+**Breaking changes:** `MariaDbUnitOfWork` moved from `@astram/engine` to `@astram/engine/internal`;
+`createIdentityAuthzPool` from `@astram/identity` to `@astram/identity/internal`;
+`PersistenceModule` and `SHIELD_DB_POOL` from `@astram/guard` to `@astram/guard/internal`. Only the
+composition root (`app.module.ts`, `main.ts`) and tests that compose the framework should import
+them. The wider lint wall may flag existing code that destructures `query` (for example
+`const { query } = req`); read request query parameters with `@Query()` instead.
+
+**Behaviour changes:** deleting a role or a company now needs authority over everyone who holds
+it (403 otherwise). Deleting a role removes its grants and takes it off service accounts.
+Deleting a company disables its service accounts, revokes their keys and ends cross-tenant grants
+naming it. An API key whose company no longer exists is rejected. Removing an MFA device,
+regenerating recovery codes and changing the password are rate-limited per account; change-password
+shares the login lockout. Admin role assignment treats permission keys the server does not know as
+not held, and `IdentityFeatureModule.forRoot` and `buildIdentityRecordAuthorization` must receive
+the same `extraObjects` (boot fails otherwise). The frontend refresh call times out after 15 s
+(treated as an outage, the user stays signed in).
+
 ## Upgrading from 0.5.x
 
 The generated app owns its files, and the scaffolder never overwrites them, so an upgrade has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.6.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.0",
+    "@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/frontend/src/auth/AuthContext.jsx

@@ -77,12 +77,14 @@ export function AuthProvider({ children }) {
     // cross-tab `navigator.locks` section that re-reads localStorage first so two tabs
     // never spend the same refresh token), then retries the request once. A rejected
     // refresh clears the session (→ login); a 503 keeps it (the server did not spend the
-    // token; the next request retries). The refresh call itself uses the RAW client.
+    // token; the next request retries). The refresh call itself uses the RAW client, and
+    // forwards the wrapper's abort signal so a hung refresh times out (an outage, not a
+    // logout) instead of holding the cross-tab lock.
     const refresher = createAuthService(rawHttp);
     const http = createRefreshingHttp({
       http: rawHttp,
       store,
-      refresh: (refreshToken) => refresher.refresh(refreshToken),
+      refresh: (refreshToken, opts) => refresher.refresh(refreshToken, opts),
       onRefreshed: (next) => sessionEventsRef.current.refreshed(next),
       onSessionExpired: () => sessionEventsRef.current.expired(),
     });

package/template/frontend/src/platform/httpClient.js

@@ -22,6 +22,14 @@ async function toResponse(res) {
   return { ok: res.ok, status: res.status, data };
 }
 
+/**
+ * Forward the caller's abort signal to fetch (a stale search, or the refresh timeout in
+ * `createRefreshingHttp`). An abort rejects fetch, which every method maps to status 0.
+ */
+function withSignal(opts) {
+  return opts && opts.signal ? { signal: opts.signal } : {};
+}
+
 /**
  * The app-wide enforced-re-enroll interceptor. When a request is rejected with a 403
  * whose body is EXACTLY `{ error: 'reenrollment_required' }` (the server's re-enroll
@@ -65,6 +73,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -80,6 +89,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -95,6 +105,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -110,6 +121,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -120,6 +132,7 @@ export function createWebHttpClient(config = {}) {
       try {
         const res = await fetch(`${BASE}${path}`, {
           headers: opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {},
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {

package/template/frontend/src/platform/httpClient.test.mjs

@@ -0,0 +1,60 @@
+// httpClient.test.mjs — the web HttpClient forwards `opts.signal` to fetch on every
+// method (Phase 8 #6), so the refresh timeout in @astram/frontend-core can abort a hung
+// /auth/refresh, and an aborted request maps to the transport-failure shape.
+//
+//   node --test src/platform/httpClient.test.mjs
+//
+// `fetch` is stubbed on globalThis, so this runs under plain Node.
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWebHttpClient } from './httpClient.js';
+
+let realFetch;
+let seen;
+
+beforeEach(() => {
+  realFetch = globalThis.fetch;
+  seen = [];
+  globalThis.fetch = async (url, init = {}) => {
+    seen.push({ url, init });
+    if (init.signal?.aborted) {
+      throw Object.assign(new Error('aborted'), { name: 'AbortError' });
+    }
+    return { ok: true, status: 200, json: async () => ({ ok: true }) };
+  };
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('createWebHttpClient — abort signal forwarding', () => {
+  const methods = [
+    ['get', (c, o) => c.get('/x', o)],
+    ['post', (c, o) => c.post('/x', {}, o)],
+    ['patch', (c, o) => c.patch('/x', {}, o)],
+    ['put', (c, o) => c.put('/x', {}, o)],
+    ['delete', (c, o) => c.delete('/x', {}, o)],
+  ];
+
+  for (const [name, call] of methods) {
+    test(`${name} passes opts.signal to fetch`, async () => {
+      const ctl = new AbortController();
+      const r = await call(createWebHttpClient(), { signal: ctl.signal });
+      assert.equal(r.status, 200);
+      assert.equal(seen[0].init.signal, ctl.signal);
+    });
+
+    test(`${name} with an aborted signal resolves { ok: false, status: 0 } (never throws)`, async () => {
+      const ctl = new AbortController();
+      ctl.abort();
+      const r = await call(createWebHttpClient(), { signal: ctl.signal });
+      assert.deepEqual(r, { ok: false, status: 0, data: null });
+    });
+
+    test(`${name} without a signal sends no signal`, async () => {
+      await call(createWebHttpClient(), undefined);
+      assert.equal('signal' in seen[0].init, false);
+    });
+  }
+});

package/template/server/eslint.config.mjs

@@ -11,18 +11,35 @@
 // entirely (this is exactly how astram-org's ORS got bypassed 165 times).
 //
 // The PRIMARY wall is structural: the framework never hands feature scope a pool
-// (EngineModule seals it). THIS lint rule is the BACKSTOP: it fails the build if any
-// app file under `src/**` imports a raw DB symbol or calls a raw DB method, so an
-// off-road attempt is a red build, not a silent success. Only the composition root
-// (`src/app.module.ts`, `src/main.ts`) and tests (`*.spec.ts`) are exempt: they wire the
-// framework (e.g. `createIdentityAuthzPool()` for ShieldModule.forRoot) and never hold
-// feature logic. Keep raw-DB wiring there; 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.
+// (EngineModule seals it), and the package entry points (`@astram/engine`,
+// `@astram/identity`, `@astram/guard`) export no raw pool or unit of work. Those live only
+// on `@astram/*/internal` subpaths (`createIdentityAuthzPool`, `MariaDbUnitOfWork`, …),
+// which only the composition root (`src/app.module.ts`, `src/main.ts`) may import.
 //
-// Some framework packages also export their internal adapters for composition and tests
-// (`createIdentityAuthzPool`, `MariaDbUnitOfWork`, …). Those are banned by NAME below, so an
-// import from the package root is caught, not only a deep `dist/` path.
+// 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 (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`
+// 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.
+//
+// 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.
 //
 // If you hit this rule because the pipe can't do what you need: STOP. Do NOT work
 // around it. Record the gap in `.astram/guide/gaps.md` and raise it with the
@@ -86,7 +103,7 @@ const FORBIDDEN_DB_SUBPATHS = {
 const FORBIDDEN_DB_NAMED_FROM = [
   {
     name: '@astram/guard',
-    importNames: ['SHIELD_DB_POOL'],
+    importNames: ['SHIELD_DB_POOL', 'PersistenceModule'],
     message:
       'Wall: the DB pool is sealed inside the engine — features use the RecordEngine (@astram/engine).',
   },
@@ -110,6 +127,108 @@ const FORBIDDEN_FRAMEWORK_NAMES = FORBIDDEN_DB_NAMED_FROM.flatMap((e) => e.impor
 /** Driver specifiers for dynamic `import()` / `require()` (static imports use the lists above). */
 const DRIVER_SPECIFIER = '/^(mariadb|mysql2?|pg|typeorm|knex|@nestjs.typeorm)(\\W|$)/';
 
+/** The framework's composition-only subpaths (`@astram/engine/internal`, …). */
+const INTERNAL_SUBPATHS = {
+  group: ['@astram/*/internal', '@astram/*/internal/**'],
+  message:
+    '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|$)/';
+
+/**
+ * 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:not([source.type='Literal']):not([source.type='TemplateLiteral'][source.expressions.length=0])",
+    message: NON_STATIC_SPECIFIER_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,
+  },
+];
+
+/** The composition root, where the framework (and its pools) are wired. Features never import it. */
+const COMPOSITION_ROOT_IMPORTS = {
+  group: ['**/app.module', '**/app.module.*', '**/main', '**/main.*'],
+  message:
+    'Wall: features never import the composition root (app.module/main) — it wires raw framework pools. Use the RecordEngine (@astram/engine).',
+};
+
+/** Raw driver methods: banned as calls, also reached by a computed key or destructuring. */
+/** (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 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}'];
+const COMPOSITION_ROOT = ['src/app.module.ts', 'src/main.ts'];
+const SPECS = ['**/*.spec.*', '**/*.test.*'];
+
 export default tseslint.config(
   js.configs.recommended,
   ...tseslint.configs.recommended,
@@ -118,8 +237,8 @@ export default tseslint.config(
   },
   // ── The wall: all app code except the composition root and tests ──────────
   {
-    files: ['src/**/*.{ts,mts,cts}'],
-    ignores: ['src/app.module.ts', 'src/main.ts', '**/*.spec.ts'],
+    files: SRC_FILES,
+    ignores: [...COMPOSITION_ROOT, ...SPECS],
     rules: {
       'no-restricted-imports': [
         'error',
@@ -127,10 +246,13 @@ export default tseslint.config(
           paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
           patterns: [
             FORBIDDEN_DB_SUBPATHS,
+            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.',
             },
           ],
         },
@@ -161,20 +283,53 @@ export default tseslint.config(
             'Wall: no raw .getConnection() in app code — use the RecordEngine (@astram/engine).',
         },
         {
-          selector: `ImportExpression[source.value=${DRIVER_SPECIFIER}]`,
-          message: 'Wall: features never load a DB driver — 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}]`,
+          message: RAW_METHOD_MESSAGE,
+        },
+        {
+          selector: `CallExpression > MemberExpression.callee[computed=true] > TemplateLiteral.property[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
+          message: RAW_METHOD_MESSAGE,
+        },
+        // …and DESTRUCTURED off anything: `const { query } = pool`, `{ ['query']: q } = pool`.
+        {
+          selector: `ObjectPattern > Property[computed=false][key.name=${RAW_METHOD_RE}]`,
+          message: RAW_METHOD_MESSAGE,
         },
         {
-          selector: `CallExpression[callee.name='require'][arguments.0.value=${DRIVER_SPECIFIER}]`,
-          message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
+          selector: `ObjectPattern > Property[computed=true][key.value=${RAW_METHOD_RE}]`,
+          message: RAW_METHOD_MESSAGE,
         },
+        {
+          selector: `ObjectPattern > Property[computed=true] > TemplateLiteral.key[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
+          message: RAW_METHOD_MESSAGE,
+        },
+        ...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.)
@@ -191,4 +346,52 @@ export default tseslint.config(
       ],
     },
   },
+  // ── 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, ...DEEP_PATHS],
+    },
+  },
+  // ── The composition root: may wire raw pools, may not hand them out ────────
+  // No re-exports (`export … from`, `export *`, `export { X as Y }`), no exported variables
+  // and no `export default <expression>`: only declared classes/functions/types. Features may
+  // not import these files either (see COMPOSITION_ROOT_IMPORTS above).
+  {
+    files: COMPOSITION_ROOT,
+    rules: {
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'ExportAllDeclaration',
+          message: 'Wall: the composition root re-exports nothing (no `export * from`).',
+        },
+        {
+          selector: 'ExportNamedDeclaration[source]',
+          message: 'Wall: the composition root re-exports nothing (no `export { … } from`).',
+        },
+        {
+          selector: 'ExportSpecifier',
+          message:
+            'Wall: the composition root re-exports nothing (no `export { X }` / `export { X as Y }`).',
+        },
+        {
+          selector: 'ExportNamedDeclaration > VariableDeclaration',
+          message:
+            'Wall: the composition root exports no variables (a wired pool must stay inside it).',
+        },
+        {
+          selector:
+            'ExportDefaultDeclaration:not([declaration.type=/^(ClassDeclaration|FunctionDeclaration)$/])',
+          message: 'Wall: the composition root default-exports only a class or function.',
+        },
+        {
+          selector: 'TSExportAssignment',
+          message: 'Wall: the composition root re-exports nothing (no `export =`).',
+        },
+      ],
+    },
+  },
 );

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}\" \"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.4.0",
-    "@astram/guard": "^0.8.0",
-    "@astram/guide": "^0.2.0",
-    "@astram/identity": "^0.5.0",
-    "@astram/migrate": "^0.3.0",
+    "@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,38 +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,
- *                 createIdentityAuthzPool, buildIdentityRecordAuthorization } from '@astram/identity';
- *        const authzPool = createIdentityAuthzPool();
+ *      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()],