create-astram-app 0.6.0 → 0.7.0

package/README.md

@@ -96,7 +96,7 @@ 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
+const authzPool = createIdentityAuthzPool();         // from @astram/identity/internal; never export it
 
 imports: [
   ShieldModule.forRoot({
@@ -132,6 +132,16 @@ 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: ['totp']` for every user with a confirmed MFA
+    device. Return `[]` 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.
+  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 +166,41 @@ 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.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.7.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/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.1",
     "@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,28 @@
 // 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 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
+// `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.
+//
+// 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.
+//
+// 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 +96,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 +120,43 @@ 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|$)/';
+/** `import('@astram/x/internal')` / `require('@astram/x/internal')` — not seen by no-restricted-imports. */
+const INTERNAL_DYNAMIC = [
+  {
+    selector: `ImportExpression[source.value=${INTERNAL_SPECIFIER}]`,
+    message: INTERNAL_SUBPATHS.message,
+  },
+  {
+    selector: `CallExpression[callee.name='require'][arguments.0.value=${INTERNAL_SPECIFIER}]`,
+    message: INTERNAL_SUBPATHS.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. */
+const RAW_METHODS = ['query', 'getConnection', 'createPool', 'createQueryRunner', 'getRepository'];
+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).';
+
+/** 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 +165,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,6 +174,8 @@ 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/**'],
               message:
@@ -160,6 +209,28 @@ export default tseslint.config(
           message:
             'Wall: no raw .getConnection() in app code — use the RecordEngine (@astram/engine).',
         },
+        // 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: `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,
+        },
         {
           selector: `ImportExpression[source.value=${DRIVER_SPECIFIER}]`,
           message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
@@ -168,6 +239,7 @@ export default tseslint.config(
           selector: `CallExpression[callee.name='require'][arguments.0.value=${DRIVER_SPECIFIER}]`,
           message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
         },
+        ...INTERNAL_DYNAMIC,
         // 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.)
@@ -191,4 +263,52 @@ export default tseslint.config(
       ],
     },
   },
+  // ── Tests: exempt from the DB wall, but not from the /internal ban ──────────
+  // (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],
+    },
+  },
+  // ── 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,17 @@
     "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": "eslint \"src/**/*.{ts,mts,cts,js,mjs,cjs}\" \"test/**/*.ts\"",
     "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.0",
+    "@astram/guard": "^0.9.0",
+    "@astram/guide": "^0.2.1",
+    "@astram/identity": "^0.6.0",
+    "@astram/migrate": "^0.3.1",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

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

@@ -52,8 +52,11 @@ import { DemoController } from './health/demo.controller';
  *      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();
+ *                 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.)
  *        imports: [
  *          ShieldModule.forRoot({ auth: true,
  *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys,