create-astram-app 0.4.0 → 0.6.0

package/README.md

@@ -1,61 +1,234 @@
 # create-astram-app
 
-The Astram app scaffolder (ADR-0023 §3). Emits a **new consumer app** that depends
-on the published, immutable framework (`@astram/core`, `@astram/guard`,
-`@astram/sdk`) and enforces **deny-by-default** from the first boot.
+The Astram app scaffolder (ADR-0023 §3). It emits a **new consumer app**: a NestJS API that
+depends on the published, immutable framework packages and enforces **deny-by-default** from the
+first boot, plus (optionally) a complete identity frontend. You write features; the framework
+owns identity, authentication, sessions, authorization and audit.
 
 ## Use it
 
 ```bash
-npx create-astram-app my-app
-cd my-app
+npx create-astram-app my-app                    # server/ only
+npx create-astram-app my-app --with-frontend    # server/ + frontend/ (identity UI)
+```
+
+`--with-frontend` may come before or after the name. The app name must be a single directory
+name (letters, numbers, `.`, `_`, `-`; no leading dot).
+
+```bash
+cd my-app/server
 npm install
-npm run dev        # boots the app; GET /health → 200, unclassified route → 403
+npm run dev        # API on http://localhost:3000; GET /health → 200, GET /demo/public → 200
+npm test           # proves deny-by-default (an unclassified route is denied)
+
+cd ../frontend     # only with --with-frontend
+npm install
+npm run dev        # identity UI on http://localhost:5173 (proxies /api → :3000)
 ```
 
-## What it emits
+### Add the frontend to an existing app
+
+```bash
+cd my-app                                  # the app root (the folder that holds server/)
+npx -p create-astram-app astram-add-frontend
+```
 
-A running, framework-**enforced** NestJS app (the minimal, clean version of
-[`examples/example-backend/`](../examples/example-backend/)):
+`astram-add-frontend` is a second bin in the `create-astram-app` package, so `npx` needs
+`-p create-astram-app` unless the package is already installed (then plain
+`npx astram-add-frontend` works). It copies the frontend template into `./frontend/`, substitutes
+the app name from `./package.json` (or the folder name), and **never overwrites an existing
+file**. Re-running it later only adds files the newer template has and your copy lacks.
+
+## What it emits
 
 ```
 my-app/
-├── package.json         depends on @astram/core ^0.1.0, @astram/guard ^0.1.1,
-│                        @astram/sdk ^0.1.0 (published ranges — NEVER workspace:*),
-│                        plus the NestJS runtime. "private": true.
-├── tsconfig.json + tsconfig.build.json
-├── vitest.config.ts
-├── src/
-│   ├── main.ts          bootstraps Nest; loadAppConfig from @astram/guard
-│   ├── app.module.ts    imports ShieldModule.forRoot() — the ONE seam
-│   ├── health/          @Public health probes + a demo denied route (enforcement proof)
-│   └── features/        EMPTY — the developer's editable space
-├── test/                enforcement e2e (200 health + 403 unclassified)
-├── .astram/guide/       DEVELOPER-OWNED guide layer (ADR-0025) — upgrade-safe, never touched
-├── .env.example         config references only (safe defaults; boots with no .env)
-├── .gitignore
-└── README.md            how to run + how to add features the framework way
+├── server/                    the API (NestJS) — always emitted
+│   ├── package.json           @astram/core, guard, engine, identity, migrate, guide, sdk as
+│   │                          published semver ranges (never workspace:*), NestJS runtime
+│   ├── src/main.ts            bootstrap; reads TRUST_PROXY → Express `trust proxy`
+│   ├── src/app.module.ts      ShieldModule.forRoot() — the ONE seam (auth/identity wiring
+│   │                          documented in its header comment)
+│   ├── src/health/            @Public health probes + /demo/public (the unclassified demo
+│   │                          route is commented out → 404; see demo.controller.ts)
+│   ├── src/features/          EMPTY — your editable space
+│   ├── test/                  enforcement e2e: 200 health; a test-only unclassified route is
+│   │                          denied 403 and fails the verifyGatable boot check
+│   ├── eslint.config.mjs      the feature wall: no raw DB access anywhere in src/** except
+│   │                          app.module.ts / main.ts
+│   ├── scripts/               dev runner (sets NODE_ENV=development), guide sync
+│   └── .env.example           config references only (boots with no .env)
+├── frontend/                  only with --with-frontend (see below)
+├── .astram/guide/             DEVELOPER-OWNED guide layer (ADR-0025) — never touched on upgrade
+├── CLAUDE.md, .gitignore
+└── README.md                  how to run + how to add features the framework way
+```
+
+`server/` scripts: `dev`, `build`, `start`, `test`, `lint`, `migration:run`,
+`migration:status`, `migration:revert`, `guide:sync`.
+
+## The frontend (`--with-frontend` / `astram-add-frontend`)
+
+A Vite + React + shadcn/ui app whose views you own and edit; the auth and API logic comes from
+`@astram/frontend-core` and `@astram/sdk` and updates with `npm update`. See
+`frontend/FRONTEND.md` in the generated app for the update and re-skin model.
+
+- **Sign-in flows:** login, MFA challenge (TOTP or a recovery code), forced MFA re-enrolment
+  after a recovery-code login, forgot password, reset password.
+- **Account:** profile, change password, two-factor devices and recovery codes.
+- **Administration** (shown only to users whose roles grant it): companies, users (memberships
+  and role postings), roles, access (role grants and access bundles), record policies (guided rule
+  builder), service accounts (roles, scope, API keys with an explicit expiry), cross-tenant grants
+  (offer, inbox, revoke), audit log; owner shares from record screens.
+- **Sessions:** a 401 refreshes the access token once and retries (single-flight, shared across
+  tabs with Web Locks); a refresh outage keeps you signed in; a rejected refresh signs you out and
+  remembers the page; sign-out in one tab reaches the others.
+- **Content-Security-Policy:** `index.html` ships a strict CSP (`script-src 'self'`, no inline
+  script or eval). A dev-only Vite plugin relaxes it for hot reload. If your API is not served
+  same-origin under `/api`, add its origin to `connect-src`.
+
+The admin pages need the server's identity wiring (below); without it they 404.
+
+## Turning on auth and the identity admin
+
+`server/src/app.module.ts` starts enforcement-only (`ShieldModule.forRoot()`: no database, no
+Redis). Its header comment shows the full wiring. In short:
+
+```ts
+const rootIds: string[] = [/* platform-admin user uuids, read from your config */];
+const authzPool = createIdentityAuthzPool();         // from @astram/identity
+
+imports: [
+  ShieldModule.forRoot({
+    auth: true,
+    emailSender: myEmailSender,                       // or 'disabled'
+    rootIds,
+    identityActionKeys: identityAuthActionKeys,
+    identityControlPlaneKeys,
+    recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]),
+  }),
+  IdentityFeatureModule.forRoot({ rootIds, extraObjects: [/* YourType */] }),
+],
 ```
 
+## Production requirements
+
+With `auth: true`, check every item before the first production deploy.
+
+- **`emailSender`.** Outside `NODE_ENV=development|test`, `auth: true` fails boot unless you pass
+  an `EmailSender` (`send({ to, subject, html, text })`, e.g. SMTP or SendGrid) or
+  `emailSender: 'disabled'` (no reset emails; `POST /auth/forgot-password` still answers 204).
+  The dev logger, which prints reset links, is never used in production.
+- **Explicit `NODE_ENV`.** Set `NODE_ENV=production`. `npm run dev` sets `development` for you;
+  `npm start` sets nothing. An unset `NODE_ENV` counts as production for the email rule, and the
+  framework's dev seed migrations run only under `development` (or `ASTRAM_SEED_DEV=1`).
+- **`TRUST_PROXY`.** The real number of reverse-proxy hops in front of the app (`0` = none,
+  `1` = behind the Astram Traefik). Unset turns the per-IP limits for login, forgot-password and
+  reset-password off, with a boot warning. Too high lets clients spoof their IP.
+- **`REFRESH_HMAC_KEY`.** A long random secret, supplied through your secrets mechanism, never
+  committed. Boot fails without it.
+- **Redis.** Required with auth: sessions, cached permission facts, the permission version, MFA
+  challenges and rate limits live there, and the request path reads only Redis. If Redis is down,
+  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).
+- **`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
+  them when you turn auth on.
+- **Migrations with the DDL account.** Run `npm run migration:run` with `DDL_DB_USER` /
+  `DDL_DB_PASSWORD` (a DDL-capable deploy account; host, port and database come from `APP_DB_*`).
+  The running app's `APP_DB_*` account must not hold DDL. The framework's guard and identity
+  migrations run first, then yours (`APP_MIGRATION_DIR`). Upgrading to guard 0.8 needs identity
+  migration `1710000000019-AddSessionMustReenroll`: apply migrations **before** starting the new
+  version. Concurrent deploys are safe (migrations hold a database lock;
+  `APP_MIGRATION_LOCK_TIMEOUT`, default 120 s).
+- **`--strict`.** `migration:status` and `migration:run` report migrations whose file changed
+  after they ran (drift). Add `--strict` in CI against a fresh database to fail on drift. Do not
+  edit an applied migration. Out-of-order pending migrations are only a warning, because
+  framework upgrades ship migrations older than your own.
+- **Existing Astram infra database volumes.** Init SQL runs only on an empty volume. On a volume
+  created before 2026-10-08, apply
+  `infra/mariadb/upgrade/2026-10-08-shield-core-audit-append-only.sql` once as root (it makes the
+  runtime `shield_core` account append-only on `shield_audit`). See `infra/README.md` in the
+  astram-framework repo.
+- **API clients other than the generated frontend** must refresh tokens one at a time (one
+  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.5.x
+
+The generated app owns its files, and the scaffolder never overwrites them, so an upgrade has
+two parts.
+
+**1. Bump the framework ranges** in `server/package.json` (`@astram/core` ^1.4.0,
+`@astram/guard` ^0.8.0, `@astram/engine` ^0.4.0, `@astram/identity` ^0.5.0,
+`@astram/migrate` ^0.3.0, `@astram/guide` ^0.2.0; `@nestjs/*` ^11.2.7) and
+`frontend/package.json` (`@astram/frontend-core` ^0.5.0), then `npm install` in both. Run the
+migrations before starting the new server.
+
+**2. Copy these files from a fresh scaffold** (`npx create-astram-app@latest tmp-app
+--with-frontend`), and merge by hand where you changed them:
+
+| File | Why |
+|---|---|
+| `server/src/main.ts` | reads `TRUST_PROXY` |
+| `server/scripts/dev.mjs` | `npm run dev` sets `NODE_ENV=development` |
+| `server/eslint.config.mjs` (delete the old `eslint.config.js`), `lint` script in `server/package.json` | lint no longer crashes; wider feature wall over `src/**/*.{ts,mts,cts}` |
+| `server/scripts/sync-astram-guide.mjs` | guide sync only in an app root, `ASTRAM_GUIDE_SYNC=0`, never fails install |
+| `server/.env.example` | `TRUST_PROXY`, `NODE_ENV`, `REDIS_COMMAND_TIMEOUT_MS`, `LOGIN_IP_*` |
+| `frontend/src/auth/AuthContext.jsx`, `sessionFlow.js`, `routeGate.js` | token refresh; admin nav after a fresh login; gated deep links |
+| `frontend/src/App.jsx` | `RequireAuth` waits for auth facts |
+| `frontend/src/platform/sessionStore.js` (plus doc-only `httpClient.js`, `shieldTransport.js`) | cross-tab session sync |
+| `frontend/index.html`, `frontend/vite.config.js` | Content-Security-Policy and its dev relaxation |
+| `frontend/src/pages/service-accounts/ServiceAccountsPage.jsx`, `accessModel.js` | asks for an API-key expiry (the server now requires one) |
+
+**Breaking and behaviour changes** (details in each package's CHANGELOG):
+
+- **guard 0.8 (breaking):** `auth: true` outside development/test fails boot without
+  `emailSender` (or `'disabled'`).
+- **Login:** users with a confirmed MFA device must complete `/auth/mfa` on every password login;
+  5 wrong TOTP codes lock MFA for 15 minutes; a TOTP code works once. Lockout counters are per
+  account now (they reset once on upgrade). Per-IP limits need `TRUST_PROXY`. Disabled accounts
+  cannot sign in, and disabling a user ends their sessions.
+- **Sessions:** a refresh-minted access token lives at most the access TTL; the previous token
+  stops working 30 s after a refresh; a replayed refresh token kills the session's live access
+  tokens; roles follow posting changes on the next request without re-login; after a Redis loss
+  the next refresh rebuilds the session instead of forcing a login. A Redis outage now fails fast
+  (about 2 s) instead of hanging; rate limiters stop limiting during the outage.
+- **Identity API:** errors map to 403/404/409/400/503 instead of 500. `PUT /identity/companies/:uuid`
+  changes only `name`/`status`; moves use `PUT /identity/companies/:uuid/parent`. User updates
+  accept only `username`/`email`/`status`, and changing another user's email or status needs
+  dominance over that user. Role grants and postings are limited to roles you hold and that are
+  used only inside your subtree. Non-root admins cannot create top-level companies or attach a
+  user from outside their subtree. Grant changes are audited. Issuing a service-account key needs
+  `expiresAtMs` or `neverExpires: true`. API keys use the account's current scope and roles.
+- **Engine:** non-root creates of subtree-scoped types are walled (403 outside your subtree);
+  update/delete/get of an unreachable id is a 403 instead of a silent no-op; record rules with
+  field conditions now apply to single-record reads and writes; unsorted lists come back in
+  primary-key order. Custom `RecordEngine` implementations must add `transaction` and
+  `lockForUpdate`.
+- **Migrate:** migrations are ordered numerically (mixed-width prefixes may reorder; check
+  `migration:status`), runs take a database lock, and the tracking table gains a `checksum` column
+  (added automatically).
+- **Core:** registering the same `(typeKey, actionKey)` twice across modules now fails at boot.
+
 ## Guarantees
 
-- **Immutable-core consumption** — the emitted `package.json` uses published semver
-  ranges, never `workspace:*` and never a source symlink. The framework upgrades via
-  `npm update`; the app's `src/` is never touched.
-- **Never clobbers** — scaffolding into an existing directory only writes files that
-  do NOT already exist. A developer-authored `docs/`, `.astram/guide/`, `README`, or
-  any other file is left exactly as-is (and reported as skipped). astram3's program
-  docs survive scaffolding.
-- **Runs immediately** — `npm install && npm run dev` boots a framework-enforced app
-  with no further wiring. (A turnkey login/session boilerplate arrives in a later
-  framework release; today the app gives correct-by-default enforcement.)
-- **Honest** — the CLI never prints "not implemented"; it scaffolds a real app and
-  tells you how to run it and add a feature.
+- **Immutable-core consumption** — the emitted `package.json` files use published semver ranges,
+  never `workspace:*` or a source symlink. The framework upgrades via `npm update`; your `src/`
+  is never touched.
+- **Never clobbers** — scaffolding into an existing directory (or re-running
+  `astram-add-frontend`) writes only files that do not exist yet. Your `docs/`, `.astram/guide/`,
+  README and edited files are left as they are and reported as skipped.
+- **Runs immediately** — `npm install && npm run dev` boots a framework-enforced API with no
+  `.env`. Real login and the identity admin need the database, Redis and the wiring above.
 
 ## Commands (for developing this package)
 
 ```bash
-pnpm --filter create-astram-app build   # tsc → dist/index.js (the CLI)
-pnpm --filter create-astram-app test    # vitest — CLI + never-clobber + emitted-shape
+pnpm --filter create-astram-app build   # tsc → dist/index.js, dist/add-frontend.js
+pnpm --filter create-astram-app test    # vitest — CLI, never-clobber, emitted shape, lint wall
 pnpm --filter create-astram-app lint
+pnpm template:verify                    # (repo root) scaffold + build/lint/test against packed tarballs
 ```

package/dist/add-frontend.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-frontend.js","sourceRoot":"","sources":["../src/add-frontend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"add-frontend.js","sourceRoot":"","sources":["../src/add-frontend.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -11,17 +11,18 @@
  * builds features in the emitted `src/features/`; the framework lives read-only
  * in `node_modules` and upgrades through `npm update`.
  *
- * What the emitted app IS today (honest scope — Phase 0a):
+ * What the emitted app IS:
  *   A running, framework-ENFORCED NestJS app. `ShieldModule.forRoot()` is the ONE
  *   registration seam: it wires the global deny-by-default guard (ADR-0002), so
  *   every route is denied unless explicitly classified (`@Public()`/`@Classified()`).
  *   Health probes + a demo route prove enforcement from the consumer's side.
- *   A turnkey login/session boilerplate arrives in a later framework release — this
- *   scaffold does NOT emit a fake login route.
+ *   Login, sessions, MFA and the identity admin come from the framework: turn them on
+ *   with `ShieldModule.forRoot({ auth: true, … })` + `IdentityFeatureModule.forRoot()` (see
+ *   the comment block in server/src/app.module.ts). `--with-frontend` adds the web UI.
  *
  * Reference skeleton: `examples/example-backend/` in the astram-framework repo.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /** Token substituted with the app name at copy time (in package.json name, README title, …). */
@@ -137,7 +138,8 @@ export function copyTemplate(srcDir, destDir, appName, report, relBase = '') {
 }
 /** Text extensions that get token substitution + utf8 handling. */
 function isTextFile(fileName) {
-    return /\.(json|ts|js|mjs|cjs|md|txt|example|yml|yaml|gitignore)$/i.test(fileName) || fileName.startsWith('_');
+    return (/\.(json|ts|js|mjs|cjs|md|txt|example|yml|yaml|gitignore)$/i.test(fileName) ||
+        fileName.startsWith('_'));
 }
 /**
  * Names of the template's top-level SUBTREES that are copied separately (not
@@ -248,17 +250,20 @@ export function main(argv = process.argv.slice(2)) {
         console.log('    identity UI). You can still add any UI framework yourself later.');
     }
     console.log('  • The framework installed in server/ as immutable dependencies (@astram/core,');
-    console.log('    @astram/guard, @astram/engine, @astram/sdk) — you never edit it; upgrade via');
+    console.log('    @astram/guard, @astram/engine, @astram/identity, @astram/migrate, @astram/sdk,');
+    console.log('    @astram/guide) — you never edit it; upgrade via');
     console.log('    `npm update`.');
     console.log('  • server/src/features/ — your editable API space. Add a feature by writing a');
     console.log('    Nest module/controller there and registering it in server/src/app.module.ts.');
     console.log('  • .astram/guide/ — your own, upgrade-safe project-rules space (ADR-0025).');
-    console.log('\n  (A turnkey login/session boilerplate ships in a later framework release;');
-    console.log('   today the app gives you correct-by-default ENFORCEMENT out of the box.)');
+    console.log('\n  Login, sessions, MFA and the identity admin are built in: enable them in');
+    console.log('  server/src/app.module.ts (see its comment block). Before production, read the');
+    console.log('  README "Production requirements" (emailSender, NODE_ENV, TRUST_PROXY, migrations).');
     console.log('\nNext steps:');
     console.log(`  cd ${appName}/server`);
     console.log('  npm install');
-    console.log('  npm run dev        # boots the API; GET /health → 200, unclassified → 403');
+    console.log('  npm run dev        # boots the API; GET /health → 200, GET /demo/public → 200');
+    console.log('  npm test           # proves deny-by-default: an unclassified route is denied');
     if (withFrontend) {
         console.log('');
         console.log(`  cd ${appName}/frontend`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "create-astram-app",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "MIT",
-  "description": "Scaffolder for a new Astram app — emits a running, framework-enforced consumer project (empty src/features/ + deny-by-default enforcement) that installs the immutable @astram/core, @astram/guard, and @astram/sdk framework.",
+  "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",
   "bin": {
     "create-astram-app": "dist/index.js",

package/template/README.md

@@ -1,20 +1,24 @@
 # __APP_NAME__
 
-An **Astram consumer app**, scaffolded with `create-astram-app`. A monorepo with a
-`server/` (the API) and a `frontend/` (your UI). The API depends on the published,
-immutable framework packages ([`@astram/core`](https://www.npmjs.com/package/@astram/core),
+An **Astram consumer app**, scaffolded with `create-astram-app`. A `server/` (the API) and,
+if you scaffolded with `--with-frontend` or ran `astram-add-frontend`, a `frontend/` (the
+identity UI). The API depends on the published, immutable framework packages
+([`@astram/core`](https://www.npmjs.com/package/@astram/core),
 [`@astram/guard`](https://www.npmjs.com/package/@astram/guard),
 [`@astram/engine`](https://www.npmjs.com/package/@astram/engine),
+[`@astram/identity`](https://www.npmjs.com/package/@astram/identity),
+[`@astram/migrate`](https://www.npmjs.com/package/@astram/migrate),
+[`@astram/guide`](https://www.npmjs.com/package/@astram/guide),
 [`@astram/sdk`](https://www.npmjs.com/package/@astram/sdk)) and enforces
 **deny-by-default** from the very first boot. You build features; the framework lives
-read-only in `server/node_modules` and upgrades via `npm update` — you never edit it.
+read-only in `node_modules` and upgrades via `npm update` — you never edit it.
 
 ## Layout
 
 ```
 __APP_NAME__/
   server/       the API (NestJS + the Astram framework enforcement)
-  frontend/     your UI (empty — add Vite/React/Next/… and call the API)
+  frontend/     the identity UI (only with --with-frontend / astram-add-frontend)
   .astram/      your project-owned, upgrade-safe AI/dev guide (ADR-0025)
   docs/         your own docs (the scaffolder never clobbers this)
 ```
@@ -24,7 +28,7 @@ __APP_NAME__/
 ```bash
 cd server
 npm install
-npm run dev        # boots the API (tsx watch) on http://localhost:3000
+npm run dev        # boots the API on http://localhost:3000 (sets NODE_ENV=development)
 ```
 
 Then:
@@ -32,15 +36,19 @@ Then:
 ```bash
 curl -i localhost:3000/health              # 200 — @Public health probe
 curl -i localhost:3000/demo/public         # 200 — explicit @Public() opt-out
-curl -i localhost:3000/demo/unclassified   # 403 — DENIED (no classification)
 ```
 
-That last 403 is the whole point: **every route is denied unless you explicitly
-classify it.** Forgetting to declare a route locks the door instead of silently
-exposing it.
+The scaffold ships no unclassified route (the demo one in
+`src/health/demo.controller.ts` is commented out, so `/demo/unclassified` is a 404).
+The point is: **every route is denied unless you explicitly classify it.** An
+unclassified route gets 403 from the global guard, and once `IdentityFeatureModule`
+is wired the app refuses to boot (`verifyGatable`). Forgetting to declare a route
+locks the door instead of silently exposing it. `npm test`
+(`test/enforcement.e2e.spec.ts`) proves both with a test-only controller.
 
 Other `server/` scripts: `npm run build` (→ `dist/`), `npm start` (run the build),
-`npm test`, `npm run lint`.
+`npm test`, `npm run lint`, `npm run migration:run` / `migration:status` /
+`migration:revert`.
 
 ## How the API wires the framework
 
@@ -58,10 +66,27 @@ export class AppModule {}
 ```
 
 `ShieldModule.forRoot()` binds the global deny-by-default guard (ADR-0002), the
-boot-pool assertion (ADR-0018), and the Core decision-authority token. You never
-re-implement enforcement — you register it once and add your controllers. Enable the
-full auth surface (login/MFA/refresh/logout) with `ShieldModule.forRoot({ auth: true,
-credentialResolver, decisionAuthority })`.
+boot-pool assertion (ADR-0018), and the Core decision-authority token. With no options it
+needs no database or Redis. To turn on login, sessions, MFA and the identity admin
+(`/auth/*`, `/account/*`, `/identity/*`), follow the commented wiring in the header of
+`server/src/app.module.ts`: `ShieldModule.forRoot({ auth: true, emailSender, rootIds,
+identityActionKeys, identityControlPlaneKeys, recordAuthorization })` plus
+`IdentityFeatureModule.forRoot({ rootIds, extraObjects })`. The framework provides the
+credential store, MFA, session handling and the decision authority; you write none of them.
+
+### Before you deploy with auth on
+
+- Pass an `emailSender` (or `'disabled'`): outside `NODE_ENV=development|test` boot fails
+  without one. Set `NODE_ENV=production` explicitly; `npm start` does not set it.
+- Set `TRUST_PROXY` to your real proxy hop count, or the per-IP login/reset limits stay off.
+- Set `REFRESH_HMAC_KEY` (a long random secret, never committed) and `REDIS_URL`. Redis is
+  required: the request path reads only Redis and fails closed when it is down.
+- Pass the same `rootIds` (platform-admin user uuids, from config) to both `forRoot` calls.
+- Run `npm run migration:run` with the DDL account (`DDL_DB_USER` / `DDL_DB_PASSWORD`) before
+  starting a new version. Add `--strict` in CI to fail on edited migrations.
+
+The full list, and how to upgrade an app scaffolded with an earlier version, is in the
+[`create-astram-app` README](https://www.npmjs.com/package/create-astram-app).
 
 ## Add a feature (the framework way)
 
@@ -69,18 +94,24 @@ credentialResolver, decisionAuthority })`.
 2. Register it in `server/src/app.module.ts` (add the module to `imports`, or its
    controller to `controllers`).
 3. **Classify every route:** `@Public()` for open routes, `@Classified({ typeKey,
-   action })` for guarded ones. Anything unclassified is denied (403) by design.
+   action })` for guarded ones. Anything unclassified is denied by design (403; with
+   `IdentityFeatureModule` wired, the app refuses to boot).
 4. **Data access goes through the framework's RecordEngine** — never a raw DB pool.
-   The `server/eslint.config.js` wall rule fails the build on off-road DB access.
+   The `server/eslint.config.mjs` wall fails lint on off-road DB access anywhere in
+   `src/**` except `app.module.ts` and `main.ts`.
 5. Add a test (see `server/test/` for the pattern).
 
 `server/src/features/` starts empty — it's your space.
 
 ## The frontend
 
-`frontend/` is intentionally empty — Astram is a **backend security kernel**, so it
-does not impose a UI framework. Add whatever you like and call the API. See
-`frontend/README.md` for the auth endpoints your UI will consume.
+With `--with-frontend` (or `npx -p create-astram-app astram-add-frontend` from this
+folder), `frontend/` holds a Vite/React identity UI: login with MFA and recovery codes,
+forgot/reset password, account settings, and admin pages for companies, users, roles,
+access, record policies, service accounts, cross-tenant grants and audit. It refreshes
+expired access tokens on its own and ships a strict Content-Security-Policy. The views are
+yours to edit; the logic updates through `@astram/frontend-core`. See
+`frontend/FRONTEND.md`.
 
 ## The `.astram/guide/` directory
 

package/template/frontend/README.md

@@ -1,16 +1,26 @@
 # frontend
 
-Your UI lives here. This folder is intentionally empty — the Astram framework is a
-**backend security kernel**, so it does not impose a frontend framework. Add whatever
-you like (Vite + React, Next.js, SvelteKit, a mobile app's web build, …) and point it
-at the API in `../server` (default `http://localhost:3000`).
+The Astram **identity UI** for this app: a Vite + React + shadcn/ui app scaffolded by
+`create-astram-app --with-frontend` or `astram-add-frontend`. The files here are yours to
+edit; the auth and API logic comes from `@astram/frontend-core` and `@astram/sdk` and
+updates with `npm update`. See [`FRONTEND.md`](./FRONTEND.md) for the update, no-clobber
+and re-skin model.
 
-The API's auth surface is ready to consume:
+```bash
+npm install
+npm run dev        # http://localhost:5173; proxies /api → http://localhost:3000 (API_URL to override)
+```
 
-- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens: { accessToken, refreshToken } }`
-- `POST /auth/refresh` `{ refreshToken }` → new tokens
-- `POST /auth/logout` `{ sessionId }` → 204
-- Protected routes: send `Authorization: Bearer <accessToken>`. A `@Classified` route
-  is enforced by the framework — no token → 401, denied by policy → 403.
+Start the API (`../server`) first, with auth turned on, or there is nothing to sign in to.
 
-See `../server/src/features/` for the API features your UI will call.
+What it includes:
+
+- Login, MFA challenge (TOTP or a recovery code), forced re-enrolment after a recovery-code
+  login, forgot password, reset password.
+- Account: profile, change password, two-factor devices and recovery codes.
+- Admin pages, shown only when your roles allow them: companies, users (memberships and
+  role postings), roles, access, record policies, service accounts, cross-tenant grants,
+  audit.
+- Token refresh: a 401 refreshes once and retries (single-flight, shared across tabs).
+- A strict Content-Security-Policy in `index.html`. If the API is not served same-origin
+  under `/api`, add its origin to `connect-src`.

package/template/frontend/index.html

@@ -2,6 +2,22 @@
 <html lang="en" suppressHydrationWarning>
   <head>
     <meta charset="UTF-8" />
+    <!--
+      Content-Security-Policy (D11). The session tokens live in localStorage, so no script
+      may run unless it is served from this origin: no inline scripts, no eval, no third-party
+      script hosts. Allowed beyond 'self':
+        style-src 'unsafe-inline'  the UI kit (sonner, Radix scroll lock) injects <style> tags
+        fonts.googleapis/gstatic   the Inter/JetBrains Mono import in src/index.css
+        img-src data: blob:        the MFA QR code is a data: URL
+      `npm run dev` relaxes script-src/connect-src for Vite's React-refresh preamble and HMR
+      websocket (see `devCsp` in vite.config.js); the built app gets this policy unchanged.
+      Add an API origin to connect-src if the frontend calls one other than same-origin /api.
+      frame-ancestors cannot be set in a <meta>; send it (or X-Frame-Options) as a header.
+    -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: blob:; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'"
+    />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>__APP_NAME__</title>

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.3.0",
+    "@astram/frontend-core": "^0.5.0",
     "@astram/sdk": "^0.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",