create-astram-app 0.5.0 → 0.6.0

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}\" \"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.4.0",
+    "@astram/guard": "^0.8.0",
+    "@astram/guide": "^0.2.0",
+    "@astram/identity": "^0.5.0",
+    "@astram/migrate": "^0.3.0",
     "@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.)

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/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).',
-        },
-      ],
-    },
-  },
-);