create-astram-app 0.4.0 → 0.6.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.)

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();

package/template/server/test/enforcement.e2e.spec.ts

@@ -1,5 +1,13 @@
-import type { INestApplication } from '@nestjs/common';
+import { Controller, Get, type INestApplication, type ModuleMetadata } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
 import { Test } from '@nestjs/testing';
+import { checkCompleteness, createModuleRegistry } from '@astram/core';
+import {
+  CatalogGatabilityError,
+  CatalogReconciler,
+  OperationInventoryScanner,
+  ShieldModule,
+} from '@astram/guard';
 import request from 'supertest';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { AppModule } from '../src/app.module';
@@ -46,11 +54,70 @@ describe('__APP_NAME__ — framework enforcement + health (e2e)', () => {
       message: expect.stringContaining('public route reachable'),
     });
   });
+});
+
+/**
+ * A deliberately UNCLASSIFIED controller (no @Public(), no @Classified()). It lives
+ * only in this test file — never in src/ — because a live unclassified route would
+ * abort a real boot (see demo.controller.ts). Used to prove both deny-by-default layers.
+ */
+@Controller('probe')
+class UnclassifiedProbeController {
+  @Get('unclassified')
+  unclassifiedRoute(): { message: string } {
+    return { message: 'this body must never be reached — the guard denies first' };
+  }
+}
+
+/** Reflect every mounted route of `imports`/`controllers` into an OperationInventory. */
+async function scanRoutes(opts: Pick<ModuleMetadata, 'imports' | 'controllers'>) {
+  const moduleRef = await Test.createTestingModule({
+    imports: [DiscoveryModule, ...(opts.imports ?? [])],
+    controllers: opts.controllers ?? [],
+    providers: [OperationInventoryScanner],
+  }).compile();
+  const inventory = moduleRef.get(OperationInventoryScanner).scan('app');
+  await moduleRef.close();
+  return inventory;
+}
 
-  it('GET /demo/unclassified is DENIED (403) — deny-by-default (ADR-0002)', async () => {
-    const res = await request(app.getHttpServer()).get('/demo/unclassified');
-    expect(res.status).toBe(403);
-    // The guard denies BEFORE the handler body runs.
-    expect(res.body.message).toContain('no access classification');
+describe('__APP_NAME__ — deny-by-default (ADR-0002)', () => {
+  it('BOOT layer: an unclassified route ABORTS boot via verifyGatable (fail-closed)', async () => {
+    const inventory = await scanRoutes({ controllers: [UnclassifiedProbeController] });
+    // The same check the identity boot provider runs: a forgotten declaration means the
+    // app refuses to start, not that the route silently serves traffic.
+    expect(() => new CatalogReconciler().verifyGatable(inventory, createModuleRegistry())).toThrow(
+      CatalogGatabilityError,
+    );
+    expect(() => new CatalogReconciler().verifyGatable(inventory, createModuleRegistry())).toThrow(
+      /UnclassifiedProbeController#unclassifiedRoute/,
+    );
+  });
+
+  it('BOOT layer: every route in YOUR AppModule is @Public() or @Classified() (none stranded)', async () => {
+    // Fails the moment a route is added without a classification — the same routes the
+    // boot check would strand. (Registering @Classified keys is the identity module's job,
+    // so only the "forgotten declaration" half is asserted here.)
+    const inventory = await scanRoutes({ imports: [AppModule] });
+    expect(inventory.operations.length).toBeGreaterThan(0);
+    const { strandedOperations } = checkCompleteness(inventory, createModuleRegistry());
+    expect(strandedOperations.map((o) => o.operationId)).toEqual([]);
+  });
+
+  it('REQUEST layer: an unclassified route is DENIED (403) before its handler runs', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [ShieldModule.forRoot()],
+      controllers: [UnclassifiedProbeController],
+    }).compile();
+    const probeApp = moduleRef.createNestApplication();
+    await probeApp.init();
+    try {
+      const res = await request(probeApp.getHttpServer()).get('/probe/unclassified');
+      expect(res.status).toBe(403);
+      // The guard denies BEFORE the handler body runs.
+      expect(res.body.message).toContain('no access classification');
+    } finally {
+      await probeApp.close();
+    }
   });
 });

package/template/server/eslint.config.js

@@ -1,95 +0,0 @@
-// 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). THIS lint rule is the BACKSTOP: it fails the build if a
-// file under `src/features/**` imports a raw DB symbol or calls a raw DB method, so
-// an off-road attempt is a red build, not a silent success.
-//
-// 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).' },
-];
-
-/**
- * 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.
- */
-const FORBIDDEN_DB_NAMED_FROM = [
-  {
-    name: '@astram/guard',
-    importNames: ['SHIELD_DB_POOL'],
-    message: 'Wall: the DB pool is sealed inside the engine — features use the RecordEngine (@astram/engine).',
-  },
-];
-
-export default tseslint.config(
-  js.configs.recommended,
-  ...tseslint.configs.recommended,
-  {
-    ignores: ['dist/**', 'node_modules/**'],
-  },
-  // ── The wall: scoped to feature code ──────────────────────────────────────
-  {
-    files: ['src/features/**/*.ts'],
-    rules: {
-      'no-restricted-imports': [
-        'error',
-        {
-          paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
-          patterns: [
-            {
-              group: ['**/adapters/mariadb-*', '@astram/engine/dist/adapters/*'],
-              message:
-                'Wall: the engine adapters (pool/uow/audit) are framework-internal — 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).',
-        },
-      ],
-    },
-  },
-);