@astram/guide 0.2.8 → 0.2.9

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?`,
@@ -106,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`.
@@ -182,9 +203,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
@@ -482,8 +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).
-- 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.
+- 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.8",
+  "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",