create-astram-app 0.7.0 → 0.9.0

package/README.md

@@ -64,9 +64,19 @@ my-app/
 └── README.md                  how to run + how to add features the framework way
 ```
 
-`server/` scripts: `dev`, `build`, `start`, `test`, `lint`, `migration:run`,
+`server/` scripts: `dev`, `build`, `start`, `test`, `lint`, `lint:wall`, `migration:run`,
 `migration:status`, `migration:revert`, `guide:sync`.
 
+The wall (`eslint.config.mjs`, plus the `lint:wall` grep for `/internal` and
+`node_modules/@astram` imports under `src/features`, run by `lint`) catches accidental use;
+deliberate bypass (`.call`/`.apply`, a computed `pool[m]()`, an aliased `require`) is a
+code-review matter.
+
+The wall also flags uuid-named route and body inputs (`id`, `uuid`, `…Id(s)`, `…Uuid(s)`) that are
+read without `UuidPipe` (`@Param('uuid', UuidPipe)`) or `uuidField` / `optionalUuidField` /
+`uuidArrayField` from `@astram/guard`. The database matches uuids ignoring case, trailing spaces and
+character width, so a raw one would slip past exact checks in your code.
+
 ## The frontend (`--with-frontend` / `astram-add-frontend`)
 
 A Vite + React + shadcn/ui app whose views you own and edit; the auth and API logic comes from
@@ -75,7 +85,14 @@ A Vite + React + shadcn/ui app whose views you own and edit; the auth and API lo
 
 - **Sign-in flows:** login, MFA challenge (TOTP or a recovery code), forced MFA re-enrolment
   after a recovery-code login, forgot password, reset password.
-- **Account:** profile, change password, two-factor devices and recovery codes.
+- **Account:** profile, change password, two-factor devices and recovery codes. Changing the
+  email asks for the current password (and an authenticator or recovery code when MFA is on);
+  the server mails a link to the new address and the email changes only when it is opened.
+- **Email confirmation:** the public `/confirm-email` page opens that link
+  (`/confirm-email#t=…`). The token is in the URL fragment; the page removes it from the address
+  bar and history at once, sets `Referrer-Policy: no-referrer` (a `<meta>` tag while mounted, and
+  a header from `npm run dev` / `npm run preview`), and posts it once. In production, also send
+  `Referrer-Policy: no-referrer` for `/confirm-email` from whatever serves the built frontend.
 - **Administration** (shown only to users whose roles grant it): companies, users (memberships
   and role postings), roles, access (role grants and access bundles), record policies (guided rule
   builder), service accounts (roles, scope, API keys with an explicit expiry), cross-tenant grants
@@ -96,7 +113,6 @@ Redis). Its header comment shows the full wiring. In short:
 
 ```ts
 const rootIds: string[] = [/* platform-admin user uuids, read from your config */];
-const authzPool = createIdentityAuthzPool();         // from @astram/identity/internal; never export it
 
 imports: [
   ShieldModule.forRoot({
@@ -105,12 +121,15 @@ imports: [
     rootIds,
     identityActionKeys: identityAuthActionKeys,
     identityControlPlaneKeys,
-    recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]),
   }),
   IdentityFeatureModule.forRoot({ rootIds, extraObjects: [/* YourType */] }),
 ],
 ```
 
+`IdentityFeatureModule` builds the record authorization from its `extraObjects` and `ShieldModule`
+decides with it, so your own object types are listed once. Do not pass `recordAuthorization` or
+`decisionAuthority` to `ShieldModule` next to it: boot fails.
+
 ## Production requirements
 
 With `auth: true`, check every item before the first production deploy.
@@ -134,12 +153,32 @@ With `auth: true`, check every item before the first production deploy.
   check your production ACL).
 - **A custom `credentialResolver`** (`ShieldModule.forRoot({ credentialResolver })`) replaces the
   framework's resolver, and with it three login checks that you then own:
-  - **MFA enforcement:** return `requiredFactors: ['totp']` for every user with a confirmed MFA
-    device. Return `[]` and that user signs in with the password alone.
+  - **MFA enforcement:** return `requiredFactors: [{ factor: 'totp', secret }]` for every user
+    with a confirmed MFA device, where `secret` is the device's TOTP shared secret (several
+    devices: one entry, secrets joined with `\n`, as the built-in resolver does). A plain
+    `['totp']` does not type-check and leaves the user stuck at `mfa_required`. Return `[]` (or
+    omit the field) and that user signs in with the password alone.
   - **Disabled accounts:** return `null` for an account that must not sign in (the built-in
     resolver does this for `shield_app.users.u_status` other than `active`).
   - **Lockout keying:** the per-account lockout is keyed on the `id` you return, so return the
     same stable id for every spelling of the user's login hint.
+  ```ts
+  import type { CredentialResolver, ResolvedCredential } from '@astram/guard';
+
+  export class DirectoryCredentialResolver implements CredentialResolver {
+    async resolve(identityHint: string): Promise<ResolvedCredential | null> {
+      const user = await directory.findByLogin(identityHint.trim().toLowerCase());
+      if (!user || user.status !== 'active') return null; // unknown or disabled: same answer
+      const secrets = await directory.confirmedTotpSecrets(user.id);
+      return {
+        passwordHash: user.passwordHash,
+        claims: { id: user.id, tenantId: user.companyId, roleIds: user.roleIds }, // stable id
+        requiredFactors: secrets.length ? [{ factor: 'totp', secret: secrets.join('\n') }] : [],
+      };
+    }
+  }
+  ```
+
   The authenticator's other protections (decoy verify, no account enumeration, no secret leaks,
   TOTP limiter and replay guard) still apply.
 - **`rootIds`.** Pass the same platform-administrator user uuids to `ShieldModule.forRoot` and
@@ -166,6 +205,116 @@ With `auth: true`, check every item before the first production deploy.
   in-flight `/auth/refresh` per session). Concurrent refreshes of the same token can trip reuse
   detection, which revokes the session (the user must sign in again).
 
+## Upgrading from 0.8.x
+
+create-astram-app 0.9.0 adds one lint rule (KI #82) and the verified email change (KI #14).
+Bump the ranges in `server/package.json` to `@astram/identity` ^0.8.0, `@astram/guard` ^0.11.0,
+`@astram/engine` ^0.5.2 and `@astram/guide` ^0.2.3, and `frontend/package.json` to
+`@astram/frontend-core` ^0.6.0, then `npm install` in both and run the migrations (identity
+`1710000000020`) with the DDL account before starting the new version.
+
+**Lint rule (KI #82):** copy `server/eslint.config.mjs` from a fresh scaffold, run `npm run lint`,
+and put every flagged uuid input through `UuidPipe` (route params) or `uuidField` /
+`optionalUuidField` / `uuidArrayField` (body and query fields).
+
+**Verified email change (KI #14) — BREAKING in `@astram/guard` 0.11, `@astram/identity` 0.8:**
+
+| Change | What you do |
+|---|---|
+| **BREAKING:** `PATCH /account/profile` with an `email` needs `currentPassword` (and `code` — TOTP or a recovery code — when the user has MFA) and answers **202** `{ pendingEmail: true, profile }` instead of 200. The address changes only after the user opens the link sent to the NEW address. A name-only edit still answers 200. | Send `currentPassword` (+ `code`) with an email change and treat 202 as "check your new inbox". Errors: 400 `invalid_current_password` / `mfa_required` / `invalid_request`, 422 `invalid_email` / `no_changes`, 429 `too_many_requests`, 503 `authentication_unavailable`. |
+| **BREAKING:** adding an MFA device when one is already confirmed needs `code`: `POST /account/mfa/devices/begin` `{ name?, code }` takes a TOTP from an existing device or a recovery code; 400 `mfa_required` without it, 400 `invalid_request` when wrong, 429 / 503. A recovery-login re-enroll session still adds a device without a code. With MFA on, confirm accepts only a device begun in the last 15 minutes (404 otherwise). | Ask for a current code on the add-device form when the user already has a device and send it with `accountService.beginMfaDevice(token, name, code)` (`reason: 'mfa_required'` → ask for it). Scaffolded apps: copy `frontend/src/pages/account/TwoFactorPage.jsx` and `frontend/src/auth/deviceEnrollment.js` (+ its `*.test.mjs`) from a fresh scaffold. |
+| New route `POST /auth/confirm-email` `{ token }` (public): 200 `{ ok: true }`, 400 `invalid_token`, 409 `email_unavailable`, 429, 503. On success every other session of the user is signed out and the old address gets a notice. | Add a confirm page that reads the token from the URL fragment (`#t=…`), POSTs it, and sets `Referrer-Policy: no-referrer`. |
+| New option `ShieldModule.forRoot({ emailChangeLinkBaseUrl })`, default `http://localhost:5173/confirm-email`. The mailed link is `${emailChangeLinkBaseUrl}#t=<token>`. | Set it to your confirm page URL in every non-local environment. |
+| Identity migration `1710000000020-CreateEmailChangeToken` (`shield_identity.email_change_token`, FK to `shield_app.users`). | Run the migrations (DDL account) before starting the new version. |
+| A password reset or change cancels a pending email change. An admin email change (`PUT /identity/users/:uuid`) refuses an address another user or login already has (409), rejects a malformed one (400), and moves the login key when it equalled the old email. | Nothing, unless your admin UI sends an empty email to clear it (now 400). |
+
+**Frontend for the email change:** `PATCH /account/profile` with an `email` now needs
+`currentPassword` (plus `code` when MFA is enrolled) and answers 202; the email changes only when
+the user opens the link mailed to the new address. An app scaffolded earlier still saves names,
+but its profile page cannot change the email. Update `@astram/frontend-core` to 0.6 and copy from
+a fresh scaffold: `frontend/src/pages/account/ProfilePage.jsx`, `frontend/src/pages/ConfirmEmail.jsx`,
+`frontend/src/auth/profileEdit.js`, `frontend/src/auth/confirmEmailLink.js` (and their
+`*.test.mjs`), the `/confirm-email` route in `frontend/src/App.jsx`, and the
+`confirmEmailNoReferrer` plugin in `frontend/vite.config.js`. If you build your own UI, use
+`accountService.updateProfile(token, { email, currentPassword, code })` (202 →
+`{ ok: true, pendingEmail: true }`, `reason: 'mfa_required'` → ask for a code) and
+`authService.confirmEmail(token)`.
+
+## Upgrading from 0.7.x
+
+create-astram-app 0.8 pairs with `@astram/identity` 0.7 and `@astram/guard` 0.10 (breaking wiring
+change). `IdentityFeatureModule` now builds the record authorization itself, from its own
+`extraObjects`, and `ShieldModule` decides with it. Before, the app built it separately with
+`buildIdentityRecordAuthorization(authzPool, extraObjects)`, and an app could pass different object
+types to the two calls, or skip the second call and get the deny-everything authority.
+
+**1. Bump the ranges** in `server/package.json` to `@astram/identity` ^0.7.0, `@astram/guard`
+^0.10.0, `@astram/engine` ^0.5.1, `@astram/migrate` ^0.3.2 and `@astram/guide` ^0.2.2, and
+`frontend/package.json` to `@astram/frontend-core` ^0.5.2, then `npm install` in both. Every package now requires `mariadb` ^3.5.4 (driver SQL-injection advisories). No new
+migrations.
+
+**2. Change `server/src/app.module.ts`:**
+
+- Delete `recordAuthorization: buildIdentityRecordAuthorization(...)` from `ShieldModule.forRoot`
+  (and from a `forRootAsync` factory). `buildIdentityRecordAuthorization` no longer exists.
+- Pass your own object types only to `IdentityFeatureModule.forRoot({ extraObjects })`.
+- Delete `createIdentityAuthzPool()` and its import from `@astram/identity/internal` unless another
+  wiring line still uses the pool (for example `new DbScopeSubtreeResolver(authzPool)`).
+
+```ts
+// before
+const authzPool = createIdentityAuthzPool();
+ShieldModule.forRoot({ auth: true, /* … */, recordAuthorization: buildIdentityRecordAuthorization(authzPool, [Note]) }),
+IdentityFeatureModule.forRoot({ rootIds, extraObjects: [Note] }),
+// after
+ShieldModule.forRoot({ auth: true, /* … */ }),
+IdentityFeatureModule.forRoot({ rootIds, extraObjects: [Note] }),
+```
+
+**Boot checks:** `ShieldModule` fails the boot if it receives `recordAuthorization` or
+`decisionAuthority` while `IdentityFeatureModule` is imported (two sources), and
+`IdentityFeatureModule` fails the boot if the request path would use the deny-everything authority
+(for example with an older `@astram/guard`).
+
+**Behaviour changes:** your `extraObjects` types are now also known to cross-tenant grants (offerable
+types, the offer/accept check) and to the guided rule-builder's policy check. The identity module
+opens one pool fewer (the request path uses the identity module's authz pool).
+
+**3. Copy the lint-wall files** from a fresh scaffold: `server/eslint.config.mjs`, the new
+`server/scripts/check-wall.mjs`, and the `lint` and `lint:wall` scripts in `server/package.json`.
+The wall now also rejects any `node_modules/` or `@astram/<pkg>/dist|src` deep import, banned names
+imported under an alias, computed `import()`/`require()` specifiers, and the driver methods
+`execute`, `batch`, `queryStream` and `beginTransaction` (so `CommandBus.execute()` from
+`@nestjs/cqrs` is flagged too). `lint:wall` fails on any `/internal` or `node_modules/@astram`
+import under `src/features`; run it in CI. The wall catches accidental use; deliberate bypass
+(`.call`, `Reflect.apply`, computed method names, an aliased `require`) is a code-review matter.
+
+**More behaviour changes:**
+
+- Change-password answers a wrong current password with 400 `invalid_current_password` (was 401)
+  and a locked account with 429 (was 401). The frontend shows clear messages for 429 and 503.
+- Login, `/auth/mfa`, change-password and the code-gated MFA account routes count each attempt
+  before verifying it (parallel guesses can no longer slip past the limit) and answer 503 when the
+  limiter's Redis call fails (before: login let the attempt through). A refused attempt counts too.
+  An app that overrides a limiter token with its own object must implement `consume` and `refund`.
+- A role delete the engine refuses no longer strips the role's grants. Revoking a grant needs
+  authority over every service account holding the role (403 otherwise).
+- Renaming another user needs authority over that user. A new posting's department and branch must
+  be linked to the membership's company (400 otherwise). A non-root admin cannot change the status
+  of their own root company (403).
+
+**4. Check for agent keys that never expire.** Keys issued before an expiry became mandatory
+(identity < 0.5) have none. `@astram/identity` 0.7 ships a read-only report; run it in `server/`
+with the app's `APP_DB_*` variables set:
+
+```sh
+npx astram-sa-keys-report                  # lists agent label, company, key version, issue date
+npx astram-sa-keys-report --fail-on-found  # exit 1 if any are listed (CI)
+```
+
+Rotate each listed agent's key with an expiry in the service-accounts page. The report never prints
+secrets, hashes or ids.
+
 ## Upgrading from 0.6.x
 
 create-astram-app 0.7 (2026-10-09) pairs with a framework release that moves raw pools off the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.7.0",
+  "version": "0.9.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/CLAUDE.md

@@ -11,8 +11,8 @@ The Astram framework ships its hard rules + capabilities in the installed
 copies — they are regenerated from the framework package on every install/upgrade):
 
 - **`.claude/rules/astram-framework-rules.md`** — the non-negotiable rules: never edit
-  the framework, all data through the RecordEngine pipe, classify every route,
-  **STOP-and-flag a gap** instead of working around it, fail closed, and — after any
+  the framework, all data through the RecordEngine pipe, classify every route, validate
+  uuid inputs with `UuidPipe` / `uuidField`, **STOP-and-flag a gap** instead of working around it, fail closed, and — after any
   framework upgrade — **re-read these rules first** (Rule 0).
 - **`.claude/rules/astram-framework-capabilities.md`** — what the framework provides
   this version (check here before building; if it's not there, it's a gap → flag it).

package/template/README.md

@@ -70,9 +70,10 @@ boot-pool assertion (ADR-0018), and the Core decision-authority token. With no o
 needs no database or Redis. To turn on login, sessions, MFA and the identity admin
 (`/auth/*`, `/account/*`, `/identity/*`), follow the commented wiring in the header of
 `server/src/app.module.ts`: `ShieldModule.forRoot({ auth: true, emailSender, rootIds,
-identityActionKeys, identityControlPlaneKeys, recordAuthorization })` plus
-`IdentityFeatureModule.forRoot({ rootIds, extraObjects })`. The framework provides the
-credential store, MFA, session handling and the decision authority; you write none of them.
+identityActionKeys, identityControlPlaneKeys })` plus
+`IdentityFeatureModule.forRoot({ rootIds, extraObjects })`, which builds the record
+authorization `ShieldModule` decides with (pass no `recordAuthorization`). The framework provides
+the credential store, MFA, session handling and the decision authority; you write none of them.
 
 ### Before you deploy with auth on
 

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.5.1",
+    "@astram/frontend-core": "^0.6.0",
     "@astram/sdk": "^0.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/App.jsx

@@ -3,7 +3,8 @@
  *
  *   /login, /forgot-password  → public auth screens (redirect to /dashboard if
  *                               already signed in)
- *   /dashboard                → protected (RequireAuth bounces to /login, saving the
+ *   /confirm-email            → public for everyone (the email-change link, KI #14)
+ *   /dashboard               → protected (RequireAuth bounces to /login, saving the
  *                               return path)
  */
 
@@ -16,6 +17,8 @@ import { decideRoute, REENROLL_PATH } from './auth/routeGate';
 import Login from './pages/Login';
 import ForgotPassword from './pages/ForgotPassword';
 import ResetPassword from './pages/ResetPassword';
+import ConfirmEmail from './pages/ConfirmEmail';
+import { CONFIRM_EMAIL_PATH } from './auth/confirmEmailLink';
 import Dashboard from './pages/Dashboard';
 import AccountLayout from './pages/account/AccountLayout';
 import ProfilePage from './pages/account/ProfilePage';
@@ -137,6 +140,9 @@ export default function App() {
           </PublicOnly>
         }
       />
+      {/* Email-change confirmation (KI #14): public for everyone, signed in or not. NOT
+          PublicOnly — bouncing a signed-in user to /dashboard would drop the `#t=` token. */}
+      <Route path={CONFIRM_EMAIL_PATH} element={<ConfirmEmail />} />
       <Route
         path="/dashboard"
         element={

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

@@ -0,0 +1,51 @@
+/**
+ * The email-change confirmation link, kept free of React so `node --test` can check it (KI #14).
+ *
+ * The server mails `<origin>/confirm-email#t=<token>` to the NEW address. The token sits in the
+ * URL FRAGMENT, which browsers never send to a server or put in a Referer header. The page
+ * still removes it from the address bar and history the moment it has read it, and sets
+ * `Referrer-Policy: no-referrer` while it is shown. Never log, store or put the token in a query.
+ */
+
+/** The public route the link opens. */
+export const CONFIRM_EMAIL_PATH = '/confirm-email';
+
+// url-safe token alphabet (base64url / hex); anything else is not a link the server minted.
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{1,512}$/;
+
+/**
+ * The `t` value of a location fragment (`#t=…`), or '' when missing or malformed.
+ * @param {string | null | undefined} hash  `window.location.hash`
+ * @returns {string}
+ */
+export function readConfirmToken(hash) {
+  if (typeof hash !== 'string' || hash.length < 2) return '';
+  const token = new URLSearchParams(hash.replace(/^#/, '')).get('t') ?? '';
+  return TOKEN_SHAPE.test(token) ? token : '';
+}
+
+/**
+ * Drop the fragment from the CURRENT history entry (no new entry, router state kept), so the
+ * token does not stay in the address bar, the back/forward list or a bookmark.
+ * @param {{ location: { pathname: string, search: string, hash: string },
+ *           history: { state: unknown, replaceState: Function } }} win  `window`
+ * @returns {boolean} true when a fragment was removed
+ */
+export function scrubConfirmToken(win) {
+  if (!win.location.hash) return false;
+  win.history.replaceState(win.history.state, '', win.location.pathname + win.location.search);
+  return true;
+}
+
+/**
+ * Add `<meta name="referrer" content="no-referrer">` for as long as the page is mounted.
+ * @param {Document} doc
+ * @returns {() => void} removes the tag again
+ */
+export function applyNoReferrer(doc) {
+  const meta = doc.createElement('meta');
+  meta.setAttribute('name', 'referrer');
+  meta.setAttribute('content', 'no-referrer');
+  doc.head.appendChild(meta);
+  return () => doc.head.removeChild(meta);
+}

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

@@ -0,0 +1,108 @@
+// confirmEmailLink.test.mjs — KI #14: the email-change link carries its single-use token in
+// the URL FRAGMENT (`/confirm-email#t=…`) so it never reaches a server log or a Referer. The
+// page must read it, then drop it from the address bar and history at once.
+//
+//   node --test src/auth/confirmEmailLink.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  CONFIRM_EMAIL_PATH,
+  readConfirmToken,
+  scrubConfirmToken,
+  applyNoReferrer,
+} from './confirmEmailLink.js';
+
+const TOKEN = ['placeholder', 'link', 'value'].join('_');
+
+describe('readConfirmToken', () => {
+  test('reads t from the fragment', () => {
+    assert.equal(readConfirmToken(`#t=${TOKEN}`), TOKEN);
+  });
+
+  test('ignores other fragment keys and order', () => {
+    assert.equal(readConfirmToken(`#x=1&t=${TOKEN}`), TOKEN);
+  });
+
+  test('missing, empty or no fragment → empty string', () => {
+    for (const hash of ['', '#', '#t=', '#token=abc', undefined, null]) {
+      assert.equal(readConfirmToken(hash), '');
+    }
+  });
+
+  test('a token with characters outside the url-safe set is refused', () => {
+    assert.equal(readConfirmToken('#t=abc%20def'), '');
+    assert.equal(readConfirmToken('#t=<script>'), '');
+    assert.equal(readConfirmToken(`#t=${'a'.repeat(600)}`), '');
+  });
+
+  test('the page path is /confirm-email', () => {
+    assert.equal(CONFIRM_EMAIL_PATH, '/confirm-email');
+  });
+});
+
+describe('scrubConfirmToken', () => {
+  function fakeWindow(url) {
+    const u = new URL(url);
+    const calls = [];
+    return {
+      calls,
+      location: { pathname: u.pathname, search: u.search, hash: u.hash },
+      history: {
+        state: { idx: 3, key: 'k' },
+        replaceState: (state, title, next) => calls.push({ state, title, next }),
+        pushState: () => assert.fail('must not add a history entry'),
+      },
+    };
+  }
+
+  test('replaces the current entry with the same path minus the fragment, keeping router state', () => {
+    const win = fakeWindow(`http://app.test/confirm-email?x=1#t=${TOKEN}`);
+    assert.equal(scrubConfirmToken(win), true);
+    assert.equal(win.calls.length, 1);
+    assert.equal(win.calls[0].next, '/confirm-email?x=1');
+    assert.deepEqual(win.calls[0].state, { idx: 3, key: 'k' });
+    assert.ok(!JSON.stringify(win.calls).includes(TOKEN));
+  });
+
+  test('never moves the token into the query string', () => {
+    const win = fakeWindow(`http://app.test/confirm-email#t=${TOKEN}`);
+    scrubConfirmToken(win);
+    assert.equal(win.calls[0].next, '/confirm-email');
+  });
+
+  test('nothing to scrub → no history call', () => {
+    const win = fakeWindow('http://app.test/confirm-email');
+    assert.equal(scrubConfirmToken(win), false);
+    assert.equal(win.calls.length, 0);
+  });
+});
+
+describe('applyNoReferrer', () => {
+  function fakeDocument() {
+    const children = [];
+    return {
+      children,
+      head: {
+        appendChild: (el) => children.push(el),
+        removeChild: (el) => children.splice(children.indexOf(el), 1),
+      },
+      createElement: (tag) => ({
+        tag,
+        attrs: {},
+        setAttribute(k, v) {
+          this.attrs[k] = v;
+        },
+      }),
+    };
+  }
+
+  test('adds <meta name="referrer" content="no-referrer"> and the cleanup removes it', () => {
+    const doc = fakeDocument();
+    const cleanup = applyNoReferrer(doc);
+    assert.equal(doc.children.length, 1);
+    assert.equal(doc.children[0].tag, 'meta');
+    assert.deepEqual(doc.children[0].attrs, { name: 'referrer', content: 'no-referrer' });
+    cleanup();
+    assert.equal(doc.children.length, 0);
+  });
+});

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

@@ -0,0 +1,33 @@
+/**
+ * Adding an authenticator device, kept free of React so `node --test` can check it.
+ *
+ * When the account already has a confirmed device, the server needs a code from one of them (or
+ * a recovery code) before it starts enrolling another, so a stolen session alone cannot add the
+ * attacker's app (KI #14 re-review). The recovery-login re-enroll screen is exempt: that user
+ * signed in with a recovery code because the device is lost. The code is sent once, never stored.
+ */
+
+/**
+ * @param {{ deviceCount: number, reenrollMode: boolean, serverAsked?: boolean }} state
+ * @returns {boolean} whether the add-device form must ask for a code
+ */
+export function addDeviceNeedsCode({ deviceCount, reenrollMode, serverAsked = false }) {
+  if (serverAsked) return true;
+  return deviceCount > 0 && !reenrollMode;
+}
+
+/**
+ * Turn the add-device form into the begin arguments, or an error to show before sending.
+ * @param {{ name: string, code: string, codeRequired: boolean }} form
+ * @returns {{ error: string } | { name: string, code?: string }}
+ */
+export function planBeginDevice(form) {
+  const name = form.name.trim();
+  if (!name) return { error: 'Enter a name for this device.' };
+  if (!form.codeRequired) return { name };
+  const code = form.code.trim();
+  if (!code) {
+    return { error: 'Enter a code from one of your authenticator apps or a recovery code.' };
+  }
+  return { name, code };
+}

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

@@ -0,0 +1,56 @@
+// deviceEnrollment.test.mjs — KI #14 re-review: adding an authenticator when the account already
+// has one needs a code from an existing device (or a recovery code); the recovery-login re-enroll
+// screen is exempt.
+//
+//   node --test src/auth/deviceEnrollment.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { addDeviceNeedsCode, planBeginDevice } from './deviceEnrollment.js';
+
+describe('addDeviceNeedsCode', () => {
+  test('no device yet → no code', () => {
+    assert.equal(addDeviceNeedsCode({ deviceCount: 0, reenrollMode: false }), false);
+  });
+
+  test('MFA already on → a code', () => {
+    assert.equal(addDeviceNeedsCode({ deviceCount: 1, reenrollMode: false }), true);
+  });
+
+  test('re-enroll screen (lost device still listed) → no code', () => {
+    assert.equal(addDeviceNeedsCode({ deviceCount: 1, reenrollMode: true }), false);
+  });
+
+  test('the server asked for one (mfa_required) → a code, even if the list was empty', () => {
+    assert.equal(
+      addDeviceNeedsCode({ deviceCount: 0, reenrollMode: false, serverAsked: true }),
+      true,
+    );
+  });
+});
+
+describe('planBeginDevice', () => {
+  test('a name is required', () => {
+    assert.deepEqual(planBeginDevice({ name: '  ', code: '', codeRequired: false }), {
+      error: 'Enter a name for this device.',
+    });
+  });
+
+  test('no code needed → only the name', () => {
+    assert.deepEqual(planBeginDevice({ name: ' Phone ', code: '123', codeRequired: false }), {
+      name: 'Phone',
+    });
+  });
+
+  test('code needed but empty → error, nothing sent', () => {
+    assert.deepEqual(planBeginDevice({ name: 'Tablet', code: '  ', codeRequired: true }), {
+      error: 'Enter a code from one of your authenticator apps or a recovery code.',
+    });
+  });
+
+  test('code needed → name + trimmed code', () => {
+    assert.deepEqual(planBeginDevice({ name: 'Tablet', code: ' 123456 ', codeRequired: true }), {
+      name: 'Tablet',
+      code: '123456',
+    });
+  });
+});

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

@@ -0,0 +1,58 @@
+/**
+ * The self-service profile edit, kept free of React so `node --test` can check it (KI #14).
+ *
+ * A name change applies at once. An email change is VERIFIED by the server: it needs the
+ * current password (plus a TOTP or recovery code when the account has MFA) and only takes
+ * effect when the user opens the link mailed to the NEW address. Until then the profile keeps
+ * the old email. The password and code are sent with this one request and never stored.
+ */
+
+export const PENDING_EMAIL_MESSAGE =
+  'We sent a confirmation link to the new address. Your email changes when you open it.';
+
+/**
+ * Turn the form into the PATCH body, or an error to show before sending anything.
+ * @param {{ name: string, email: string, currentPassword: string, code: string,
+ *           codeRequired: boolean }} form
+ * @param {{ name: string, email: string }} initial  the current profile values
+ * @returns {{ error: string } | { changes: object, emailChanging: boolean }}
+ */
+export function planProfileEdit(form, initial) {
+  const name = form.name.trim();
+  const email = form.email.trim();
+  if (!name) return { error: 'Please enter your name.' };
+
+  const changes = {};
+  if (name !== initial.name) changes.name = name;
+  const emailChanging = email !== initial.email;
+  if (emailChanging) {
+    // The password is sent as typed (spaces are part of it).
+    if (!form.currentPassword) {
+      return { error: 'Enter your current password to change your email.' };
+    }
+    const code = form.code.trim();
+    if (form.codeRequired && !code) {
+      return { error: 'Enter a code from your authenticator app or a recovery code.' };
+    }
+    changes.email = email;
+    changes.currentPassword = form.currentPassword;
+    if (code) changes.code = code;
+  }
+  if (Object.keys(changes).length === 0) return { error: 'Nothing to update.' };
+  return { changes, emailChanging };
+}
+
+/**
+ * What the page does with an `accountService.updateProfile` result.
+ * @returns {{ kind: 'saved' } | { kind: 'pending', message: string }
+ *         | { kind: 'error', error: string, showCode: boolean }}
+ */
+export function interpretProfileResult(r) {
+  if (r.ok && r.pendingEmail) return { kind: 'pending', message: PENDING_EMAIL_MESSAGE };
+  if (r.ok) return { kind: 'saved' };
+  return {
+    kind: 'error',
+    error: r.error || 'Could not update your profile.',
+    showCode: r.reason === 'mfa_required' || r.reason === 'invalid_code',
+  };
+}