create-astram-app 0.5.0 → 0.7.0

package/template/server/eslint.config.mjs

@@ -0,0 +1,314 @@
+// ESLint flat config for an Astram consumer app.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE PHYSICAL WALL — backstop (do not remove).
+//
+// The Astram paved road is the ONE way features touch data: inject the framework's
+// RecordEngine (from @astram/engine) and go through the pipe (permission gate +
+// audit are mandatory, cross-tenant isolation is enforced). A feature must NEVER
+// reach the database directly — a raw mariadb/typeorm pool, a DataSource, a
+// QueryRunner, or a repository `.save()`/`.query()` skips the security layer
+// 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), 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.
+//
+// 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
+// framework — the capability must be added to @astram/engine (the gap-flag loop).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+/** Raw DB packages a feature must never import directly. */
+const FORBIDDEN_DB_IMPORTS = [
+  {
+    name: 'mariadb',
+    message: 'Wall: features never open a DB pool — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'mysql',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'mysql2',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  { name: 'typeorm', message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).' },
+  {
+    name: '@nestjs/typeorm',
+    message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'pg',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'knex',
+    message: 'Wall: no query builder in features — use the RecordEngine (@astram/engine).',
+  },
+];
+
+/** Driver/ORM SUBPATHS (`paths` above matches exact specifiers only). */
+const FORBIDDEN_DB_SUBPATHS = {
+  group: [
+    'mariadb/*',
+    'mysql/*',
+    'mysql2/*',
+    'typeorm/*',
+    '@nestjs/typeorm/*',
+    'pg/*',
+    'pg-*',
+    'knex/*',
+  ],
+  message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+};
+
+/**
+ * Named imports that hand a feature raw DB access even from an ALLOWED package.
+ * `SHIELD_DB_POOL` is exported from `@astram/guard` (a package a feature legitimately
+ * imports for other reasons), so it must be blocked by NAME on that path — the engine
+ * owns the pool; feature scope must never import the pool token. The same goes for the
+ * composition-only factories/adapters of `@astram/identity` and `@astram/engine`.
+ */
+const FORBIDDEN_DB_NAMED_FROM = [
+  {
+    name: '@astram/guard',
+    importNames: ['SHIELD_DB_POOL', 'PersistenceModule'],
+    message:
+      'Wall: the DB pool is sealed inside the engine — features use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: '@astram/identity',
+    importNames: ['createIdentityAuthzPool'],
+    message:
+      'Wall: createIdentityAuthzPool is a raw pool for app.module.ts wiring only — features use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: '@astram/engine',
+    importNames: ['MariaDbUnitOfWork', 'MariaDbAuditSink', 'RecordEngineImpl', 'TableRegistry'],
+    message:
+      'Wall: engine internals (unit of work, audit sink, impl, registry) bypass the gate and audit — inject RECORD_ENGINE / RecordsService instead.',
+  },
+];
+
+/** Every name above, for the syntax ban that also catches `ns.X`, `require(…).X`, `(await import(…)).X`. */
+const FORBIDDEN_FRAMEWORK_NAMES = FORBIDDEN_DB_NAMED_FROM.flatMap((e) => e.importNames);
+
+/** 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,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+  // ── The wall: all app code except the composition root and tests ──────────
+  {
+    files: SRC_FILES,
+    ignores: [...COMPOSITION_ROOT, ...SPECS],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          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:
+                'Wall: framework internals (pool/uow/audit adapters, deep dist/src paths) are off-limits — features use the RecordEngine facade only.',
+            },
+          ],
+        },
+      ],
+      // Block raw query-runner / repository calls even if a pool were obtained.
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: "CallExpression[callee.property.name='createQueryRunner']",
+          message: 'Wall: no QueryRunner in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='getRepository']",
+          message:
+            'Wall: no repository access in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='createPool']",
+          message: 'Wall: features never create a DB pool — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='query']",
+          message: 'Wall: no raw .query() in app code — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='getConnection']",
+          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).',
+        },
+        {
+          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.)
+        ...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).`,
+        })),
+        // …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.)
+        ...FORBIDDEN_FRAMEWORK_NAMES.flatMap((name) => [
+          {
+            selector: `Literal[value='${name}']`,
+            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+          },
+          {
+            selector: `TemplateLiteral[expressions.length=0] > TemplateElement[value.cooked='${name}']`,
+            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+          },
+        ]),
+      ],
+    },
+  },
+  // ── 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,27 +14,27 @@
     "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\" \"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.3.0",
-    "@astram/engine": "^0.3.0",
-    "@astram/guard": "^0.7.0",
-    "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.4.0",
-    "@astram/migrate": "^0.2.0",
+    "@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/sdk": "^0.2.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/common": "^11.2.7",
+    "@nestjs/core": "^11.2.7",
+    "@nestjs/platform-express": "^11.2.7",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/testing": "^11.2.7",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "@types/supertest": "^6.0.2",

package/template/server/scripts/dev.mjs

@@ -10,6 +10,12 @@
  * hot-reload AND correct DI. Same compiler as the production build, no extra deps.
  *
  * `.env` is loaded by the node child via --env-file-if-exists.
+ *
+ * NODE_ENV: the child runs with NODE_ENV=development unless your shell already set it.
+ * `npm run dev` is a dev box by definition, and @astram/guard keys dev-only defaults
+ * off the RAW NODE_ENV (e.g. with `auth: true` and no `emailSender`, the dev email
+ * logger that prints reset links is used ONLY under development/test; an unset
+ * NODE_ENV fails boot). `npm start` does NOT set it — production must configure a sender.
  */
 
 import { spawn } from 'node:child_process';
@@ -20,7 +26,13 @@ mkdirSync('dist', { recursive: true });
 // 1) tsc in watch mode → dist/ (emits decorator metadata; the whole point).
 const tsc = spawn(
   process.execPath,
-  [new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname, '-w', '-p', 'tsconfig.build.json', '--preserveWatchOutput'],
+  [
+    new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname,
+    '-w',
+    '-p',
+    'tsconfig.build.json',
+    '--preserveWatchOutput',
+  ],
   { stdio: 'inherit' },
 );
 
@@ -33,11 +45,10 @@ const startNode = () => {
     return;
   }
   started = true;
-  const node = spawn(
-    process.execPath,
-    ['--env-file-if-exists=.env', '--watch', 'dist/main.js'],
-    { stdio: 'inherit' },
-  );
+  const node = spawn(process.execPath, ['--env-file-if-exists=.env', '--watch', 'dist/main.js'], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'development' },
+  });
   node.on('exit', (code) => {
     tsc.kill();
     process.exit(code ?? 0);

package/template/server/scripts/sync-astram-guide.mjs

@@ -17,9 +17,16 @@
  *
  * The app root is the monorepo root (one level up from server/), because CLAUDE.md +
  * .claude/ live at the app root and Claude walks UP the tree from wherever you work.
+ *
+ * SAFETY (it runs on every install, including in CI and Docker builds):
+ *   - It only writes when that root is recognisably an Astram app (has `CLAUDE.md` or
+ *     `.astram/`). A `server/` copied alone (e.g. `COPY server/ /app` in a Dockerfile, or
+ *     a standalone clone) is skipped, so it never writes to `/` or to `~/.claude/rules/`.
+ *   - `ASTRAM_GUIDE_SYNC=0` skips it (CI, production images).
+ *   - It never fails the install: any error is reported and the exit code stays 0.
  */
 
-import { cpSync, mkdirSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
@@ -29,7 +36,20 @@ const here = dirname(fileURLToPath(import.meta.url)); // server/scripts
 const appRoot = resolve(here, '..', '..'); // monorepo root
 const rulesDir = join(appRoot, '.claude', 'rules');
 
+function log(msg) {
+  process.stdout.write(`[sync-astram-guide] ${msg}\n`);
+}
+
 function main() {
+  if (process.env.ASTRAM_GUIDE_SYNC === '0') {
+    log('ASTRAM_GUIDE_SYNC=0 — skipped.');
+    return 0;
+  }
+  if (!existsSync(join(appRoot, 'CLAUDE.md')) && !existsSync(join(appRoot, '.astram'))) {
+    log(`${appRoot} has no CLAUDE.md or .astram/ — not an Astram app root, skipped.`);
+    return 0;
+  }
+
   let guide;
   try {
     guide = require('@astram/guide');
@@ -40,24 +60,30 @@ function main() {
     return 0;
   }
 
-  mkdirSync(rulesDir, { recursive: true });
-  // Copy the framework docs into .claude/rules/ (overwrite — they are the framework's
-  // to own; on upgrade the newer versions replace the older ones cleanly).
-  cpSync(guide.FRAMEWORK_RULES_PATH, join(rulesDir, 'astram-framework-rules.md'));
-  cpSync(guide.CAPABILITIES_PATH, join(rulesDir, 'astram-framework-capabilities.md'));
-
-  // Stamp the synced version so a human/AI can see which framework version's rules
-  // are present (and notice when an upgrade changed them).
-  writeFileSync(
-    join(rulesDir, '.astram-guide-version'),
-    `${guide.version}\n`,
-    'utf8',
-  );
-
-  process.stdout.write(
-    `[sync-astram-guide] framework rules synced (v${guide.version}) → .claude/rules/\n`,
-  );
+  try {
+    mkdirSync(rulesDir, { recursive: true });
+    // Copy the framework docs into .claude/rules/ (overwrite — they are the framework's
+    // to own; on upgrade the newer versions replace the older ones cleanly).
+    cpSync(guide.FRAMEWORK_RULES_PATH, join(rulesDir, 'astram-framework-rules.md'));
+    cpSync(guide.CAPABILITIES_PATH, join(rulesDir, 'astram-framework-capabilities.md'));
+
+    // Stamp the synced version so a human/AI can see which framework version's rules
+    // are present (and notice when an upgrade changed them).
+    writeFileSync(join(rulesDir, '.astram-guide-version'), `${guide.version}\n`, 'utf8');
+  } catch (err) {
+    // Best-effort: a read-only or odd filesystem must never fail `npm install`.
+    const reason = err && typeof err === 'object' && 'code' in err ? err.code : 'error';
+    log(`could not sync into ${rulesDir} (${reason}) — skipped. Run \`npm run guide:sync\` later.`);
+    return 0;
+  }
+
+  log(`framework rules synced (v${guide.version}) → .claude/rules/`);
   return 0;
 }
 
-process.exitCode = main();
+try {
+  process.exitCode = main();
+} catch {
+  log('unexpected error — skipped.');
+  process.exitCode = 0;
+}

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

@@ -17,12 +17,16 @@ import { DemoController } from './health/demo.controller';
  *   2. Import that module here (add it to `imports`) or list its controller in
  *      `controllers`.
  *   3. Classify every route: `@Public()` for open routes, `@Classified(...)` for
- *      guarded ones. Anything left unclassified is DENIED (403) by design.
+ *      guarded ones. Anything left unclassified is DENIED by design: the global guard
+ *      answers 403, and once `IdentityFeatureModule` is wired the app refuses to BOOT
+ *      (`verifyGatable` aborts on any unclassified route).
  *
- * `HealthController` + `DemoController` below are starter routes that prove the
- * framework enforces from your side (health/@Public → 200, unclassified → 403).
- * Keep the health probes; the demo controller is illustrative — delete it once
- * you've seen enforcement work.
+ * `HealthController` + `DemoController` below are starter routes, all `@Public()`
+ * (`/health`, `/demo/public` → 200). The scaffold ships NO unclassified route (the
+ * demo one is commented out, so `/demo/unclassified` is a 404); `npm test`
+ * (`test/enforcement.e2e.spec.ts`) proves deny-by-default with a test-only
+ * controller. Keep the health probes; the demo controller is illustrative — delete
+ * it once you've seen enforcement work.
  *
  * ── OPTIONAL: real authentication (login/MFA/refresh/logout) ──────────────────
  * The framework ships a complete Auth surface you can turn on WITHOUT writing any
@@ -32,6 +36,8 @@ import { DemoController } from './health/demo.controller';
  *   2. Provide the DB/Redis/HMAC config in `.env` (see the AUTH block in
  *      `.env.example`) — auth needs a real MariaDB + Redis and a refresh HMAC key.
  *   3. Create a user in the `shield_identity.identity_credential` table.
+ *   4. Outside development/test (`NODE_ENV`), `auth: true` also requires an
+ *      `emailSender` (or `emailSender: 'disabled'`) — otherwise boot fails closed.
  * You then get framework-owned `POST /auth/{login,mfa,refresh,logout}` for free —
  * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
  * boot; turning it on requires the config above, by design — fail-closed.)
@@ -46,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,

package/template/server/src/health/demo.controller.ts

@@ -8,14 +8,18 @@ import { Public } from '@astram/guard';
  *   deny-by-default global guard.
  *
  * Deny-by-default has TWO layers, and they differ in WHEN they bite:
- *   1. **Boot-time (fail-closed, strongest):** the identity boot check (`verifyGatable`)
- *      scans every route and ABORTS BOOT if any non-`@Public` route lacks `@Classified`.
- *      A forgotten declaration doesn't just get denied at request time — the app won't
- *      start. That is why the illustrative "unclassified route" below is a COMMENT, not a
- *      live handler: a live one would prevent this app from booting. Uncomment it only to
- *      SEE the boot abort, then re-comment (or classify it).
- *   2. **Request-time (per-request):** even absent the boot check, the global guard denies
- *      an unclassified route with 403.
+ *   1. **Request-time (always on):** the global guard wired by `ShieldModule.forRoot()`
+ *      denies any route that is neither `@Public()` nor `@Classified(...)` with 403,
+ *      before its handler runs.
+ *   2. **Boot-time (once `IdentityFeatureModule` is wired):** the identity boot check
+ *      (`verifyGatable`) scans every route and ABORTS BOOT if any non-`@Public` route
+ *      lacks `@Classified`. A forgotten declaration then means the app won't start.
+ *
+ * The illustrative "unclassified route" below is a COMMENT, so this scaffold ships no
+ * unclassified route and `GET /demo/unclassified` is a 404. Uncomment it to see the
+ * denial: 403 with the default `ShieldModule.forRoot()`, a boot abort once
+ * `IdentityFeatureModule` is imported. Then re-comment it (or classify it).
+ * `test/enforcement.e2e.spec.ts` proves both layers with a test-only controller.
  *
  * This controller is illustrative — delete it once you've seen enforcement work; a real
  * feature classifies every route with `@Public()` or `@Classified(...)`.
@@ -28,10 +32,10 @@ export class DemoController {
     return { message: 'public route reachable — explicit @Public() opt-out' };
   }
 
-  // Intentionally NO @Public() / @Classified(). Kept as a COMMENT because the boot-time
-  // `verifyGatable` (fail-closed) aborts boot on any unclassified route — a live handler
-  // here would stop the app from starting. Uncomment to witness the boot abort, then
-  // re-comment or classify it.
+  // Intentionally NO @Public() / @Classified(). Kept as a COMMENT so the scaffold ships no
+  // unclassified route: live, it is denied 403 by the guard, and with IdentityFeatureModule
+  // wired `verifyGatable` aborts boot. Uncomment to witness the denial, then re-comment or
+  // classify it.
   // @Get('unclassified')
   // unclassifiedRoute(): { message: string } {
   //   return { message: 'this body must never be reached — the guard denies first' };

package/template/server/src/main.ts

@@ -1,5 +1,6 @@
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
+import type { NestExpressApplication } from '@nestjs/platform-express';
 import { loadAppConfig } from '@astram/guard';
 import { AppModule } from './app.module';
 
@@ -14,11 +15,32 @@ import { AppModule } from './app.module';
  */
 export async function bootstrap(): Promise<void> {
   const config = loadAppConfig();
-  const app = await NestFactory.create(AppModule, { bufferLogs: false });
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, { bufferLogs: false });
+  // TRUST_PROXY = the number of reverse-proxy hops in front of this app: 0 = no proxy
+  // (exposed directly), 1 = behind the Astram Traefik. It must be your REAL hop count:
+  // too high and a client can spoof its IP via X-Forwarded-For; too low and every client
+  // shares the proxy's IP. Unset → `trust proxy` stays unset and @astram/guard turns its
+  // per-IP limiters (login, forgot-password, reset-password) OFF, with a boot warning;
+  // the per-account limits stay on.
+  const trustProxy = parseTrustProxy(process.env.TRUST_PROXY);
+  if (trustProxy !== undefined) app.set('trust proxy', trustProxy);
   await app.listen(config.port);
   console.log(`[__APP_NAME__] listening on :${config.port} (${config.environment})`);
 }
 
+/**
+ * Parse TRUST_PROXY: unset/blank → `undefined` (leave Express's default); a non-negative
+ * integer → that hop count; anything else fails boot (a guessed value could let clients
+ * spoof their IP).
+ */
+export function parseTrustProxy(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw.trim() === '') return undefined;
+  if (!/^\d+$/.test(raw.trim())) {
+    throw new Error(`TRUST_PROXY must be a non-negative integer hop count (got "${raw}")`);
+  }
+  return Number(raw.trim());
+}
+
 // Only auto-start when run directly (not when imported by tests).
 if (process.env.NODE_ENV !== 'test') {
   void bootstrap();