@astram/guide 0.2.9 → 0.2.10

package/CAPABILITIES.md

@@ -100,8 +100,9 @@ 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
@@ -130,6 +131,27 @@ imports: [
   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`.
@@ -169,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,
@@ -486,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
@@ -503,7 +553,10 @@ 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).
+- 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

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.9",
+  "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"
   }
 }