create-astram-app 0.9.8 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.9.8",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/README.md

@@ -59,7 +59,7 @@ wiring:
 import { ShieldModule } from '@astram/guard';
 
 @Module({
-  imports: [ShieldModule.forRoot()],          // framework owns enforcement
+  imports: [ShieldModule.forRoot()], // framework owns enforcement
   controllers: [HealthController, DemoController],
 })
 export class AppModule {}
@@ -80,7 +80,15 @@ the credential store, MFA, session handling and the decision authority; you writ
 ### Before you deploy with auth on
 
 - Pass an `emailSender` (or `'disabled'`): outside `NODE_ENV=development|test` boot fails
-  without one. Set `NODE_ENV=production` explicitly; `npm start` does not set it.
+  without one. Set `NODE_ENV=production` explicitly; `npm start` does not set it. The easiest is
+  `emailSender: 'env'`: the provider (SMTP, Brevo, SendGrid or Mailgun) comes from `EMAIL_PROVIDER`
+  and the MESSAGING block in `server/_env.example`, with no mail code in the app. It needs
+  `@astram/messaging` installed (the template already lists it) and, outside development, a
+  `SECRETS_PROVIDER` for the credentials. Every framework email is then bounded and audited, and
+  admins can invite pending users from the Users page.
+- Keep the framework pins in `server/package.json` exact (`@astram/core`, `engine`, `guard`,
+  `identity`, `migrate`): the packages pin each other exactly, and a `^` range can install a
+  second `@astram/core`. `npm ls @astram/core` must show one copy.
 - Set `RESET_LINK_BASE_URL` and `EMAIL_CHANGE_LINK_BASE_URL` to your public reset-password and
   confirm-email pages: with an `emailSender`, production boot fails when either is unset or
   points at localhost.
@@ -100,7 +108,7 @@ The full list, and how to upgrade an app scaffolded with an earlier version, is
 2. Register it in `server/src/app.module.ts` (add the module to `imports`, or its
    controller to `controllers`).
 3. **Classify every route:** `@Public()` for open routes, `@Classified({ typeKey,
-   action })` for guarded ones. Anything unclassified is denied by design (403; with
+action })` for guarded ones. Anything unclassified is denied by design (403; with
    `IdentityFeatureModule` wired, the app refuses to boot).
 4. **Data access goes through the framework's RecordEngine** — never a raw DB pool.
    The `server/eslint.config.mjs` wall fails lint on off-road DB access anywhere in
@@ -114,6 +122,45 @@ The full list, and how to upgrade an app scaffolded with an earlier version, is
 
 `server/src/features/` starts empty — it's your space.
 
+## Bootstrap your organisation
+
+`npm run bootstrap:org` (in `server/`) creates your organisation (tenants, companies,
+departments, branches, roles, users and grants) from one JSON file, through the framework's
+own services against your `AppModule`. It needs auth on and `IdentityFeatureModule` wired in
+`server/src/app.module.ts` (see its header), a built app (`npm run build`) and the migrations
+applied. Without the module it exits non-zero with "wire IdentityFeatureModule in AppModule
+before running bootstrap:org". The file format is in the framework capabilities synced into
+`.claude/rules/astram-framework-capabilities.md` (section "Organisation bootstrap").
+
+```bash
+cd server
+npm run build
+# Dry run: prints the plan, writes nothing.
+npm run bootstrap:org -- --file ../deploy/org.json
+# Apply (needs ASTRAM_BOOTSTRAP_OPERATOR; safe to re-run, it converges).
+ASTRAM_BOOTSTRAP_OPERATOR=jane.doe npm run bootstrap:org -- --file ../deploy/org.json --apply
+```
+
+- Flags: `--apply`, `--claim-unowned-roles`, `--reissue-links`, `--link-ttl-hours <n>`,
+  `--links-to-stdout`, `--email-links`, `--interactive` (prompt for root passwords without echo).
+- Every non-root user gets a one-time set-password link, printed once, only to a terminal
+  (pass `--links-to-stdout` to print them to a pipe). Links are never logged or written to a file.
+  With `emailSender` configured, `--email-links` emails each link to its user instead. Root
+  users' links are never emailed (a root link is a platform takeover): they are printed to a
+  terminal as before, or reported as not delivered.
+- Root passwords come from `ASTRAM_BOOTSTRAP_ROOT_PASSWORD_<USERNAME>` (a `secret-ref:` outside
+  development) or `--interactive`. Put the printed root uuids in `SHIELD_ROOT_IDS` and pass
+  `rootIdsFromEnv()` to both `forRoot` calls (see `server/_env.example`).
+
+### Existing apps
+
+An app scaffolded before this release has no `bootstrap:org`. To add it: 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 frontend
 
 With `--with-frontend` (or `npx -p create-astram-app astram-add-frontend` from this

package/template/frontend/src/auth/resetWording.js

@@ -0,0 +1,28 @@
+// resetWording.js — the reset page's words (G-010 R11, AC-15). An invite link carries
+// `purpose=invite`; it opens the same page and posts the same token to the same
+// `POST /auth/reset-password`, so the marker changes wording only and grants nothing.
+
+const RESET = Object.freeze({
+  isInvite: false,
+  title: 'Choose a new password',
+  subtitle: 'Enter a new password for your account.',
+  submit: 'Reset password',
+  success: 'Your password has been reset. Please sign in with your new password.',
+  deadLink: 'Request a new reset link',
+});
+
+const INVITE = Object.freeze({
+  isInvite: true,
+  title: 'Set your password',
+  subtitle: 'Choose a password to finish setting up your account.',
+  submit: 'Set password',
+  success: 'Your password is set. Please sign in.',
+  deadLink: 'Ask your administrator for a new invite',
+});
+
+/**
+ * @param {string | null | undefined} purpose the link's `purpose` query value
+ */
+export function resetWording(purpose) {
+  return purpose === 'invite' ? INVITE : RESET;
+}

package/template/frontend/src/auth/resetWording.test.mjs

@@ -0,0 +1,35 @@
+// resetWording.test.mjs — G-010 AC-15: an invite link (`purpose=invite`) opens the same reset
+// page with "Set your password" wording; any other link keeps the reset wording. The marker only
+// changes words: the page posts the same token to the same route either way.
+//
+//   node --test src/auth/resetWording.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { resetWording } from './resetWording.js';
+
+describe('resetWording', () => {
+  test('purpose=invite → set-password wording', () => {
+    const w = resetWording('invite');
+    assert.equal(w.isInvite, true);
+    assert.equal(w.title, 'Set your password');
+    assert.equal(w.subtitle, 'Choose a password to finish setting up your account.');
+    assert.equal(w.submit, 'Set password');
+    assert.equal(w.success, 'Your password is set. Please sign in.');
+    assert.equal(w.deadLink, 'Ask your administrator for a new invite');
+  });
+
+  test('anything else → today’s reset wording', () => {
+    for (const purpose of [null, undefined, '', 'reset', 'INVITE', 'invite ']) {
+      const w = resetWording(purpose);
+      assert.equal(w.isInvite, false);
+      assert.equal(w.title, 'Choose a new password');
+      assert.equal(w.subtitle, 'Enter a new password for your account.');
+      assert.equal(w.submit, 'Reset password');
+      assert.equal(
+        w.success,
+        'Your password has been reset. Please sign in with your new password.',
+      );
+      assert.equal(w.deadLink, 'Request a new reset link');
+    }
+  });
+});

package/template/frontend/src/pages/ResetPassword.jsx

@@ -18,6 +18,7 @@ import { Label } from '@/components/ui/label';
 import { Card, CardContent } from '@/components/ui/card';
 import ThemeToggle from '@/theme/ThemeToggle';
 import { branding } from '@/config/branding';
+import { resetWording } from '@/auth/resetWording';
 
 const MIN_PASSWORD_LEN = 8;
 
@@ -26,6 +27,8 @@ export default function ResetPassword() {
   const navigate = useNavigate();
   const [params] = useSearchParams();
   const token = params.get('token') ?? '';
+  // G-010: invite links carry `purpose=invite` (wording only; the same token, the same route).
+  const words = resetWording(params.get('purpose'));
 
   const [next, setNext] = useState('');
   const [confirm, setConfirm] = useState('');
@@ -59,7 +62,7 @@ export default function ResetPassword() {
     setBusy(false);
 
     if (r.ok) {
-      toast.success('Your password has been reset. Please sign in with your new password.');
+      toast.success(words.success);
       navigate('/login', { replace: true });
       return;
     }
@@ -89,10 +92,8 @@ export default function ResetPassword() {
               className="hidden h-9 w-auto dark:block"
             />
             <div className="text-center">
-              <h1 className="text-xl font-bold tracking-tight">Choose a new password</h1>
-              <p className="mt-1 text-sm text-muted-foreground">
-                Enter a new password for your account.
-              </p>
+              <h1 className="text-xl font-bold tracking-tight">{words.title}</h1>
+              <p className="mt-1 text-sm text-muted-foreground">{words.subtitle}</p>
             </div>
           </div>
 
@@ -105,12 +106,16 @@ export default function ResetPassword() {
 
           {linkDead ? (
             <div className="text-center">
-              <Link
-                to="/forgot-password"
-                className="inline-flex items-center gap-1.5 text-sm font-medium text-primary hover:underline"
-              >
-                Request a new reset link
-              </Link>
+              {words.isInvite ? (
+                <p className="text-sm text-muted-foreground">{words.deadLink}</p>
+              ) : (
+                <Link
+                  to="/forgot-password"
+                  className="inline-flex items-center gap-1.5 text-sm font-medium text-primary hover:underline"
+                >
+                  {words.deadLink}
+                </Link>
+              )}
             </div>
           ) : (
             <form onSubmit={onSubmit} className="space-y-4" noValidate>
@@ -143,7 +148,7 @@ export default function ResetPassword() {
                 ) : (
                   <>
                     <KeyRound className="size-4" />
-                    Reset password
+                    {words.submit}
                   </>
                 )}
               </Button>

package/template/frontend/src/pages/users/UsersPage.jsx

@@ -8,18 +8,24 @@
  * The user EDIT page (/users/edit/:uuid) is where the Assignments (membership + posting)
  * editor will live in Phase 5 — UserForm leaves a clear placeholder for it.
  *
+ * Invite (G-010): a "Sign-in" column shows whether each user has set a password yet
+ * (`row.signInStatus`, computed server-side), with an Invite button for pending users when the
+ * caller holds identity:user:invite (`inviteAction.js`; UX only, the server decides).
+ *
  * ⛔ No raw UUIDs: columns render username/email/status; `row.id` is a key/route param only.
  */
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
-import { Users } from 'lucide-react';
+import { Send, Users } from 'lucide-react';
 import { toast } from 'sonner';
-import { useAuth } from '@/auth/AuthContext';
+import { useAuth, useCan } from '@/auth/AuthContext';
 import AppShell from '@/shell/AppShell';
 import PageHeader from '@/components/PageHeader';
 import EntityList, { EntityListControls, EntityListPager } from '@/components/EntityList';
 import ConfirmDialog from '@/components/ConfirmDialog';
 import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { INVITE_PERMISSION, canInvite, inviteOutcome } from './inviteAction';
 
 /** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
 function formatDate(v) {
@@ -35,6 +41,38 @@ function formatDate(v) {
   }
 }
 
+/** Sign-in status badge text (server-computed `signInStatus`). */
+const SIGN_IN_LABEL = { pending: 'Pending', active: 'Active', none: 'No sign-in' };
+
+/** The Sign-in column: status badge + Invite for pending users (G-010). Not sortable. */
+function signInColumn(holdsInvite, invitingId, onInvite) {
+  return {
+    key: 'signInStatus',
+    label: 'Sign-in',
+    sortable: false,
+    render: (row) => (
+      <div className="flex items-center gap-2">
+        <Badge variant={row.signInStatus === 'active' ? 'success' : 'secondary'}>
+          {SIGN_IN_LABEL[row.signInStatus] ?? '—'}
+        </Badge>
+        {canInvite(row, holdsInvite) && (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            disabled={invitingId === row.id}
+            onClick={() => onInvite(row)}
+            aria-label={`Invite ${row.fields?.username || 'this user'}`}
+          >
+            <Send className="size-4" />
+            Invite
+          </Button>
+        )}
+      </div>
+    ),
+  };
+}
+
 // Sortable columns (server-side): Username, Email, Status, Created.
 const COLUMNS = [
   {
@@ -121,6 +159,9 @@ export default function UsersPage() {
     setSearchParams(p, { replace: true });
   }, [query, setSearchParams]);
 
+  const holdsInvite = useCan(INVITE_PERMISSION);
+  const [invitingId, setInvitingId] = useState(null);
+
   const [deleteTarget, setDeleteTarget] = useState(null);
   const [deleteBusy, setDeleteBusy] = useState(false);
 
@@ -152,6 +193,40 @@ export default function UsersPage() {
   const onPageChange = useCallback((page) => setQuery((q) => ({ ...q, page })), []);
   const onLimitChange = useCallback((limit) => setQuery((q) => ({ ...q, limit, page: 1 })), []);
 
+  const onInvite = useCallback(
+    async (row) => {
+      if (!token || invitingId) return;
+      setInvitingId(row.id);
+      const outcome = inviteOutcome(await identity.inviteUser(token, row.id));
+      setInvitingId(null);
+      if (outcome.kind === 'error') {
+        toast.error(outcome.text);
+        return;
+      }
+      if (outcome.link) {
+        // The one-time link is shown nowhere else: copy it, or show it once if the copy fails.
+        try {
+          await navigator.clipboard.writeText(outcome.link);
+          toast.success(outcome.text);
+        } catch {
+          toast.success(outcome.text.replace('Link copied', 'Copy this link now'), {
+            description: outcome.link,
+            duration: 60_000,
+          });
+        }
+      } else {
+        toast.success(outcome.text);
+      }
+    },
+    [identity, token, invitingId],
+  );
+
+  const columns = useMemo(() => {
+    const out = [...COLUMNS];
+    out.splice(3, 0, signInColumn(holdsInvite, invitingId, onInvite));
+    return out;
+  }, [holdsInvite, invitingId, onInvite]);
+
   const onConfirmDelete = async () => {
     if (!deleteTarget) return;
     setDeleteBusy(true);
@@ -185,7 +260,7 @@ export default function UsersPage() {
         />
 
         <EntityList
-          columns={COLUMNS}
+          columns={columns}
           rows={rows}
           search={query.search}
           sortBy={query.sortBy}

package/template/frontend/src/pages/users/inviteAction.js

@@ -0,0 +1,37 @@
+// inviteAction.js — the Users page's Invite action (G-010 R13, AC-16). Pure logic, tested by
+// inviteAction.test.mjs; UsersPage renders from it. Showing or hiding the action is UX only: the
+// server decides (`POST /identity/users/:uuid/invite` needs identity:user:invite, the tenant wall
+// and the dominance ceiling).
+
+/** The permission key the invite route is gated on. */
+export const INVITE_PERMISSION = 'identity:user:invite';
+
+/**
+ * Show Invite for this row? Only for users whose sign-in is still pending (created or invited,
+ * no password yet) and only when the caller holds {@link INVITE_PERMISSION}.
+ * @param {{ signInStatus?: string } | null | undefined} row
+ * @param {boolean} holdsInvite
+ */
+export function canInvite(row, holdsInvite) {
+  return Boolean(holdsInvite && row && row.signInStatus === 'pending');
+}
+
+/**
+ * The toast for an `identity.inviteUser` result. A returned one-time link (only when the app opted
+ * in to `returnLinkToAdmin`) is handed back for the page to copy to the clipboard.
+ * @param {{ ok: boolean, emailed?: boolean, link?: string, error?: string }} result
+ * @returns {{ kind: 'success' | 'error', text: string, link?: string }}
+ */
+export function inviteOutcome(result) {
+  if (!result || !result.ok) {
+    return { kind: 'error', text: (result && result.error) || 'Could not invite the user.' };
+  }
+  if (result.link) {
+    return {
+      kind: 'success',
+      text: result.emailed ? 'Invite sent · Link copied' : 'Link copied',
+      link: result.link,
+    };
+  }
+  return { kind: 'success', text: 'Invite sent' };
+}

package/template/frontend/src/pages/users/inviteAction.test.mjs

@@ -0,0 +1,63 @@
+// inviteAction.test.mjs — G-010 AC-16: the Users page shows Invite only for users whose sign-in
+// is still pending, and only to callers holding identity:user:invite (UX only; the server decides).
+//
+//   node --test src/pages/users/inviteAction.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { INVITE_PERMISSION, canInvite, inviteOutcome } from './inviteAction.js';
+
+describe('canInvite', () => {
+  test('the permission key is identity:user:invite', () => {
+    assert.equal(INVITE_PERMISSION, 'identity:user:invite');
+  });
+
+  test('pending users, for a caller who holds the key', () => {
+    assert.equal(canInvite({ id: 'u1', signInStatus: 'pending' }, true), true);
+  });
+
+  test('never for active users, users with no credential, or unknown status', () => {
+    for (const signInStatus of ['active', 'none', undefined, 'PENDING']) {
+      assert.equal(canInvite({ id: 'u1', signInStatus }, true), false);
+    }
+  });
+
+  test('never without the permission, or without a row', () => {
+    assert.equal(canInvite({ id: 'u1', signInStatus: 'pending' }, false), false);
+    assert.equal(canInvite(null, true), false);
+  });
+});
+
+describe('inviteOutcome', () => {
+  test('emailed → "Invite sent"', () => {
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: true }), {
+      kind: 'success',
+      text: 'Invite sent',
+    });
+  });
+
+  test('a returned link → copy it, "Link copied"; emailed too → both', () => {
+    const link = 'https://app.example/reset-password?token=t&purpose=invite';
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: false, link }), {
+      kind: 'success',
+      text: 'Link copied',
+      link,
+    });
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: true, link }), {
+      kind: 'success',
+      text: 'Invite sent · Link copied',
+      link,
+    });
+  });
+
+  test('failures show the service message (409 reasons included)', () => {
+    const reason = 'This user has already set a password. Use forgot-password instead.';
+    assert.deepEqual(inviteOutcome({ ok: false, status: 409, error: reason }), {
+      kind: 'error',
+      text: reason,
+    });
+    assert.deepEqual(inviteOutcome({ ok: false, status: 500, error: '' }), {
+      kind: 'error',
+      text: 'Could not invite the user.',
+    });
+  });
+});

package/template/server/_env.example

@@ -135,6 +135,54 @@ NODE_ENV=development
 # Upload size cap in bytes (default 10 MiB; above the 50 MiB ceiling fails boot).
 # OBJECT_STORAGE_MAX_BYTES=10485760
 
+# --- OPTIONAL: MESSAGING — email delivery (G-010) ---
+# Read only when src/app.module.ts passes ShieldModule.forRoot({ auth: true, emailSender: 'env' })
+# (install @astram/messaging). Password resets, admin invites, email-change confirmation and
+# security notices go out through this provider; every send is bounded and audited.
+# One of smtp | brevo | sendgrid | mailgun | disabled (no default: unset fails boot).
+# EMAIL_PROVIDER=brevo
+# EMAIL_FROM_ADDRESS=no-reply@example.com
+# EMAIL_FROM_NAME=Example
+# Provider credentials: outside development/test they MUST be `secret-ref:` references, which
+# needs SECRETS_PROVIDER configured (above). A literal value fails boot.
+# BREVO_API_KEY=secret-ref:mail/brevo-api-key
+# SENDGRID_API_KEY=secret-ref:mail/sendgrid-api-key
+# MAILGUN_API_KEY=secret-ref:mail/mailgun-api-key
+# MAILGUN_DOMAIN=mg.example.com
+# MAILGUN_REGION=us
+# Optional https base for an HTTP provider (a relay or test stub); http is refused.
+# EMAIL_API_BASE_URL=
+# SMTP: TLS is starttls (default, port 587) or implicit (465); none only to a loopback host
+# outside development/test. Certificates are always verified; SMTP_TLS_CA adds a private CA.
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_TLS=starttls
+# SMTP_USER=mailer
+# SMTP_PASSWORD=secret-ref:mail/smtp-password
+# SMTP_TLS_CA=/etc/ssl/private-ca.pem
+# Per-send bound in ms (default 10000, max 30000; one retry on a temporary failure inside it).
+# MESSAGE_SEND_TIMEOUT_MS=10000
+# 1 = check reachability and credentials at boot without sending (a failure refuses boot).
+# MESSAGE_BOOT_PROBE=1
+# SMS and WhatsApp: ports only this release; anything but `disabled` fails boot.
+# SMS_PROVIDER=disabled
+# WHATSAPP_PROVIDER=disabled
+# Admin invites (POST /identity/users/:uuid/invite): link lifetime in hours (1-168, default 72)
+# and invites per admin per hour (default 30).
+# INVITE_LINK_TTL_HOURS=72
+# INVITE_RATE_PER_ADMIN=30
+
+# --- OPTIONAL: organisation bootstrap (`npm run bootstrap:org`; needs IdentityFeatureModule wired) ---
+# Platform-root user uuids, comma-separated, lower-case canonical form. Read by rootIdsFromEnv()
+# in src/app.module.ts (pass it to BOTH forRoot calls); bootstrap:org prints the uuid of each root.
+# SHIELD_ROOT_IDS=
+# Who is running the bootstrap (audit "on behalf of"). Required with --apply.
+# ASTRAM_BOOTSTRAP_OPERATOR=jane.doe
+# Password of each root user declared in the org file, one variable per username (upper-cased).
+# Outside development/test it must be a `secret-ref:` reference (a literal fails the run);
+# or pass --interactive to be prompted without echo.
+# ASTRAM_BOOTSTRAP_ROOT_PASSWORD_ADMIN=secret-ref:bootstrap/root-password-admin
+
 # --- Migrations (optional; @astram/identity's migrations run automatically) ---
 # APP_MIGRATION_DIR=migrations         # your app's own migrations, run after identity's
 # APP_MIGRATION_TABLE=schema_migrations

package/template/server/package.json

@@ -9,6 +9,7 @@
     "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc -p tsconfig.build.json",
     "start": "node --env-file-if-exists=.env dist/main.js",
+    "bootstrap:org": "node --env-file-if-exists=.env dist/bootstrap-org.js",
     "dev": "node scripts/dev.mjs",
     "test": "vitest run",
     "migration:run": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate",
@@ -20,12 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.8.0",
-    "@astram/engine": "^0.9.0",
-    "@astram/guard": "^0.16.0",
-    "@astram/guide": "^0.2.7",
-    "@astram/identity": "^0.13.0",
-    "@astram/migrate": "^0.6.0",
+    "@astram/core": "1.9.0",
+    "@astram/engine": "0.10.1",
+    "@astram/guard": "0.18.0",
+    "@astram/guide": "^0.2.8",
+    "@astram/identity": "0.15.0",
+    "@astram/messaging": "^0.1.1",
+    "@astram/migrate": "0.6.1",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

package/template/server/src/app.module.ts

@@ -39,7 +39,14 @@ import { DemoController } from './health/demo.controller';
  *   4. Outside development/test (`NODE_ENV`), `auth: true` also requires an
  *      `emailSender` (or `emailSender: 'disabled'`) — otherwise boot fails closed —
  *      and, with a sender, public `RESET_LINK_BASE_URL` / `EMAIL_CHANGE_LINK_BASE_URL`
- *      (not localhost; see `.env.example`).
+ *      (not localhost; see `.env.example`). The simplest sender is configuration only:
+ *      `ShieldModule.forRoot({ auth: true, emailSender: 'env' })` with `EMAIL_PROVIDER`
+ *      (smtp | brevo | sendgrid | mailgun | disabled), `EMAIL_FROM_ADDRESS` and the
+ *      provider's variables (MESSAGING block in `.env.example`; credentials must be
+ *      `secret-ref:` values outside development/test, so set up `SECRETS_PROVIDER` first).
+ *      Admins can then invite users (`POST /identity/users/:uuid/invite`, the Users page
+ *      Invite button); `IdentityFeatureModule.forRoot({ invite: { returnLinkToAdmin: true } })`
+ *      also shows the one-time link to the admin once.
  * You then get framework-owned `POST /auth/{login,mfa,refresh,logout}` for free —
  * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
  * boot; turning it on requires the config above, by design — fail-closed.)
@@ -52,13 +59,18 @@ import { DemoController } from './health/demo.controller';
  * identity → guard), so the consumer wires it (ADR-0026):
  *   1. Turn auth on (above), pass the identity permission keys (so the frontend admin
  *      nav lights up), and import the identity module:
+ *        import { rootIdsFromEnv, ShieldModule } from '@astram/guard';
  *        import { identityAuthActionKeys, identityControlPlaneKeys,
  *                 IdentityFeatureModule } from '@astram/identity';
  *        imports: [
- *          ShieldModule.forRoot({ auth: true,
+ *          ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(),
  *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys }),
- *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles,…}
+ *          // mounts /identity/{companies,users,roles,…}
+ *          IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() }),
  *        ],
+ *   `rootIdsFromEnv()` reads `SHIELD_ROOT_IDS` (comma-separated platform-root user uuids; unset
+ *   means no roots), so both calls get the same list. `npm run bootstrap:org` creates your
+ *   organisation from a file and needs `IdentityFeatureModule` wired (see the README).
  *   `IdentityFeatureModule.forRoot()` self-wires the engine from your `APP_DB_*` env
  *   (no separate engine setup) and builds the record authorization `ShieldModule` decides
  *   with, so the guard renders REAL decisions from your roles' grants. Do NOT also pass
@@ -89,8 +101,9 @@ import { DemoController } from './health/demo.controller';
   // admin console (incl. the guided rule-builder + owner shares), use (see the OPTIONAL
   // blocks above for the full form + the extraObjects note for your OWN owned types):
   //   imports: [
-  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys }),
-  //     IdentityFeatureModule.forRoot({ /* extraObjects: [YourType] */ }),
+  //     ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(), identityActionKeys,
+  //       identityControlPlaneKeys }),
+  //     IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() /*, extraObjects: [YourType] */ }),
   //   ],
   imports: [ShieldModule.forRoot()],
   controllers: [HealthController, DemoController],

package/template/server/src/bootstrap-org.args.ts

@@ -0,0 +1,96 @@
+/**
+ * Command-line flags of `npm run bootstrap:org` (see `bootstrap-org.ts`).
+ *
+ * A pure module (no framework imports) so the flag parser is unit-testable. Unknown flags
+ * and stray arguments are refused: a typo such as `--aply` must never silently fall back
+ * to a dry run, and error text never echoes the offending value (it could be a secret).
+ */
+export interface BootstrapArgs {
+  /** Path of the org JSON file. */
+  file: string;
+  /** Write. Without it the run is a dry run. */
+  apply: boolean;
+  claimUnownedRoles: boolean;
+  reissueLinks: boolean;
+  /** Link lifetime in whole hours; the runner validates the range. */
+  linkTtlHours: number | undefined;
+  linksToStdout: boolean;
+  /** Email the set-password links (needs a configured emailSender) instead of printing them. */
+  emailLinks: boolean;
+  /** Prompt for the root passwords (no echo) instead of reading the environment. */
+  interactive: boolean;
+}
+
+export class BootstrapArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BootstrapArgsError';
+  }
+}
+
+export const BOOTSTRAP_USAGE =
+  'usage: npm run bootstrap:org -- --file <path> [--apply] [--claim-unowned-roles] ' +
+  '[--reissue-links] [--link-ttl-hours <n>] [--links-to-stdout | --email-links] [--interactive]';
+
+export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
+  const args: BootstrapArgs = {
+    file: '',
+    apply: false,
+    claimUnownedRoles: false,
+    reissueLinks: false,
+    linkTtlHours: undefined,
+    linksToStdout: false,
+    emailLinks: false,
+    interactive: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i] as string;
+    switch (flag) {
+      case '--file': {
+        const value = argv[i + 1];
+        if (value === undefined || value === '' || value.startsWith('--')) {
+          throw new BootstrapArgsError('--file needs a path');
+        }
+        args.file = value;
+        i += 1;
+        break;
+      }
+      case '--apply':
+        args.apply = true;
+        break;
+      case '--claim-unowned-roles':
+        args.claimUnownedRoles = true;
+        break;
+      case '--reissue-links':
+        args.reissueLinks = true;
+        break;
+      case '--links-to-stdout':
+        args.linksToStdout = true;
+        break;
+      case '--email-links':
+        args.emailLinks = true;
+        break;
+      case '--interactive':
+        args.interactive = true;
+        break;
+      case '--link-ttl-hours': {
+        const value = argv[i + 1];
+        if (value === undefined || !/^\d+$/.test(value)) {
+          throw new BootstrapArgsError('--link-ttl-hours needs a whole number of hours');
+        }
+        args.linkTtlHours = Number(value);
+        i += 1;
+        break;
+      }
+      default:
+        throw new BootstrapArgsError(
+          flag.startsWith('--') ? 'unknown option' : 'unexpected argument',
+        );
+    }
+  }
+  if (args.file === '') throw new BootstrapArgsError('--file <path> is required');
+  if (args.emailLinks && args.linksToStdout) {
+    throw new BootstrapArgsError('--email-links cannot be combined with --links-to-stdout');
+  }
+  return args;
+}

package/template/server/src/bootstrap-org.ts

@@ -0,0 +1,132 @@
+import 'reflect-metadata';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { NestFactory } from '@nestjs/core';
+import { resolveBootSecrets } from '@astram/guard';
+import { OrgBootstrapError, runOrgBootstrap } from '@astram/identity';
+import {
+  BOOTSTRAP_USAGE,
+  BootstrapArgsError,
+  parseBootstrapArgs,
+  type BootstrapArgs,
+} from './bootstrap-org.args';
+
+/**
+ * `npm run bootstrap:org -- --file org.json [--apply] [--email-links]`: creates your organisation (tenants,
+ * companies, roles, users, grants) from a declarative file, through the framework's own
+ * services, against THIS app's `AppModule` (so grants can name your own object types).
+ * Without `--apply` it is a dry run that prints the plan and writes nothing.
+ * Set-password links print to the terminal; with `--email-links` (needs an `emailSender` in
+ * `ShieldModule.forRoot`) each one is emailed instead and none is printed, except ROOT links:
+ * those are never emailed and print only to a terminal (or with `--links-to-stdout`).
+ *
+ * No security logic lives here: `runOrgBootstrap` (from `@astram/identity`) does the work.
+ * Same boot order as `main.ts`: `resolveBootSecrets()` runs BEFORE `AppModule` is loaded,
+ * so `AppModule` is imported dynamically. Exit code 0 on success, non-zero otherwise.
+ *
+ * Needs `IdentityFeatureModule` wired in `AppModule` (see the header of `app.module.ts`).
+ */
+
+/** Prompt without echo (TTY only): the typed characters never reach the terminal. */
+async function promptHidden(question: string): Promise<string> {
+  let muted = false;
+  const output = new Writable({
+    write(chunk, _encoding, done) {
+      if (!muted) process.stdout.write(chunk);
+      done();
+    },
+  });
+  const rl = createInterface({ input: process.stdin, output, terminal: true });
+  return new Promise<string>((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      process.stdout.write('\n');
+      resolve(answer);
+    });
+    muted = true;
+  });
+}
+
+async function run(args: BootstrapArgs): Promise<number> {
+  if (args.interactive && !process.stdin.isTTY) {
+    console.error('--interactive needs a terminal');
+    return 1;
+  }
+  await resolveBootSecrets();
+  const { AppModule } = await import('./app.module');
+  // Warn level only: the Nest boot chatter is noise, and nothing here may log a secret.
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['warn', 'error'],
+  });
+  try {
+    const report = await runOrgBootstrap(app, {
+      file: args.file,
+      apply: args.apply,
+      claimUnownedRoles: args.claimUnownedRoles,
+      reissueLinks: args.reissueLinks,
+      ...(args.linkTtlHours !== undefined ? { linkTtlHours: args.linkTtlHours } : {}),
+      linksToStdout: args.linksToStdout,
+      emailLinks: args.emailLinks,
+      ...(process.env.ASTRAM_BOOTSTRAP_OPERATOR !== undefined
+        ? { operator: process.env.ASTRAM_BOOTSTRAP_OPERATOR }
+        : {}),
+      isTTY: process.stdout.isTTY === true,
+      out: console.log,
+      ...(args.interactive
+        ? {
+            promptRootPassword: (username: string) =>
+              promptHidden(`Password for root "${username}": `),
+          }
+        : {}),
+    });
+    // Counts only: links and passwords were already shown through `out`, never repeated.
+    console.log(
+      `${report.applied ? 'applied' : 'dry run (nothing written; pass --apply to write)'}: ` +
+        `${report.plan.entries.length} planned, ${report.links} link(s) issued` +
+        (args.emailLinks
+          ? ` (${report.linksEmailed} emailed, ${report.linksPrintedRoots} root link(s) printed, ` +
+            `${report.linksNotEmailed} not delivered)`
+          : '') +
+        ', ' +
+        `${report.rootIds.length} root(s)`,
+    );
+    return 0;
+  } finally {
+    await app.close();
+  }
+}
+
+async function main(): Promise<void> {
+  let args: BootstrapArgs;
+  try {
+    args = parseBootstrapArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof BootstrapArgsError) {
+      console.error(`${err.message}\n${BOOTSTRAP_USAGE}`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+  try {
+    process.exitCode = await run(args);
+  } catch (err) {
+    process.exitCode = 1;
+    if (err instanceof OrgBootstrapError) {
+      // `--email-links` without a sender is also `not_wired`; its own message says what to set.
+      if (err.code === 'not_wired' && !err.message.startsWith('--email-links')) {
+        console.error(
+          'wire IdentityFeatureModule in AppModule before running bootstrap:org (see the header of src/app.module.ts)',
+        );
+      }
+      console.error(`bootstrap:org failed [${err.code}]: ${err.message}`);
+    } else {
+      // Generic on purpose: an unexpected error can carry values from the file or the database.
+      console.error(
+        'bootstrap:org failed: unexpected error (no details printed; see the app logs)',
+      );
+    }
+  }
+}
+
+void main();