@astram/guide 0.2.8 → 0.2.10

package/CAPABILITIES.md

@@ -27,7 +27,7 @@ const rootIds = rootIdsFromEnv(process.env);       // SHIELD_ROOT_IDS; never fro
 imports: [
   ShieldModule.forRoot({
     auth: true,
-    emailSender: myEmailSender,                     // or 'disabled' — REQUIRED outside dev/test
+    emailSender: 'env',                             // or your EmailSender, or 'disabled' — REQUIRED outside dev/test
     rootIds,
     identityActionKeys: identityAuthActionKeys,
     identityControlPlaneKeys,
@@ -40,7 +40,7 @@ imports: [
 - **`ShieldModule.forRoot(options?)`** (`@astram/guard`; `forRootAsync` for DI-computed options).
   Options: `auth?`, `recordAuthorization?` (or a pre-built `decisionAuthority?`; only for an app
   WITHOUT `IdentityFeatureModule`, never both),
-  `emailSender?: EmailSender | 'disabled'`, `rootIds?`, `identityActionKeys?`,
+  `emailSender?: EmailSender | 'disabled' | 'env'`, `rootIds?`, `identityActionKeys?`,
   `identityControlPlaneKeys?`, `config?`, and optional overrides `credentialResolver?`,
   `profileResolver?`, `credentialWriter?`, `resetTokenStore?`, `recoveryCodeStore?`,
   `profileWriter?`, `sessionSweeper?`, `auditSink?`, `mfaDeviceStore?`, `totpVerifier?`,
@@ -100,15 +100,58 @@ imports: [
 - **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.
+  (`TRUST_PROXY` in the scaffold). On a Redis error the login, MFA and recovery-code budgets fail
+  closed (503), as do the request path and the TOTP replay guard; the forgot-password and
+  reset-password per-IP counters fail open (logged).
 - **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.
+- **Email** (G-010, ADR-0043): `emailSender: 'env'` picks the provider from configuration —
+  `EMAIL_PROVIDER` = `smtp` | `brevo` | `sendgrid` | `mailgun` | `disabled` (no default), plus
+  `EMAIL_FROM_ADDRESS`, `EMAIL_FROM_NAME` and the provider's variables (the MESSAGING block in the
+  template's `server/_env.example`; runbook §6). It needs the `@astram/messaging` package installed;
+  write no mail code. Outside `NODE_ENV=development|test` credentials must be `secret-ref:` values, so
+  a `SECRETS_PROVIDER` is required first; bad config fails boot naming the variable;
+  `MESSAGE_BOOT_PROBE=1` checks credentials at boot without sending. Your own `EmailSender`
+  (`send({ to, subject, html, text })`) still works. Either way every framework email (password
+  reset, invite, email-change confirmation, security notices) is bounded (`MESSAGE_SEND_TIMEOUT_MS`,
+  default 10 s, one retry on a temporary failure) and audited (`message.sent` / `message.failed`:
+  provider, purpose, masked recipient; never the link or body). Outside `NODE_ENV=development|test`,
+  `auth: true` without `emailSender` fails boot; `'disabled'` sends nothing and
+  `/auth/forgot-password` still answers 204. SMS and WhatsApp are ports only (`SmsProvider`,
+  `WhatsAppProvider` in `@astram/core`); no adapter yet, and `SMS_PROVIDER` / `WHATSAPP_PROVIDER`
+  accept only `disabled`.
+- **Administrator invite** (G-010): `POST /identity/users/:uuid/invite` (permission
+  `identity:user:invite`; wildcard `identity:*` / `identity:user:*` holders have it after the upgrade)
+  emails a one-time set-password link to a user whose sign-in is still pending. It is tenant-walled and
+  dominance-checked like update; 409 for a user who already set a password or has no credential, 429
+  over 3 per user or `INVITE_RATE_PER_ADMIN` per admin per hour, 501 with mail disabled and no link
+  return. `IdentityFeatureModule.forRoot({ invite: { returnLinkToAdmin: true } })` also returns the
+  link once. User reads carry a top-level `signInStatus` (`pending` | `active` | `none`). Frontend:
+  `identity.inviteUser(token, uuid)` (`@astram/frontend-core`); the scaffolded Users page has the
+  Invite button, and the reset page shows "Set your password" for `purpose=invite` links.
+- **Sign-in options** (ADR-0045; guard 0.20, identity 0.17, frontend-core 0.8). Each is OFF until
+  you turn it on; an upgrade without new options changes nothing on the wire except the logout fix
+  below. Write none of this yourself (Rule 6).
+
+  | Option | Default | What it does | Risk / note |
+  |--------|---------|--------------|-------------|
+  | `ShieldModule.forRoot({ signInWith: ['email', 'username'] })` | `['email']` | One field takes the email or the user's login name (`sonja`). `'email'` must stay in the list (boot fails otherwise). | Login names are global: an admin who hits "That sign-in name is already in use." learns the name exists somewhere (no tenant is named). |
+  | `captcha: 'env'` | off | Cloudflare Turnstile or Google reCAPTCHA (v3 score, v2 checkbox) on login, forgot-password and reset / set-password, from `CAPTCHA_*` env. Adaptive by default: a challenge after 3 failures for the account, the typed name or the IP. | Platform-wide only. Outside development/test `CAPTCHA_SECRET` must be a `secret-ref:` and `CAPTCHA_EXPECTED_HOSTNAMES` is required. `CAPTCHA_FAIL_MODE=open` lets sign-in through when the provider is down (audited, limits still apply); keep `closed` unless you accept that. The frontend build needs `VITE_CAPTCHA_PROVIDER` = the server's `CAPTCHA_PROVIDER` (CSP); a mismatch shows a "misconfigured" notice. |
+  | `logoutRequiresProof: true` | `false` this release; `true` from the next guard major | `POST /auth/logout` ends a session only with proof: its refresh token, or a bearer bound to it. | With `false`, an unproven logout (an old `{ sessionId }`-only frontend) still ends the session and is counted (`auth.logout.unproven`); anyone holding a leaked session id can end that session. The scaffolded app sets `true`. A custom frontend must send `{ sessionId, refreshToken }` + bearer first (`@astram/frontend-core` `logout(session)` does). |
+  | Mandatory 2FA (`/identity/security-policies`, identity wired) | no policies | Admins require 2FA for everyone in a company subtree, holders of a role, or holders of a permission key (`identity:*` allowed); grace 0–14 days, per user from when they become subject. Root can set a platform floor. | A required user without 2FA can only reach the enrolment pages (403 `mfa_enrollment_required`) until they enrol; during grace `/auth/me` carries `mfaEnrollmentDeadline`. Root accounts are bound only by floor policies. Takes effect on the user's next request. |
+
+  - **What counts as 2FA for a policy:** a confirmed **TOTP** authenticator only, in this release.
+    Recovery codes never count. Email codes, passkeys and SMS are not available as factors yet.
+  - Removing the last device while a policy applies answers 409 `mfa_required_by_policy`.
+  - `GET /auth/login-options` (public) returns `{ signInWith, captcha: { provider, siteKey, mode } | null }`
+    for the login page; a 401 with `captcha: 'required'` asks the page to show the widget.
+  - Sign-in events are audited by default when `IdentityFeatureModule` is loaded (`auth.login.*`,
+    `auth.logout`, `auth.mfa.*`, `auth.captcha.*`, `auth.handle.changed`; failed logins only for
+    real accounts, at most one row per lockout window). Your own `auditSink` still wins.
+  - Restricted sessions (recovery-code login or mandatory 2FA) get 403 on `POST /auth/scope-switch`,
+    and `GET /identity/auth-facts` answers `{ facts: [], restricted: 'reenroll' | 'mfa_enrollment' }`.
 - **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`.
@@ -148,6 +191,26 @@ imports: [
   active company; none when root creates it in the admin UI (a shared, root-only role). It cannot
   be changed by update. Deleting a company clears the owner of its roles. This round records
   ownership only: which roles an admin can see or administer is unchanged.
+- **Security policies (mandatory 2FA, ADR-0045).** `GET|POST /identity/security-policies`,
+  `GET|PUT|DELETE /identity/security-policies/:uuid` (permissions
+  `identity:security_policy:{read,create,update,delete}`; no access bundle carries them). Any holder
+  can create or tighten a policy for a company in their subtree; lowering or deleting a role or
+  permission policy needs the grant ceiling over what it covers, a company-wide policy needs all of
+  `identity:*` at that company or above; the platform floor is root-only. Every write is a
+  `permission_change` audit row and takes effect on the affected users' next request.
+- **Login names (G-014).** `loginName` on `POST /identity/users` and `PUT /identity/users/:uuid`
+  (`null` clears) (and optional `loginName` per
+  user in `bootstrap:org` files): `[a-z0-9._-]`, 3–64 characters, stored lower-case, never `@`.
+  Needs dominance over the user; audited `auth.handle.changed`; existing sessions stay. Users cannot
+  set or change their own (no `/account/*` route does).
+- **Admin sign-in controls.** `POST /identity/users/:uuid/{reset-mfa,unlock,end-sessions}`
+  (permissions `identity:user:{reset_mfa,unlock,end_sessions}`), body `{ code }` = the admin's OWN
+  current TOTP code; an admin without 2FA gets 409 `mfa_required`; needs dominance; not on yourself.
+  Reset-MFA deletes the user's devices and recovery codes and ends their sessions; unlock clears the
+  login, MFA, recovery and CAPTCHA counters; end-sessions revokes every session. All audited. User
+  reads carry `mfaStatus` (`enrolled` | `required` | `grace` | `not_required`), never device data.
+  Roles holding `identity:*` or `identity:user:*` gain these actions (and `security_policy`) on
+  upgrade; exact-key roles need a grant.
 
 ## Organisation bootstrap (`npm run bootstrap:org`, `@astram/identity` `runOrgBootstrap`, ADR-0042)
 - **What it does.** Creates your organisation from one JSON file at deploy time: platform roots,
@@ -182,9 +245,10 @@ imports: [
   another tenant is a `conflict` (roles are still global by name); an unowned role needs
   `--claim-unowned-roles`.
 - **What it does NOT do.** No deletes, renames, moves or revokes (differences are reported only);
-  it never activates an inactive membership or updates a changed email. No upload from the UI. No
-  administrator invite route or emailed link yet (G-010); department and branch admin routes are
-  separate too.
+  it never activates an inactive membership or updates a changed email. No upload from the UI.
+  Department and branch admin routes are separate. With `emailSender` configured, `--email-links`
+  emails each non-root set-password link instead of printing it; root links are never emailed and
+  follow the terminal-only print rule (it cannot be combined with `--links-to-stdout`).
 - **Existing apps** (scaffolded before this release) have no `bootstrap:org`. Upgrade
   `@astram/identity` and `@astram/guard` (`npm update @astram/identity @astram/guard`), copy
   `src/bootstrap-org.ts` and `src/bootstrap-org.args.ts` from a freshly scaffolded app (or from
@@ -464,6 +528,14 @@ upload(@Req() req: Record<string, unknown>) {
 - 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.
+- Sign-in options (frontend-core 0.8): `auth.loginOptions()`, `captchaToken` on `login` /
+  `requestReset` / `resetPassword` (a failure carries `captchaRequired`), `restrictionReasonOf(body)`,
+  `logout(session)` sends the proof, `createSecurityPolicyService(http)`, and
+  `identity.{resetUserMfa,unlockUser,endUserSessions}(token, uuid, code)`. The scaffolded frontend
+  has the login label from `signInWith`, the CAPTCHA widget (`VITE_CAPTCHA_PROVIDER`,
+  `create-astram-app --captcha <provider>`), routing to 2FA setup on `mfa_enrollment_required`, a
+  grace banner, the Security page (policies), and Users-page 2FA status, sign-in name and admin
+  actions.
 
 ## Available, but NOT wired to a data path (do not assume they protect data yet)
 - **Envelope encryption / per-tenant DEKs** (`createEncryptionService`, `LocalKekCrypto`): the
@@ -481,9 +553,13 @@ upload(@Req() req: Record<string, unknown>) {
 - 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).
-- An administrator invite (admin-console route that emails a set-password link) and framework
-  email/SMS delivery adapters (framework item G-010). Today first sign-in links come from
-  `npm run bootstrap:org` only.
+- Second factors other than TOTP (email code, passkey/WebAuthn, SMS), passwordless email-code
+  sign-in, a per-tenant allowed-factor list, a user's own session list, security notification
+  emails, and a configurable password policy (mandatory 2FA by tenant, role or permission IS
+  provided, above).
+- SMS and WhatsApp delivery adapters, phone numbers on users, phone verification and SMS/WhatsApp
+  MFA (the ports exist in `@astram/core`; adapters come with a phone-number identity feature).
+- A durable outbox or queue for guaranteed delivery (sends are best-effort with one retry; re-issue
+  an invite), bounce or webhook processing, and admin-editable message templates.
 
 If you need one of these, STOP and flag it in `.astram/guide/gaps.md` (Rule 4).

package/FRAMEWORK_RULES.md

@@ -58,6 +58,16 @@ infrastructure, and they may not re-export it). The lint wall is a backstop, not
 sandbox: code that slips past it is still a Rule 2 violation. If you find yourself
 wanting a raw query, see Rule 4.
 
+**Shared reference data** (code lists, catalogues, units: the same rows for every
+tenant) is an object type declared `access: { plane, global: true }`, with no tenant
+field and no `readScope`. It is read-only through the engine for everyone; create and
+change its rows only in an app migration (idempotent, select-before-insert on the
+business key). Never fake shared data with a match-all `readScope`, and never put
+tenant data in a global type. A record policy on a global type applies only to callers
+whose active tenant is the policy's tenant (plus platform policies): it does not cascade
+down the company hierarchy, so a parent's deny does not hide the row from its child
+companies' users. To hide a row across a group, author the policy in each tenant.
+
 ## 3. Classify every route (deny-by-default)
 
 Every HTTP route is DENIED by the global enforcement guard unless you classify it:
@@ -117,6 +127,24 @@ contributes configuration through the seam (`rootIds` from config, an `emailSend
 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`.
 
+Sign-in options are configuration too, never app code (`CAPABILITIES.md`, "Sign-in options"):
+- **Username sign-in:** `signInWith: ['email', 'username']`. Do not look users up by name
+  yourself, and do not let users set their own login name; admins set it (`loginName` on the users
+  API) or `bootstrap:org` does.
+- **CAPTCHA:** `captcha: 'env'` plus the `CAPTCHA_*` variables and the same provider in
+  `VITE_CAPTCHA_PROVIDER`. Do not add your own CAPTCHA check, widget script origin or bot filter on
+  `/auth/*`; do not set `CAPTCHA_FAIL_MODE=open` without a recorded decision.
+- **Mandatory 2FA:** admins create policies through `/identity/security-policies` (the Security
+  page). Do not gate routes on "has 2FA" in app code or keep your own list of who must enrol. In
+  this release only a confirmed **TOTP** authenticator counts as 2FA for a policy; recovery codes
+  never do. Handle 403 `mfa_enrollment_required` like `reenrollment_required`: send the user to the
+  2FA setup page.
+- **Logout:** call `logout(session)` from `@astram/frontend-core` (it sends the refresh token and
+  bearer as proof) and set `logoutRequiresProof: true` once your frontend does. Never end a
+  session by id alone.
+- **Unlock, reset 2FA, end sessions:** use the users API actions (`reset-mfa`, `unlock`,
+  `end-sessions`); never clear limiter keys or delete MFA rows yourself.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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",
@@ -19,5 +19,10 @@
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ASTRAM-2-0/astram-framework.git",
+    "directory": "packages/guide"
   }
 }