@astram/guide 0.1.0 → 0.2.0

package/CAPABILITIES.md

@@ -1,58 +1,187 @@
 <!--
-  @astram/guide — CAPABILITIES.md   (framework-owned, version 0.1.0)
+  @astram/guide — CAPABILITIES.md   (framework-owned, version 0.2.0)
 
   What the Astram framework provides THIS version. Refreshed on upgrade (ADR-0025).
   Use this to answer "does the framework already do X?" before building — and, if it
   does NOT, that's a Rule-4 gap (STOP and flag in .astram/guide/gaps.md).
+
+  Matches the framework release: @astram/core 1.4 · guard 0.8 · engine 0.4 · identity 0.5 ·
+  frontend-core 0.5 · migrate 0.3 · sdk 0.2 · create-astram-app 0.6.
 -->
 
-# Astram Framework — Capabilities (v0.1.0)
+# Astram Framework — Capabilities (v0.2.0)
+
+The building blocks the framework provides. Consume these; do not reimplement them. Everything
+below is wired by the two `forRoot` calls in your `app.module.ts`; you write no security code.
+
+## Wiring (the ONE seam, plus the identity module)
+
+```ts
+import { ShieldModule } from '@astram/guard';
+import {
+  IdentityFeatureModule, identityAuthActionKeys, identityControlPlaneKeys,
+  createIdentityAuthzPool, buildIdentityRecordAuthorization,
+} from '@astram/identity';
+
+const rootIds = ['<platform-admin user uuid>'];   // from config, never from a request
+const authzPool = createIdentityAuthzPool();
 
-The building blocks the framework provides. Consume these; do not reimplement them.
+imports: [
+  ShieldModule.forRoot({
+    auth: true,
+    emailSender: myEmailSender,                     // or 'disabled' — REQUIRED outside dev/test
+    rootIds,
+    identityActionKeys: identityAuthActionKeys,
+    identityControlPlaneKeys,
+    recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]),
+  }),
+  IdentityFeatureModule.forRoot({ rootIds, extraObjects: [/* YourType */] }),
+],
+```
+
+- **`ShieldModule.forRoot(options?)`** (`@astram/guard`; `forRootAsync` for DI-computed options).
+  Options: `auth?`, `recordAuthorization?` (or a pre-built `decisionAuthority?`, never both),
+  `emailSender?: EmailSender | 'disabled'`, `rootIds?`, `identityActionKeys?`,
+  `identityControlPlaneKeys?`, `config?`, and optional overrides `credentialResolver?`,
+  `profileResolver?`, `credentialWriter?`, `resetTokenStore?`, `recoveryCodeStore?`,
+  `profileWriter?`, `sessionSweeper?`, `auditSink?`, `mfaDeviceStore?`, `totpVerifier?`,
+  `sessionFactsProjector?`, `scopeSubtreeResolver?`, `membershipChecker?`. With `auth: true` every
+  override has a MariaDB/Redis default; leave them out unless you have a reason.
+- **`IdentityFeatureModule.forRoot({ rootIds?, extraObjects? })`** (`@astram/identity`). Pass the
+  SAME `rootIds` as `ShieldModule`, and the SAME `extraObjects` as
+  `buildIdentityRecordAuthorization`. Without `rootIds` it logs a boot warning.
+- `ShieldModule.forRoot()` with no options = enforcement only (no DB, no Redis, boots without
+  `.env`). Omitting `recordAuthorization` (and `decisionAuthority`) binds a stub that denies every
+  `@Classified` route.
 
 ## Enforcement (`@astram/guard`)
 - **Global deny-by-default guard** — every route is denied unless `@Public()` or
-  `@Classified({ typeKey, action })`.
-- **Request authentication** — a `@Classified` route resolves the bearer access token
-  → `Principal` → `decide()` automatically. `request.principal` is available to the
-  handler (act as the logged-in user).
-- **The ONE seam** — `ShieldModule.forRoot({ auth?, credentialResolver?, decisionAuthority?, config? })`.
-
-## Auth surface (`@astram/guard`, opt-in `auth: true`)
-- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens }` (or an MFA challenge).
-- `POST /auth/mfa` · `POST /auth/refresh` · `POST /auth/logout`.
-- Argon2id password verification, sessions, refresh-token rotation + reuse detection,
-  opaque access tokens bound to the principal (server-revocable; logout = immediate kill).
-- MFA/TOTP.
-- You provide: a `CredentialResolver` (reads your users) + a `DecisionAuthority` (your policy).
+  `@Classified({ typeKey, action })`. With `IdentityFeatureModule` wired, an unclassified route
+  aborts boot (`verifyGatable`).
+- **One decision authority** — a `@Classified` route resolves the bearer token → `Principal` →
+  `decide()`; `request.principal` is the caller. Identity, tenant, roles and root status come from
+  the session, never from the request.
+- **Redis-only request path** — session, cached facts and the per-tenant permission version are
+  read from Redis; no DB query on a request with fresh facts. Redis unavailable ⇒ deny (fail
+  closed), bounded by `REDIS_COMMAND_TIMEOUT_MS` (default 2000).
+- **Live roles** — a role posting change, a grant change or a user disable bumps the permission
+  version; the next request reloads facts and roles. No re-login needed.
+- **Engine errors → HTTP** — `AuthorizationDeniedError` → 403, `ValidationError` → 400,
+  `EngineUnavailableError` → 503 for your controllers too (global filter; id-free messages).
+
+## Authentication and sessions (`@astram/guard`, `auth: true`)
+- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens }`, or an MFA challenge.
+  `POST /auth/mfa` (TOTP or recovery code) · `POST /auth/refresh` · `POST /auth/logout` ·
+  `GET /auth/me` · `POST /auth/scope-switch` · `POST /auth/forgot-password` ·
+  `POST /auth/reset-password`.
+- `/account/*`: change password, edit profile, MFA devices (enrol, confirm, rename, delete),
+  regenerate recovery codes. A recovery-code login is restricted until a new device is enrolled.
+- Argon2id passwords; opaque access tokens bound in Redis (server-revocable, logout is immediate);
+  refresh-token rotation with reuse detection (a replay revokes the whole lineage and its live
+  access tokens). An access token lives at most the access TTL (15 min default).
+- **MFA enforced**: any user with a confirmed TOTP device must pass `/auth/mfa` on every password
+  login. 5 wrong codes / 15 min per account; a used code cannot be replayed (90 s); the pending
+  challenge lives in Redis (works across instances, never holds the password).
+- **Lockout and rate limits**: per-account login and forgot-password budgets (keyed on the
+  resolved account, so spelling variants share one counter); per-IP limits for login,
+  forgot-password and reset-password, active only when Express `trust proxy` is set explicitly
+  (`TRUST_PROXY` in the scaffold). Rate limiters fail open on a Redis error by design; the request
+  path and the TOTP replay guard fail closed.
+- **Disabled accounts** cannot log in or refresh; disabling a user revokes their sessions and
+  drops their roles at once.
+- **Silent recovery**: after a Redis loss, the next refresh rebuilds the session from MariaDB
+  (no forced re-login); a restricted (recovery-code) session rebuilds restricted.
+- **Email**: reset links go through your `EmailSender` (`send({ to, subject, html, text })`).
+  Outside `NODE_ENV=development|test`, `auth: true` without `emailSender` fails boot;
+  `'disabled'` sends nothing and `/auth/forgot-password` still answers 204.
+- **Service-account API keys** (`Authorization: Bearer ask_…`) authenticate agents and machine
+  clients through the same `decide()` path; scope, status and roles are read live; issuing a key
+  needs an explicit expiry (`expiresAtMs`) or `neverExpires: true`.
+- Override contracts: the login lockout is keyed on the account the injected `credentialResolver`
+  returns for the hint as typed, so use that one resolver wherever login resolves accounts; a
+  custom `totpVerifier` must use a window of at most ±1 step and must not normalise the code, or
+  the 90 s replay claim no longer covers it.
+
+## Identity and tenancy (`@astram/identity`)
+- Admin API under `/identity/*`: companies (create, update name/status, move via
+  `PUT /identity/companies/:uuid/parent`, delete), users, roles, memberships and role postings,
+  access (role ↔ permission grants and access bundles), permission catalog, record policies
+  (guided rule builder, 14 operators, no raw expressions), record shares (owner shares),
+  cross-tenant grants (offer, accept, revoke), service accounts (roles, scope, keys), audit read.
+  `GET /identity/auth-facts` feeds the frontend's permission-gated navigation.
+- **Scoped-hierarchy tenancy** (ADR-0027): a tenant is a company node; an admin's authority covers
+  its subtree. Reads, updates, deletes AND creates of subtree-scoped types are walled in the query
+  (ADR-0030, ADR-0034). Non-root admins cannot create top-level tenants.
+- **No escalation**: you can grant, revoke or assign (via postings) only roles and keys you hold
+  (ADR-0029); a role used outside your subtree is root-only; changing another user's email or
+  status needs dominance over that user. Grant changes are audited in the same transaction.
+- **Cross-tenant access** only through an explicit, consented, scoped, revocable grant (ADR-0009).
+- **Root** = the `rootIds` allowlist only. Root administers the control plane and cannot read
+  customer business data.
+- Migrations for `shield_identity`, `shield_authz`, `shield_app` identity tables ship in
+  `@astram/identity` and `@astram/guard` and run through `@astram/migrate` automatically. Dev seeds
+  (099/100) run only with `NODE_ENV=development` or `ASTRAM_SEED_DEV=1`.
 
 ## The record pipe (`@astram/engine`)
-- **`RecordEngine`** (token `RECORD_ENGINE`) — create/read/update/delete/list over
-  registered tables, through one unbypassable pipe: permission gate (`decide()`) →
-  server-trusted write-context (anti-forgery) → validate → write (real table) →
-  junction sync → audit → event.
-- **Cross-tenant isolation** — a `tenantId`-trusted field auto-scopes reads AND writes
-  to the actor's tenant.
-- **Physical wall** — the raw DB pool is sealed in the engine; feature scope never
-  receives it. Off-road DB access fails the build (the app's `eslint.config.js`).
-- **Gap signal** — an unsupported field type / operation throws
-  `CapabilityNotSupportedError` (a Rule-4 STOP).
-- Field types supported this version: `string`, `number`, `boolean`, `uuid`,
-  `timestamp`, `json`. (Anything else → flag a gap.)
+- **`RecordEngine`** (token `RECORD_ENGINE`) / `RecordsService` — create/get/update/delete/list
+  over registered object types through one pipe: permission gate (`decide()`) → server-trusted
+  write context → validate → write → junction sync → audit (mandatory) → event.
+- **Record decision inputs**: `get`, `update` and `delete` read the stored row first and pass its
+  fields and tenant to `decide()`, so record rules such as "deny update where status eq locked"
+  hold on single-record paths. An unreachable id (missing, other tenant, outside your subtree) is
+  a 403, identical for missing and foreign.
+- **List scoping in the query** (ADR-0028): `list()` returns exactly the rows `decide()` allows
+  (record rules, owner shares, cross-tenant grants, subtree), filtered in SQL; `get()` uses the
+  same scope. Membership/subtree-scoped lists ("companies I belong to") are provided.
+- Stable paging: every `list()` orders by the primary key last.
+- `transaction(fn)` runs several pipe calls in one unit of work (rolls back on any failed write);
+  `lockForUpdate(typeKey, id)` serialises a check-then-write.
+- `@Field({ immutable: true })` create-only fields; `trusted` fields are stamped server-side.
+  `readScope` declares the subtree wall; `create: 'unscoped'` opts a type out of the create wall.
+- **Physical wall** — the raw DB pool is sealed in the engine. The scaffold's
+  `server/eslint.config.mjs` fails lint on driver imports, raw pools, `.query()` and the
+  framework's internal DB exports anywhere in `src/**` except `app.module.ts` and `main.ts`. A lint
+  rule is a backstop, not a sandbox: do not go around it.
+- **Gap signal** — an unsupported field type or operation throws `CapabilityNotSupportedError`
+  (a Rule-4 STOP). Field types this version: `string`, `number`, `boolean`, `uuid`, `timestamp`,
+  `json`.
 
 ## Migrations (`@astram/migrate`)
-- Deploy-time code-table migration runner: timestamped `up()`/`down()` files, a
-  `schema_migrations` table, `migrate` / `migrate:revert` / `migrate:status`. Raw SQL
-  through a DDL-capable deploy account (the running app never holds DDL).
+- `migrate` / `migrate:revert` / `migrate:status` with the deploy-time DDL account (`DDL_DB_*`);
+  the running app never holds DDL. Framework migrations merge with yours (`APP_MIGRATION_DIR`).
+- Numeric ordering, duplicate-id detection, a database lock so concurrent deploys never apply a
+  migration twice (`APP_MIGRATION_LOCK_TIMEOUT`, default 120 s), and drift detection (a changed
+  applied file is reported; `--strict` fails on it). Never edit a migration that already ran.
+
+## Frontend (`@astram/frontend-core`, `@astram/sdk`, scaffolded `frontend/`)
+- `@astram/frontend-core`: auth, account, identity, audit, record-policy, share, cross-tenant and
+  service-account services over an injected `HttpClient`; `createRefreshingHttp` refreshes an
+  expired access token transparently (single-flight, cross-tab lock, one retry; an outage keeps
+  the session). Clients that call `/auth/refresh` concurrently without single-flight can log the
+  user out (reuse detection).
+- `@astram/sdk`: platform-agnostic auth-fact projection (`check` → allowed/deny/unavailable,
+  version-staleness refetch, retry/backoff). The UI never re-decides.
+- The scaffolded frontend (`create-astram-app --with-frontend` or `npx -p create-astram-app
+  astram-add-frontend`) ships login, MFA, recovery, forgot/reset, account and admin pages, with a
+  strict Content-Security-Policy.
 
-## Frontend SDK (`@astram/sdk`)
-- Platform-agnostic fact projection for building UIs against the framework.
+## Available, but NOT wired to a data path (do not assume they protect data yet)
+- **Envelope encryption / per-tenant DEKs** (`createEncryptionService`, `LocalKekCrypto`): the
+  engine exists, but no record field is encrypted and no production `DekStore` ships.
+- **Secrets provider** (`SecretsProvider`, `resolveSecretRefs`, `EncryptedFileSecretsProvider`):
+  the guard's runtime config does not resolve `secret-ref:` values at boot.
+- **Risk engine** (`createRiskEngine`): advisory scoring with no request-path caller.
+- **Hash-chained audit** (`createAuditRecorder`, `verifyChain`): the shipped audit writer is
+  append-only but does not store the chain.
 
-## NOT provided yet (as of v0.1.0) — these are Rule-4 gaps if you need them
+## NOT provided yet — these are Rule-4 gaps if you need them
 - Runtime (no-code) object definition / admin-defined objects + runtime DDL.
 - Formula / lookup / rollup computed fields (the pipe's compute stage is a no-op).
 - Business-rule events (the pipe's emit-event stage is a no-op).
 - Extension-field sidecar (runtime custom fields on a registered table).
-- Membership-scoped list filtering (e.g. "companies I belong to").
+- Per-principal column masking on reads (row-level scoping is provided; column-level is not).
+- External identity providers (OIDC, SAML, LDAP, Entra ID, Cognito, Okta, Google Workspace) and
+  WebAuthn ceremonies.
+- Tenant- or role-mandated MFA (MFA is enforced for users who enrolled a device).
 
 If you need one of these, STOP and flag it in `.astram/guide/gaps.md` (Rule 4).

package/FRAMEWORK_RULES.md

@@ -1,5 +1,5 @@
 <!--
-  @astram/guide — FRAMEWORK_RULES.md   (framework-owned, version 0.1.0)
+  @astram/guide — FRAMEWORK_RULES.md   (framework-owned, version 0.2.0)
 
   This file is the FRAMEWORK layer of the two-layer AI guide (ADR-0025). It is
   installed in node_modules and REPLACED WHOLESALE on `npm update` — never edit it
@@ -30,10 +30,12 @@ the current rules, not a stale memory of them. Your project's own rules in
 ## 1. NEVER edit or bypass the framework
 
 The framework packages (`@astram/core`, `@astram/guard`, `@astram/engine`,
-`@astram/migrate`, `@astram/sdk`, `@astram/guide`) live in `node_modules` and are
-**immutable**. Do not edit them, patch them, monkey-patch them, or reach around their
-public API. You register your app through the ONE seam — `ShieldModule.forRoot(...)` —
-and consume the exported building blocks. That is the entire contract.
+`@astram/identity`, `@astram/migrate`, `@astram/frontend-core`, `@astram/sdk`,
+`@astram/guide`) live in `node_modules` and are **immutable**. Do not edit them, patch
+them, monkey-patch them, or reach around their public API. You register your app through
+the ONE seam — `ShieldModule.forRoot(...)`, plus `IdentityFeatureModule.forRoot(...)` for
+the identity surface — and consume the exported building blocks. That is the entire
+contract.
 
 - **`@astram/core` is especially sacred.** It is the pure security engine. It has no
   reason to be imported directly by feature code and must never be modified.
@@ -48,9 +50,10 @@ the permission gate, validation, audit, and cross-tenant isolation on every writ
 by construction.
 
 This is enforced two ways: the raw DB pool is **sealed inside the engine module** (you
-cannot inject what you are not given), and the app's `eslint.config.js` **fails the
-build** on any off-road DB access under `src/features/**`. If you find yourself
-wanting a raw query, see Rule 4.
+cannot inject what you are not given), and the app's `server/eslint.config.mjs` **fails
+lint** on off-road DB access anywhere in `src/**` (only `app.module.ts` and `main.ts` may
+wire infrastructure). The lint wall is a backstop, not a sandbox: code that slips past it
+is still a Rule 2 violation. If you find yourself wanting a raw query, see Rule 4.
 
 ## 3. Classify every route (deny-by-default)
 
@@ -60,9 +63,10 @@ Every HTTP route is DENIED by the global enforcement guard unless you classify i
   request's bearer token → `Principal` → `decide()` and allows only on `allow`. No
   token → 401; denied → 403.
 
-An unclassified route is a 403, by design — a forgotten declaration locks the door
-instead of silently exposing it. Never make a route public to "make it work"; classify
-it correctly.
+An unclassified route is a 403, by design, and once `IdentityFeatureModule` is wired the
+app refuses to boot with one — a forgotten declaration locks the door instead of
+silently exposing it. Never make a route public to "make it work"; classify it
+correctly.
 
 ## 4. When the framework can't do it: STOP and FLAG the gap — do NOT work around it
 
@@ -87,17 +91,21 @@ signal, not something to catch-and-work-around.
 Resolve internal ids to human-readable labels before they reach a UI or a response a
 user sees. Never put a password, hash, token, or secret in a response body or a log.
 
-## 6. Auth is the framework's; you provide only DATA + POLICY
-
-You do not write login/session/token code — the framework owns it (`ShieldModule
-.forRoot({ auth: true })` gives you `POST /auth/{login,mfa,refresh,logout}` for free).
-Your app contributes exactly two things through the seam:
-- a **`CredentialResolver`** — reads YOUR user/identity tables to answer "what's this
-  user's password hash, tenant, roles?",
-- a **`DecisionAuthority`** — your allow/deny policy.
-
-Never reimplement session handling, token verification, or password hashing in app
-code. If the auth surface lacks something you need, that's Rule 4 (flag the gap).
+## 6. Auth and identity are the framework's; you provide only CONFIG + DATA
+
+You do not write login/session/token/MFA code, user or role administration, or an
+authorization policy engine — the framework owns all of it. `ShieldModule.forRoot({ auth:
+true, recordAuthorization, … })` gives you `/auth/*` and `/account/*`, and
+`IdentityFeatureModule.forRoot(...)` gives you `/identity/*` (companies, users, roles,
+access, record policies, shares, cross-tenant grants, service accounts, audit). Your app
+contributes configuration through the seam (`rootIds` from config, an `emailSender`, your
+own object types as `extraObjects`) and its data; access policy is authored by
+administrators as role grants and record policies, not in code. See `CAPABILITIES.md`.
+
+Never reimplement session handling, token verification, password hashing, or an
+allow/deny check in app code. Never take a tenant, company, role or user id for an access
+decision from the request body — the framework takes them from the session. If the auth
+or identity surface lacks something you need, that's Rule 4 (flag the gap).
 
 ## 7. Fail closed, always
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Astram framework — the AI/dev GUIDE layer (ADR-0025). Ships the framework's hard rules + capabilities manifest as installed, upgrade-refreshed docs. A consumer app's CLAUDE.md references FRAMEWORK_RULES.md from this package; `npm update` replaces it wholesale so new rules arrive cleanly, while the app's own .astram/guide/ layer is never touched. This is the framework-owned FLOOR: an app rule may tighten it, never weaken it.",
   "type": "commonjs",
@@ -20,4 +20,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}