@astram/guide 0.2.9 → 0.2.11

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`.
@@ -165,10 +187,43 @@ imports: [
   service is built without `IdentityFeatureModule.forRoot`) when no credential was made.
   Once your `EmailSender` works, `POST /auth/forgot-password` reaches the user. A user whose email
   is set later stays locked until the next `bootstrap:org` run gives them a credential.
-- **Role owner.** Every role records an owner company when it is created: a non-root admin's
-  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.
+- **Roles belong to one company** (G-013, ADR-0047). A role is assigned only in its own company
+  (postings and service accounts; 400 otherwise, root included), read and managed through the owner
+  wall (a parent company's admins manage their subsidiaries' roles; out of reach ⇒ 404), and its name
+  is unique within its company only (409 names the existing role). `GET|POST
+  /identity/companies/:companyUuid/roles`; `POST /identity/roles` creates the role in the caller's
+  active company (400 "Choose a company for the role." without one). Role routes need
+  `identity:company:read` (the `access-admin` bundle grants it). An ownerless role (seeded without
+  `r_owner_company_uuid`) is root-only and assignable nowhere.
+- **Departments and branches belong to one company** (G-012). `POST
+  /identity/companies/:companyUuid/departments` and `/branches` (`{ name }`), `PUT` (rename) and
+  `DELETE` on `/identity/departments/:uuid` and `/identity/branches/:uuid`; the list routes are walled
+  and return `{ rows: [{ uuid, name, usedBy? }], total, page, limit }` (`?page&limit&search`). Names
+  are unique per company ignoring case and accents (409); delete is refused (409) while any posting
+  uses the row; at most 1000 of each per company. Access bundle `org-structure`.
+- **The active membership is always `active`** (G-011): `PUT /identity/memberships/:uuid` refuses
+  activating a non-active membership or moving the active one off `active` (409), and a body that
+  sets `isActive: true` with another status (400).
+- **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,
@@ -191,7 +246,8 @@ imports: [
   `ASTRAM_BOOTSTRAP_OPERATOR`. Root passwords: `ASTRAM_BOOTSTRAP_ROOT_PASSWORD_<USERNAME>` (a
   `secret-ref:` outside development/test, so a `SECRETS_PROVIDER` is needed) or `--interactive`.
   Other flags: `--reissue-links`, `--link-ttl-hours <1..168>` (default 72), `--links-to-stdout`,
-  `--claim-unowned-roles`. Runs hold a database lock.
+  `--claim-unowned-roles` (a no-op notice since roles belong to one company). Runs hold a database
+  lock.
 - **First sign-in.** Non-root users get a locked credential and a one-time set-password link,
   printed once, to a terminal only (`--links-to-stdout` sends them to a pipe, where logs can keep
   them). The operator delivers each link; the user redeems it at the reset page. Outside
@@ -199,9 +255,11 @@ imports: [
 - **Roots.** The run prints each root's uuid and a `SHIELD_ROOT_IDS=…` line: set it and restart
   (`rootIdsFromEnv`, above).
 - **Re-runs and new tenants.** Additive and idempotent: a second `--apply` writes nothing. A file
-  covers only the tenants it declares, so onboard a new tenant with a new file. A role name owned by
-  another tenant is a `conflict` (roles are still global by name); an unowned role needs
-  `--claim-unowned-roles`.
+  covers only the tenants it declares, so onboard a new tenant with a new file. Roles, departments
+  and branches are created in the company that declares them, and the same name may exist in
+  another company. A posting must use a role declared on its own company (a role declared only on a
+  parent is a file error). After renaming a department or branch in the app, rename it in the file
+  too, or a re-run creates the old name again.
 - **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.
   Department and branch admin routes are separate. With `emailSender` configured, `--email-links`
@@ -279,6 +337,28 @@ imports: [
   (a Rule-4 STOP). Field types this version: `string`, `number`, `boolean`, `uuid`, `timestamp`,
   `json`.
 
+## Shared reference data: global types (ADR-0046; engine 0.11, guard 0.20)
+- **Declare** `@ObjectType({ ..., access: { plane, global: true } })` for rows every tenant reads the
+  same (code lists, catalogues, units). No tenant field, no `readScope`. Registration refuses
+  `global` with `tenantScoped`, `owned`, `system`, a `readScope`, a `trusted: 'tenantId'` field,
+  `crudActions: true` or any action other than `read`, naming the type.
+- **Reads** (list, get, `aggregate()`, search) carry no tenant clause, but the type's `read` grant
+  and deny policies still apply: a caller without `read` sees nothing. Root follows the plane:
+  `plane: 'data'` keeps root denied, `plane: 'control'` lets root read.
+- **Writes** through the engine (create, update, delete, `createMany`) are refused for everyone,
+  root included, before any SQL. Seed and change rows only in an app migration, idempotent and
+  select-before-insert on the business key.
+- **Policies do not cascade.** A record policy on a global type applies only to callers whose
+  active tenant is the policy's tenant, plus platform policies; a parent's deny does not reach its
+  child companies' users. To hide a row across a group, author the policy in each tenant or as a
+  platform policy.
+- **No sharing, no cross-tenant reach**: a global type is never `owned`, so never a share target.
+- **Tenant-less data types are now refused writes.** A `plane: 'data'` type with no tenant field,
+  no `readScope` and not global refuses non-root create, update, delete and `createMany`
+  (`AuthorizationDeniedError('tenantless_data_write_denied')`). Boot logs the global types once and
+  warns once per such type: make it global, give it a tenant field, or add a `readScope`.
+- Never fake shared data with a match-all `readScope`, and never put tenant data in a global type.
+
 ## Custom object actions (ADR-0038; engine 0.7, guard 0.14, identity 0.11)
 - **Declare domain verbs on the type**: `@ObjectType({ ..., actions: ['activate', 'review'] })`.
   The type's vocabulary is `read, create, update, delete` plus the declared actions, and each one
@@ -486,6 +566,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 +591,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.11",
   "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"
   }
 }