create-astram-app 0.8.0 → 0.9.1

package/README.md

@@ -72,6 +72,16 @@ The wall (`eslint.config.mjs`, plus the `lint:wall` grep for `/internal` and
 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 rule only matches
+those names: a uuid input under another name (`@Param('target')`), a destructured body, a body
+bound to another variable name, a value read off `req`, or a param given any other pipe is not
+flagged, so a clean lint run does not prove every uuid input
+is canonicalised. Put `UuidPipe` on every uuid route param, whatever its name, and a uuid helper
+on every uuid body or query field.
+
 ## 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
@@ -80,7 +90,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
@@ -126,6 +143,12 @@ With `auth: true`, check every item before the first production deploy.
   an `EmailSender` (`send({ to, subject, html, text })`, e.g. SMTP or SendGrid) or
   `emailSender: 'disabled'` (no reset emails; `POST /auth/forgot-password` still answers 204).
   The dev logger, which prints reset links, is never used in production.
+- **`RESET_LINK_BASE_URL` and `EMAIL_CHANGE_LINK_BASE_URL`.** The public URLs of your
+  reset-password and confirm-email pages (e.g. `https://app.example.com/reset-password` and
+  `https://app.example.com/confirm-email`); `ShieldModule.forRoot({ emailChangeLinkBaseUrl })`
+  wins over the env var. Outside `NODE_ENV=development|test`, with an `emailSender`, boot fails
+  when either is unset, not a URL, or points at `localhost`, `127.0.0.1`, `::1` or `0.0.0.0`
+  (`emailSender: 'disabled'` mails no links, so it skips this check).
 - **Explicit `NODE_ENV`.** Set `NODE_ENV=production`. `npm run dev` sets `development` for you;
   `npm start` sets nothing. An unset `NODE_ENV` counts as production for the email rule, and the
   framework's dev seed migrations run only under `development` (or `ASTRAM_SEED_DEV=1`).
@@ -193,6 +216,41 @@ 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

package/dist/index.js

@@ -258,7 +258,8 @@ export function main(argv = process.argv.slice(2)) {
     console.log('  • .astram/guide/ — your own, upgrade-safe project-rules space (ADR-0025).');
     console.log('\n  Login, sessions, MFA and the identity admin are built in: enable them in');
     console.log('  server/src/app.module.ts (see its comment block). Before production, read the');
-    console.log('  README "Production requirements" (emailSender, NODE_ENV, TRUST_PROXY, migrations).');
+    console.log('  README "Production requirements" (emailSender, link URLs, NODE_ENV, TRUST_PROXY,');
+    console.log('  migrations).');
     console.log('\nNext steps:');
     console.log(`  cd ${appName}/server`);
     console.log('  npm install');

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,MAAM,EACN,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAExD,gGAAgG;AAChG,MAAM,cAAc,GAAG,cAAc,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW;IACzB,yEAAyE;IACzE,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAwB;IACtD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,yBAAyB,CAAC;IACnC,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,wDAAwD,IAAI,GAAG,CAAC;IACzE,CAAC;IACD,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,kCAAkC,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,+DAA+D,IAAI,GAAG,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,wCAAwC,IAAI,GAAG,CAAC;IACzD,CAAC;IACD,gDAAgD;IAChD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,OAAO,mEAAmE,IAAI,GAAG,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,KAAK,GAAG;IACZ,mDAAmD;IACnD,EAAE;IACF,6EAA6E;IAC7E,8EAA8E;IAC9E,iBAAiB;IACjB,EAAE;IACF,uEAAuE;IACvE,oEAAoE;IACpE,EAAE;IACF,UAAU;IACV,gCAAgC;IAChC,gDAAgD;CACjD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAQb;;;;;;GAMG;AACH,SAAS,gBAAgB,CACvB,OAAe,EACf,QAAgB,EAChB,OAAe,EACf,MAAkB,EAClB,GAAW;IAEX,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,2DAA2D;QAC3D,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7E,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,OAAe,EACf,OAAe,EACf,MAAkB,EAClB,OAAO,GAAG,EAAE;IAEZ,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,4EAA4E;QAC5E,4EAA4E;QAC5E,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAE1D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;YACtD,SAAS;QACX,CAAC;QAED,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,SAAS,UAAU,CAAC,QAAgB;IAClC,OAAO,CACL,4DAA4D,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC3E,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CACzB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAU,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAe,EACf,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,YAAY,GAAG,KAAK;IAEpB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAe,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAExD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,WAAW,OAAO,iCAAiC,CAAC,CAAC;QACvE,CAAC;QACD,6EAA6E;QAC7E,+EAA+E;IACjF,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAE/B,4EAA4E;IAC5E,oEAAoE;IACpE,wEAAwE;IACxE,4CAA4C;IAC5C,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,8EAA8E;IAC9E,qEAAqE;IACrE,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,0EAA0E;IAC1E,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACnE,IAAK,iBAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,0DAA0D;IAC1D,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE7F,wEAAwE;IACxE,4EAA4E;IAC5E,iEAAiE;IACjE,IAAI,YAAY,EAAE,CAAC;QACjB,YAAY,CACV,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1B,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAC3B,OAAO,EACP,MAAM,EACN,UAAU,CACX,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC;AAED,sEAAsE;AACtE,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAE7C;;;;;GAKG;AACH,SAAS,YAAY,CAAC,IAAc;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAEvD,MAAM,eAAe,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,sBAAsB,eAAe,IAAI,CAAC,CAAC;QACzD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,OAAO,GAAI,IAAe,CAAC,IAAI,EAAE,CAAC;IAExC,IAAI,MAAkB,CAAC;IACvB,IAAI,CAAC;QACH,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,sBAAuB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,CAAC;IACX,CAAC;IAED,sDAAsD;IACtD,OAAO,CAAC,GAAG,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,MAAM,mBAAmB,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CACT,KAAK,MAAM,CAAC,OAAO,CAAC,MAAM,qDAAqD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAC9F,OAAO,CAAC,GAAG,CAAC,2EAA2E,CAAC,CAAC;IACzF,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,6EAA6E,CAAC,CAAC;IAC7F,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,kFAAkF,CAAC,CAAC;QAChG,OAAO,CAAC,GAAG,CAAC,sEAAsE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,OAAO,CAAC,GAAG,CAAC,oFAAoF,CAAC,CAAC;IAClG,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAC9F,OAAO,CAAC,GAAG,CAAC,kFAAkF,CAAC,CAAC;IAChG,OAAO,CAAC,GAAG,CAAC,6EAA6E,CAAC,CAAC;IAC3F,OAAO,CAAC,GAAG,CAAC,8EAA8E,CAAC,CAAC;IAC5F,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,OAAO,CAAC,GAAG,CAAC,oFAAoF,CAAC,CAAC;IAClG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE9B,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC,QAAQ,OAAO,SAAS,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,OAAO,CAAC,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAC9F,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,QAAQ,OAAO,WAAW,CAAC,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,+DAA+D,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,2EAA2E;AAC3E,+EAA+E;AAC/E,8EAA8E;AAC9E,iFAAiF;AACjF,SAAS,cAAc;IACrB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;IACvD,CAAC;AACH,CAAC;AACD,IAAI,cAAc,EAAE,EAAE,CAAC;IACrB,OAAO,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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

@@ -79,6 +79,9 @@ the credential store, MFA, session handling and the decision authority; you writ
 
 - 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.
+- 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.
 - Set `TRUST_PROXY` to your real proxy hop count, or the per-IP login/reset limits stay off.
 - Set `REFRESH_HMAC_KEY` (a long random secret, never committed) and `REDIS_URL`. Redis is
   required: the request path reads only Redis and fails closed when it is down.
@@ -100,7 +103,12 @@ The full list, and how to upgrade an app scaffolded with an earlier version, is
 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
    `src/**` except `app.module.ts` and `main.ts`.
-5. Add a test (see `server/test/` for the pattern).
+5. **Canonicalise every uuid input** with `@astram/guard`: `@Param('uuid', UuidPipe)` on EVERY
+   uuid route param, whatever its name, and `uuidField` / `optionalUuidField` / `uuidArrayField`
+   on every uuid body or query field. The database matches uuids ignoring case, trailing spaces
+   and width, so a raw one slips past exact checks. The lint rule only flags uuid-looking names
+   (`id`, `uuid`, `…Id(s)`, `…Uuid(s)`); it is a nudge, not a guarantee.
+6. Add a test (see `server/test/` for the pattern).
 
 `server/src/features/` starts empty — it's your space.
 

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.5.2",
+    "@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',
+  };
+}

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

@@ -0,0 +1,135 @@
+// profileEdit.test.mjs — KI #14: changing the email needs the current password (and an MFA
+// code when the account has MFA) and only takes effect from the link sent to the new address.
+//
+//   node --test src/auth/profileEdit.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { planProfileEdit, interpretProfileResult, PENDING_EMAIL_MESSAGE } from './profileEdit.js';
+
+const initial = { name: 'Jane', email: 'old@x.test' };
+const pw = 'p'.repeat(12);
+const form = (over = {}) => ({
+  name: 'Jane',
+  email: 'old@x.test',
+  currentPassword: '',
+  code: '',
+  codeRequired: false,
+  ...over,
+});
+
+describe('planProfileEdit', () => {
+  test('name only → no password asked, only the name is sent', () => {
+    assert.deepEqual(planProfileEdit(form({ name: ' New ' }), initial), {
+      changes: { name: 'New' },
+      emailChanging: false,
+    });
+  });
+
+  test('a password typed for a name-only edit is not sent', () => {
+    const plan = planProfileEdit(form({ name: 'New', currentPassword: pw }), initial);
+    assert.deepEqual(plan.changes, { name: 'New' });
+  });
+
+  test('empty name → error', () => {
+    assert.deepEqual(planProfileEdit(form({ name: '  ' }), initial), {
+      error: 'Please enter your name.',
+    });
+  });
+
+  test('nothing changed → error', () => {
+    assert.deepEqual(planProfileEdit(form(), initial), { error: 'Nothing to update.' });
+  });
+
+  test('email changed without a current password → error, nothing sent', () => {
+    assert.deepEqual(planProfileEdit(form({ email: 'new@x.test' }), initial), {
+      error: 'Enter your current password to change your email.',
+    });
+  });
+
+  test('email changed with the password → email + currentPassword sent', () => {
+    assert.deepEqual(
+      planProfileEdit(form({ email: ' new@x.test ', currentPassword: pw }), initial),
+      { changes: { email: 'new@x.test', currentPassword: pw }, emailChanging: true },
+    );
+  });
+
+  test('MFA account: a code is required and sent with the email change', () => {
+    assert.deepEqual(
+      planProfileEdit(
+        form({ email: 'new@x.test', currentPassword: pw, codeRequired: true }),
+        initial,
+      ),
+      { error: 'Enter a code from your authenticator app or a recovery code.' },
+    );
+    assert.deepEqual(
+      planProfileEdit(
+        form({ email: 'new@x.test', currentPassword: pw, codeRequired: true, code: ' 123456 ' }),
+        initial,
+      ),
+      {
+        changes: { email: 'new@x.test', currentPassword: pw, code: '123456' },
+        emailChanging: true,
+      },
+    );
+  });
+
+  test('name and email together → both sent, plus the proof', () => {
+    const plan = planProfileEdit(
+      form({ name: 'New', email: 'new@x.test', currentPassword: pw }),
+      initial,
+    );
+    assert.deepEqual(plan.changes, { name: 'New', email: 'new@x.test', currentPassword: pw });
+  });
+
+  test('the password is never trimmed', () => {
+    const plan = planProfileEdit(
+      form({ email: 'new@x.test', currentPassword: ` ${pw} ` }),
+      initial,
+    );
+    assert.equal(plan.changes.currentPassword, ` ${pw} `);
+  });
+});
+
+describe('interpretProfileResult', () => {
+  test('200 → saved', () => {
+    assert.deepEqual(interpretProfileResult({ ok: true, profile: {} }), { kind: 'saved' });
+  });
+
+  test('202 → pending, with the "check your new inbox" message', () => {
+    assert.deepEqual(interpretProfileResult({ ok: true, pendingEmail: true, profile: {} }), {
+      kind: 'pending',
+      message: PENDING_EMAIL_MESSAGE,
+    });
+    assert.equal(
+      PENDING_EMAIL_MESSAGE,
+      'We sent a confirmation link to the new address. Your email changes when you open it.',
+    );
+  });
+
+  test('mfa_required / invalid_code → error that shows the code field', () => {
+    for (const reason of ['mfa_required', 'invalid_code']) {
+      assert.deepEqual(interpretProfileResult({ ok: false, status: 400, reason, error: 'E' }), {
+        kind: 'error',
+        error: 'E',
+        showCode: true,
+      });
+    }
+  });
+
+  test('other failures → error, code field unchanged', () => {
+    assert.deepEqual(
+      interpretProfileResult({
+        ok: false,
+        status: 400,
+        reason: 'invalid_current_password',
+        error: 'Current password is incorrect.',
+      }),
+      { kind: 'error', error: 'Current password is incorrect.', showCode: false },
+    );
+    assert.deepEqual(interpretProfileResult({ ok: false, status: 500 }), {
+      kind: 'error',
+      error: 'Could not update your profile.',
+      showCode: false,
+    });
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * ConfirmEmail — the page the email-change link opens (`/confirm-email#t=…`, KI #14).
+ *
+ * Public: the link may be opened on a device with no session, and a signed-in user is not
+ * bounced away (that would drop the fragment). On mount it reads the token from the URL
+ * fragment, removes the fragment from the address bar and history (`history.replaceState`),
+ * and sets `<meta name="referrer" content="no-referrer">` while mounted. It then POSTs the
+ * token once through `authService.confirmEmail` (no bearer). The token is never logged,
+ * stored or put in a query string. Fragment handling lives in `auth/confirmEmailLink.js`.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { AlertCircle, ArrowLeft, CheckCircle2, Loader2 } from 'lucide-react';
+import { useAuth } from '@/auth/AuthContext';
+import { applyNoReferrer, readConfirmToken, scrubConfirmToken } from '@/auth/confirmEmailLink';
+import { Card, CardContent } from '@/components/ui/card';
+import ThemeToggle from '@/theme/ThemeToggle';
+import { branding } from '@/config/branding';
+
+const MISSING_TOKEN = { ok: false, status: 400, error: 'This link is invalid or has expired.' };
+
+export default function ConfirmEmail() {
+  const { auth, isAuthenticated, refreshProfile } = useAuth();
+  // Read only (pure, so StrictMode's double call sees the same value); scrubbed below.
+  const [token] = useState(() => readConfirmToken(window.location.hash));
+  const [result, setResult] = useState(token ? null : MISSING_TOKEN);
+  // The token is single-use: post it once, even when StrictMode re-runs the effect.
+  const postedRef = useRef(false);
+
+  // Before paint: drop the fragment from the URL and history, and send no Referer.
+  useLayoutEffect(() => {
+    scrubConfirmToken(window);
+    return applyNoReferrer(document);
+  }, []);
+
+  useEffect(() => {
+    if (!token || postedRef.current) return;
+    postedRef.current = true;
+    auth.confirmEmail(token).then((r) => {
+      setResult(r);
+      // Best effort: the header shows the new address at once (a revoked session just
+      // signs out on its next request).
+      if (r.ok && isAuthenticated) refreshProfile();
+    });
+  }, [auth, token, isAuthenticated, refreshProfile]);
+
+  const back = isAuthenticated
+    ? { to: '/account/profile', label: 'Back to your profile' }
+    : { to: '/login', label: 'Sign in' };
+
+  return (
+    <div className="grid-bg relative flex min-h-screen items-center justify-center bg-background p-6">
+      <div className="absolute right-4 top-4">
+        <ThemeToggle compact />
+      </div>
+
+      <Card className="w-full max-w-md shadow-xl">
+        <CardContent className="p-8">
+          <div className="mb-7 flex flex-col items-center gap-4">
+            <img
+              src={branding.logo.light}
+              alt={branding.appName}
+              className="h-9 w-auto dark:hidden"
+            />
+            <img
+              src={branding.logo.dark}
+              alt={branding.appName}
+              className="hidden h-9 w-auto dark:block"
+            />
+            <h1 className="text-xl font-bold tracking-tight">Confirm your new email</h1>
+          </div>
+
+          {result === null && (
+            <div
+              role="status"
+              aria-live="polite"
+              className="flex items-center justify-center gap-2 text-sm text-muted-foreground"
+            >
+              <Loader2 className="size-4 animate-spin" aria-hidden="true" />
+              Confirming…
+            </div>
+          )}
+
+          {result?.ok === true && (
+            <div
+              role="status"
+              className="flex items-start gap-2 rounded-lg border border-primary/30 bg-primary/10 px-3 py-2.5 text-sm"
+            >
+              <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-primary" />
+              <span>
+                Your email address has been changed. For your security, your other sessions were
+                signed out.
+              </span>
+            </div>
+          )}
+
+          {result?.ok === false && (
+            <div
+              role="alert"
+              className="flex items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2.5 text-sm text-destructive"
+            >
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>
+                {result.error}
+                {result.status === 400 && ' Request the change again from your profile.'}
+              </span>
+            </div>
+          )}
+
+          <div className="mt-6 text-center">
+            <Link
+              to={back.to}
+              className="inline-flex items-center gap-1.5 text-sm font-medium text-primary hover:underline"
+            >
+              <ArrowLeft className="size-4" />
+              {back.label}
+            </Link>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/template/frontend/src/pages/account/ProfilePage.jsx

@@ -4,15 +4,22 @@
  *
  * Pre-fills from the /auth/me profile (via useAuth().profile); on save it PATCHes
  * /account/profile through the shared accountService, then calls refreshProfile() so
- * the header/sidebar user card reflects the new name/email at once. Only sends the
- * fields that actually changed (partial edit). All display values are NAMES (never
- * UUIDs) — the profile the server returns is UUID-free by contract. (Logic lifted
- * verbatim from the former single-page Account.jsx ProfileCard.)
+ * the header/sidebar user card reflects the new name at once. Only sends the fields that
+ * actually changed (partial edit). All display values are NAMES (never UUIDs).
+ *
+ * Email change (KI #14): the server verifies it. Changing the email asks for the current
+ * password, and for a TOTP / recovery code when the account has MFA (detected up front from
+ * the device list, and always when the server answers `mfa_required`). The server answers 202
+ * and mails a link to the NEW address; the email only changes when that link is opened (the
+ * /confirm-email page), so the page keeps showing the old one. The password and code live in
+ * component state for one request and are cleared after it. The form logic is in
+ * `auth/profileEdit.js`.
  */
 import { useEffect, useState } from 'react';
 import { toast } from 'sonner';
-import { Loader2, ShieldCheck, UserRound } from 'lucide-react';
+import { Loader2, MailCheck, ShieldCheck, UserRound } from 'lucide-react';
 import { useAuth } from '@/auth/AuthContext';
+import { planProfileEdit, interpretProfileResult } from '@/auth/profileEdit';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -22,12 +29,18 @@ export default function ProfilePage() {
   const { tokens, account, profile, refreshProfile } = useAuth();
   const [name, setName] = useState(profile?.name ?? '');
   const [email, setEmail] = useState(profile?.email ?? '');
+  const [currentPassword, setCurrentPassword] = useState('');
+  const [code, setCode] = useState('');
+  // True when the account has MFA (from the device list) or the server asked for a code.
+  const [codeRequired, setCodeRequired] = useState(false);
+  const [pendingNotice, setPendingNotice] = useState('');
   const [error, setError] = useState('');
   const [submitting, setSubmitting] = useState(false);
 
   const initialName = profile?.name ?? '';
   const initialEmail = profile?.email ?? '';
-  const dirty = name.trim() !== initialName || email.trim() !== initialEmail;
+  const emailDirty = email.trim() !== initialEmail;
+  const dirty = name.trim() !== initialName || emailDirty;
 
   // The profile may still be loading (null) when this first mounts (e.g. a hard page
   // refresh). Seed the fields once it arrives / changes; a server-side refresh after
@@ -37,32 +50,58 @@ export default function ProfilePage() {
     setEmail(profile?.email ?? '');
   }, [profile?.name, profile?.email]);
 
+  // Best effort: ask for the MFA code up front when the account has a device. If this
+  // fails, the server's `mfa_required` answer shows the field instead.
+  const accessToken = tokens?.accessToken;
+  useEffect(() => {
+    if (!accessToken) return;
+    let active = true;
+    account.listMfaDevices(accessToken).then((r) => {
+      if (active && r.ok && r.mfaEnabled) setCodeRequired(true);
+    });
+    return () => {
+      active = false;
+    };
+  }, [account, accessToken]);
+
   const onSubmit = async (e) => {
     e.preventDefault();
     setError('');
 
-    if (!name.trim()) {
-      setError('Please enter your name.');
-      return;
-    }
-    const changes = {};
-    if (name.trim() !== initialName) changes.name = name.trim();
-    if (email.trim() !== initialEmail) changes.email = email.trim();
-    if (Object.keys(changes).length === 0) {
-      setError('Nothing to update.');
+    const plan = planProfileEdit(
+      { name, email, currentPassword, code, codeRequired },
+      {
+        name: initialName,
+        email: initialEmail,
+      },
+    );
+    if (plan.error) {
+      setError(plan.error);
       return;
     }
 
     setSubmitting(true);
-    const r = await account.updateProfile(tokens?.accessToken, changes);
+    const r = await account.updateProfile(tokens?.accessToken, plan.changes);
+    // The password and code were for this one request only.
+    setCurrentPassword('');
+    setCode('');
     setSubmitting(false);
 
-    if (r.ok) {
-      await refreshProfile();
-      toast.success('Profile updated');
+    const outcome = interpretProfileResult(r);
+    if (outcome.kind === 'error') {
+      if (outcome.showCode) setCodeRequired(true);
+      setError(outcome.error);
+      return;
+    }
+    await refreshProfile();
+    if (outcome.kind === 'pending') {
+      // The email is unchanged until the link is opened: show the current one again.
+      setEmail(initialEmail);
+      setPendingNotice(outcome.message);
+      toast.success('Check your new inbox');
       return;
     }
-    setError(r.error || 'Could not update your profile.');
+    toast.success('Profile updated');
   };
 
   return (
@@ -99,6 +138,49 @@ export default function ProfilePage() {
             />
           </div>
 
+          {emailDirty && (
+            <div className="space-y-4 rounded-lg border bg-muted/30 p-4">
+              <p className="text-sm text-muted-foreground">
+                To change your email, confirm it is you. We will send a link to the new address;
+                your email changes when you open it.
+              </p>
+              <div className="space-y-1.5">
+                <Label htmlFor="pf-current-password">Current password</Label>
+                <Input
+                  id="pf-current-password"
+                  type="password"
+                  autoComplete="current-password"
+                  value={currentPassword}
+                  onChange={(e) => setCurrentPassword(e.target.value)}
+                />
+              </div>
+              {codeRequired && (
+                <div className="space-y-1.5">
+                  <Label htmlFor="pf-code">Authenticator or recovery code</Label>
+                  <Input
+                    id="pf-code"
+                    type="text"
+                    inputMode="text"
+                    autoComplete="one-time-code"
+                    value={code}
+                    onChange={(e) => setCode(e.target.value)}
+                    placeholder="123456"
+                  />
+                </div>
+              )}
+            </div>
+          )}
+
+          {pendingNotice && (
+            <div
+              role="status"
+              className="flex items-start gap-2 rounded-lg border border-primary/30 bg-primary/10 px-3 py-2 text-sm"
+            >
+              <MailCheck className="mt-0.5 size-4 shrink-0 text-primary" />
+              <span>{pendingNotice}</span>
+            </div>
+          )}
+
           {error && (
             <div className="rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
               {error}

package/template/frontend/src/pages/account/TwoFactorPage.jsx

@@ -37,6 +37,7 @@ import {
   X,
 } from 'lucide-react';
 import { useAuth } from '@/auth/AuthContext';
+import { addDeviceNeedsCode, planBeginDevice } from '@/auth/deviceEnrollment';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { InputOTP, InputOTPGroup, InputOTPSlot } from '@/components/ui/input-otp';
@@ -296,6 +297,14 @@ export default function TwoFactorPage({ onDeviceConfirmed, reenrollMode = false
   const [code, setCode] = useState('');
   const [addError, setAddError] = useState('');
   const [addBusy, setAddBusy] = useState(false);
+  // With MFA already on, adding a device needs a code from an existing one (or a recovery code).
+  const [stepUpCode, setStepUpCode] = useState('');
+  const [serverAskedCode, setServerAskedCode] = useState(false);
+  const stepUpRequired = addDeviceNeedsCode({
+    deviceCount: devices.length,
+    reenrollMode,
+    serverAsked: serverAskedCode,
+  });
   // The boxed-OTP input (input-otp forwards its ref to the real <input>). Focused when the
   // enroll step opens so the user can type the code straight away without clicking a box.
   const codeInputRef = useRef(null);
@@ -399,12 +408,15 @@ export default function TwoFactorPage({ onDeviceConfirmed, reenrollMode = false
   const openAdd = () => {
     setAddError('');
     setNewName('');
+    setStepUpCode('');
     setAddPhase('naming');
   };
 
   const resetAdd = () => {
     setAddPhase('idle');
     setNewName('');
+    setStepUpCode('');
+    setServerAskedCode(false);
     setDeviceId('');
     setSecret('');
     setOtpauthUri('');
@@ -415,18 +427,26 @@ export default function TwoFactorPage({ onDeviceConfirmed, reenrollMode = false
   const onBegin = async (e) => {
     e.preventDefault();
     setAddError('');
-    const name = newName.trim();
-    if (!name) {
-      setAddError('Enter a name for this device.');
+    const plan = planBeginDevice({
+      name: newName,
+      code: stepUpCode,
+      codeRequired: stepUpRequired,
+    });
+    if (plan.error) {
+      setAddError(plan.error);
       return;
     }
     setAddBusy(true);
-    const r = await account.beginMfaDevice(token, name);
+    const r = await account.beginMfaDevice(token, plan.name, plan.code);
     setAddBusy(false);
     if (!r.ok) {
+      if (r.reason === 'mfa_required') setServerAskedCode(true);
+      // A spent or wrong code cannot be retried: clear it.
+      if (r.reason === 'invalid_code') setStepUpCode('');
       setAddError(r.error || 'Could not start two-factor setup.');
       return;
     }
+    setStepUpCode('');
     setDeviceId(r.deviceId || '');
     setSecret(r.secret || '');
     setOtpauthUri(r.otpauthUri || '');
@@ -606,6 +626,21 @@ export default function TwoFactorPage({ onDeviceConfirmed, reenrollMode = false
                     A friendly label so you can tell your devices apart.
                   </p>
                 </div>
+                {stepUpRequired && (
+                  <div className="space-y-1.5">
+                    <Label htmlFor="mfa-stepup-code">Current code</Label>
+                    <Input
+                      id="mfa-stepup-code"
+                      autoComplete="one-time-code"
+                      placeholder="6-digit code or recovery code"
+                      value={stepUpCode}
+                      onChange={(e) => setStepUpCode(e.target.value)}
+                    />
+                    <p className="text-xs text-muted-foreground">
+                      From one of your existing authenticator apps, or a recovery code.
+                    </p>
+                  </div>
+                )}
                 <div className="flex items-center gap-2">
                   <Button type="submit" disabled={addBusy}>
                     {addBusy ? (

package/template/frontend/vite.config.js

@@ -21,6 +21,26 @@ function devCsp() {
   };
 }
 
+/**
+ * `Referrer-Policy: no-referrer` on the email-change confirmation page (KI #14), for
+ * `npm run dev` and `npm run preview`. The page also sets the same policy with a <meta> tag
+ * while it is mounted, and its token is in the URL fragment (never sent in a Referer). In
+ * production, send this header for `/confirm-email` from whatever serves the built app.
+ */
+function confirmEmailNoReferrer() {
+  const setHeader = (req, res, next) => {
+    if ((req.url ?? '').split(/[?#]/)[0] === '/confirm-email') {
+      res.setHeader('Referrer-Policy', 'no-referrer');
+    }
+    next();
+  };
+  return {
+    name: 'astram-confirm-email-no-referrer',
+    configureServer: (server) => server.middlewares.use(setHeader),
+    configurePreviewServer: (server) => server.middlewares.use(setHeader),
+  };
+}
+
 /**
  * __APP_NAME__ frontend — Vite config (shadcn/ui + Tailwind v4).
  *
@@ -29,7 +49,7 @@ function devCsp() {
  * `/auth/login`. `@` aliases `src/` (the shadcn import convention).
  */
 export default defineConfig({
-  plugins: [react(), tailwindcss(), devCsp()],
+  plugins: [react(), tailwindcss(), devCsp(), confirmEmailNoReferrer()],
   resolve: {
     alias: {
       '@': fileURLToPath(new URL('./src', import.meta.url)),

package/template/server/_env.example

@@ -60,6 +60,14 @@ NODE_ENV=development
 # TRUST_PROXY (above) is set, so the client IP is real rather than the proxy's.
 # LOGIN_IP_MAX_FAILURES=50
 # LOGIN_IP_WINDOW_MS=900000
+#
+# Public URLs of your frontend's reset-password and confirm-email pages; the framework mails
+# `<RESET_LINK_BASE_URL>?token=…` and `<EMAIL_CHANGE_LINK_BASE_URL>#t=…`. Defaults point at the
+# Vite dev server (http://localhost:5173/...). Outside NODE_ENV development/test, with an
+# emailSender, boot FAILS if either is unset or points at localhost/127.0.0.1/::1/0.0.0.0.
+# ShieldModule.forRoot({ emailChangeLinkBaseUrl }) wins over EMAIL_CHANGE_LINK_BASE_URL.
+# RESET_LINK_BASE_URL=https://app.example.com/reset-password
+# EMAIL_CHANGE_LINK_BASE_URL=https://app.example.com/confirm-email
 
 # --- Migrations (optional; @astram/identity's migrations run automatically) ---
 # APP_MIGRATION_DIR=migrations         # your app's own migrations, run after identity's

package/template/server/eslint.config.mjs

@@ -224,6 +224,44 @@ const RAW_METHOD_RE = `/^(${RAW_METHODS.join('|')})$/`;
 const MORE_RAW_METHOD_RE = `/^(${RAW_METHODS.slice(5).join('|')})$/`;
 const RAW_METHOD_MESSAGE = `Wall: no raw driver method (${RAW_METHODS.join('/')}) in app code, however it is reached — use the RecordEngine (@astram/engine).`;
 
+/**
+ * KI #82: uuid route/body inputs go through `UuidPipe` / `uuidField` / `optionalUuidField` /
+ * `uuidArrayField` (@astram/guard). MariaDB's utf8mb4_unicode_ci matches a uuid ignoring case,
+ * trailing spaces and character width, so a raw `"<id> "` or fullwidth uuid reaches the row while
+ * every exact check in JS (own root, a Set of allowed ids, a Redis key) misses it. A uuid-NAMED
+ * input (`id`, `uuid`, `…Id(s)`, `…Uuid(s)`) is flagged when it is read without the canonicaliser.
+ *
+ * This is a NAME-BASED NUDGE, NOT A GUARANTEE. It only sees those names in those shapes: a uuid
+ * under another name (`@Param('slug')`, `@Param('target')`, `@Query('owner')`), a destructured
+ * body (`const { companyUuid } = body`), a body bound to another variable name, a value read off
+ * `req`, or a param with ANY pipe argument (`@Param('id', SomeOtherPipe)`) is not flagged. Put
+ * `UuidPipe` on EVERY uuid route param
+ * whatever its name, and a uuid helper on every uuid body/query field; a clean lint run does not
+ * prove every uuid input is canonicalised.
+ */
+const UUID_NAME_RE = '/^(id|ids|uuid|uuids|[a-z][A-Za-z0-9]*(Id|Ids|Uuid|Uuids))$/';
+const UUID_HELPERS_RE = '/^(uuidField|optionalUuidField|uuidArrayField)$/';
+const UUID_BODY_OBJECTS_RE = '/^(body|dto|b|payload|input)$/';
+const UUID_MESSAGE =
+  "Wall: a uuid route/body input goes through UuidPipe (`@Param('uuid', UuidPipe)`) or uuidField / optionalUuidField / uuidArrayField from @astram/guard — the database matches uuids ignoring case, spaces and width, so a raw one slips past exact checks.";
+const UUID_INPUTS = [
+  {
+    // @Param('uuid') / @Query('recordId') / @Body('roleUuid') with no pipe argument.
+    selector: `Decorator > CallExpression[callee.name=/^(Param|Query|Body)$/][arguments.length=1] > Literal.arguments[value=${UUID_NAME_RE}]`,
+    message: UUID_MESSAGE,
+  },
+  {
+    // @Param() — the whole params object reaches the handler unvalidated.
+    selector: "Decorator > CallExpression[callee.name='Param'][arguments.length=0]",
+    message: UUID_MESSAGE,
+  },
+  {
+    // body.companyUuid / body?.roleIds read raw (not as the first argument of a uuid helper).
+    selector: `MemberExpression[computed=false][object.name=${UUID_BODY_OBJECTS_RE}][property.name=${UUID_NAME_RE}]:not(CallExpression[callee.name=${UUID_HELPERS_RE}] > MemberExpression):not(CallExpression[callee.name=${UUID_HELPERS_RE}] > ChainExpression > MemberExpression)`,
+    message: UUID_MESSAGE,
+  },
+];
+
 /** App source files: TypeScript and plain JavaScript in every module flavour. */
 const SRC_FILES = ['src/**/*.{ts,mts,cts,js,mjs,cjs}'];
 const COMPOSITION_ROOT = ['src/app.module.ts', 'src/main.ts'];
@@ -315,6 +353,7 @@ export default tseslint.config(
         ...INTERNAL_DYNAMIC,
         ...DEEP_PATHS,
         ...NON_STATIC_SPECIFIERS,
+        ...UUID_INPUTS,
         // The banned framework names however they are reached: `ns.SHIELD_DB_POOL`,
         // `require('@astram/guard').SHIELD_DB_POOL`, `(await import('@astram/engine')).TableRegistry`.
         // (A named import from the listed package is already reported by no-restricted-imports,

package/template/server/package.json

@@ -21,10 +21,10 @@
   },
   "dependencies": {
     "@astram/core": "^1.4.0",
-    "@astram/engine": "^0.5.1",
-    "@astram/guard": "^0.10.0",
-    "@astram/guide": "^0.2.2",
-    "@astram/identity": "^0.7.0",
+    "@astram/engine": "^0.5.2",
+    "@astram/guard": "^0.11.0",
+    "@astram/guide": "^0.2.3",
+    "@astram/identity": "^0.8.0",
     "@astram/migrate": "^0.3.2",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",

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

@@ -37,7 +37,9 @@ import { DemoController } from './health/demo.controller';
  *      `.env.example`) — auth needs a real MariaDB + Redis and a refresh HMAC key.
  *   3. Create a user in the `shield_identity.identity_credential` table.
  *   4. Outside development/test (`NODE_ENV`), `auth: true` also requires an
- *      `emailSender` (or `emailSender: 'disabled'`) — otherwise boot fails closed.
+ *      `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`).
  * 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.)