@astram/guide 0.2.7 → 0.2.9

package/CAPABILITIES.md

@@ -17,17 +17,17 @@ below is wired by the two `forRoot` calls in your `app.module.ts`; you write no
 ## Wiring (the ONE seam, plus the identity module)
 
 ```ts
-import { ShieldModule } from '@astram/guard';
+import { ShieldModule, rootIdsFromEnv } from '@astram/guard';
 import {
   IdentityFeatureModule, identityAuthActionKeys, identityControlPlaneKeys,
 } from '@astram/identity';
 
-const rootIds = ['<platform-admin user uuid>'];   // from config, never from a request
+const rootIds = rootIdsFromEnv(process.env);       // SHIELD_ROOT_IDS; never from a request
 
 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?`,
@@ -62,6 +62,10 @@ imports: [
   HERE ONLY: the module builds the record authorization from them and `ShieldModule` decides with
   it. Passing `recordAuthorization`/`decisionAuthority` to `ShieldModule` as well fails the boot.
   Without `rootIds` it logs a boot warning.
+- **`rootIdsFromEnv(env)`** (`@astram/guard`) reads `SHIELD_ROOT_IDS` (comma-separated user
+  uuids, lower-case canonical form). Any invalid or duplicate entry fails boot (the value is never
+  echoed); unset returns an empty list. `npm run bootstrap:org` prints the line to set. An app that
+  reads its own variable keeps working; root is never inferred from `u_is_platform_superuser`.
 - `ShieldModule.forRoot()` with no options and no identity module = enforcement only (no DB, no
   Redis, boots without `.env`); it binds a stub that denies every `@Classified` route.
 
@@ -102,9 +106,30 @@ imports: [
   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.
 - **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`.
@@ -131,7 +156,63 @@ imports: [
   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`.
+  (099/100) run only with `NODE_ENV=development` or `ASTRAM_SEED_DEV=1`. Anywhere else, create the
+  first users with `npm run bootstrap:org` (below).
+- **API-created users can be reached by reset.** `POST /identity/users` with an email and a
+  company creates the user, an active membership and a **locked** credential in one transaction
+  (no password works until the user sets one). The response is `{ id, credential: 'locked' }`, or
+  `{ id, credential: 'none', reason }` (`no_email`, `no_company`; `no_provisioner` only when the
+  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.
+
+## 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,
+  a company tree (tenants and `children`), departments and branches per company, roles with their
+  permission keys, and users with one active membership and their role postings. It runs against
+  your own `AppModule` (`NestFactory.createApplicationContext`), so keys of your `extraObjects` are
+  grantable. Every write goes through the framework's services and `decide()`, as the declared
+  operation `shield:org-bootstrap`; audit rows carry `operation`, `step` and `onBehalfOf` (the
+  operator). It needs auth on and `IdentityFeatureModule` wired; without the module it exits with
+  "wire IdentityFeatureModule in AppModule before running bootstrap:org".
+- **File.** `{ "version": 1, "roots": [{ username, email, homeCompany }], "tenants": [company] }`;
+  `company` = `{ name, departments?, branches?, roles?: [{ name, permissions }], users?:
+  [{ username, email, company?, postings?: [{ role, department?, branch? }] }], children? }`.
+  Unknown fields, unknown permission keys (allowed: catalog keys plus `<feature>:*` and
+  `<feature>:<type>:*`), duplicate usernames or emails and references to undeclared roles,
+  departments or branches are refused before any write. No password, uuid or secret in the file.
+  A user with no postings is allowed (signs in, holds nothing).
+- **Run.** `npm run bootstrap:org -- --file org.json` is a dry run (prints `create` / `unchanged` /
+  `drift` / `not-in-file` / `conflict`). Add `--apply` to write; it needs
+  `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.
+- **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
+  development/test `RESET_LINK_BASE_URL` must be set and not localhost.
+- **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`.
+- **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`
+  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
+  `create-astram-app/template/server/src/` in the framework repo) into `server/src/`, and add
+  `"bootstrap:org": "node --env-file-if-exists=.env dist/bootstrap-org.js"` to the `scripts` of
+  `server/package.json`. `npm run build` compiles both files; no other change is needed.
 
 ## The record pipe (`@astram/engine`)
 - **`RecordEngine`** (token `RECORD_ENGINE`) / `RecordsService` — create/get/update/delete/list,
@@ -423,5 +504,9 @@ upload(@Req() req: Record<string, unknown>) {
 - 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).
+- 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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",