@astram/guard 0.10.2 → 0.11.1

package/dist/auth/email-change-messages.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_YOU_SENTENCE = exports.DEFAULT_EMAIL_CHANGE_LINK_BASE_URL = exports.EMAIL_CHANGE_TTL_MS = void 0;
+exports.emailChangeLink = emailChangeLink;
+exports.confirmEmailChangeMessage = confirmEmailChangeMessage;
+exports.emailChangedNoticeMessage = emailChangedNoticeMessage;
+/** Email-change token time-to-live: 30 minutes (same as a password reset). */
+exports.EMAIL_CHANGE_TTL_MS = 30 * 60 * 1000;
+/** The default confirm-page base (a dev Vite origin), like the reset-link default. */
+exports.DEFAULT_EMAIL_CHANGE_LINK_BASE_URL = 'http://localhost:5173/confirm-email';
+/**
+ * What to do if the change was not the owner's (A10, reworded in Phase 13 #2a). After an
+ * attacker's change the login hint may have moved with the email (it follows when it equalled the
+ * old address), so a reset from the login page may not reach the victim: the administrator comes
+ * first, and the reset advice is qualified rather than given as the remedy.
+ */
+exports.NOT_YOU_SENTENCE = "If this wasn't you, contact your administrator immediately. Your sign-in email may have " +
+    'changed too, so a password reset from the login page may not reach you.';
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/** The confirm link: the token rides in the fragment, never the query (A4). */
+function emailChangeLink(base, rawToken) {
+    return `${base}#t=${rawToken}`;
+}
+function confirmEmailChangeMessage(to, link) {
+    const minutes = Math.round(exports.EMAIL_CHANGE_TTL_MS / 60000);
+    return {
+        to,
+        subject: 'Confirm your new email address',
+        text: 'You asked to use this address for your account. Confirm it by opening this link ' +
+            `within ${minutes} minutes: ${link}\n\n` +
+            'If you did not ask for this, ignore this message; nothing changes.',
+        html: '<p>You asked to use this address for your account. Confirm it by opening this link ' +
+            `within ${minutes} minutes:</p>` +
+            `<p><a href="${escapeHtml(link)}" rel="noreferrer">${escapeHtml(link)}</a></p>` +
+            '<p>If you did not ask for this, ignore this message; nothing changes.</p>',
+    };
+}
+function emailChangedNoticeMessage(to, maskedNewEmail, atMs) {
+    const when = new Date(atMs)
+        .toISOString()
+        .replace('T', ' ')
+        .replace(/\.\d+Z$/, ' UTC');
+    const what = `The email address on your account was changed to ${maskedNewEmail} at ${when}.`;
+    return {
+        to,
+        subject: 'Your account email address was changed',
+        text: `${what}\n\n${exports.NOT_YOU_SENTENCE}`,
+        html: `<p>${escapeHtml(what)}</p><p>${escapeHtml(exports.NOT_YOU_SENTENCE)}</p>`,
+    };
+}

package/dist/auth/link-base-url.d.ts

@@ -0,0 +1,24 @@
+/** The default reset-page base (a dev Vite origin). */
+export declare const DEFAULT_RESET_LINK_BASE_URL = "http://localhost:5173/reset-password";
+export interface AuthLinkBaseUrls {
+    readonly resetLinkBaseUrl: string;
+    readonly emailChangeLinkBaseUrl: string;
+}
+export interface ResolveAuthLinkBaseUrlsInput {
+    /** The raw environment (`NODE_ENV`, `RESET_LINK_BASE_URL`, `EMAIL_CHANGE_LINK_BASE_URL`). */
+    readonly env: NodeJS.ProcessEnv;
+    /** `ShieldModule.forRoot({ emailChangeLinkBaseUrl })`. */
+    readonly emailChangeLinkBaseUrlOption?: string | undefined;
+    /**
+     * `true` when no app-supplied sender exists: `emailSender: 'disabled'` (nothing is delivered) or
+     * omitted (outside development/test the email-sender boot rule already fails the boot with its
+     * own error; in development/test the link rule is off anyway).
+     */
+    readonly mailDisabled: boolean;
+}
+/**
+ * Resolve both link bases and apply the boot rule. Throws (boot fails) outside development/test
+ * when a base is unset or local and mail is not `'disabled'`.
+ */
+export declare function resolveAuthLinkBaseUrls(input: ResolveAuthLinkBaseUrlsInput): AuthLinkBaseUrls;
+//# sourceMappingURL=link-base-url.d.ts.map

package/dist/auth/link-base-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-base-url.d.ts","sourceRoot":"","sources":["../../src/auth/link-base-url.ts"],"names":[],"mappings":"AAmBA,uDAAuD;AACvD,eAAO,MAAM,2BAA2B,yCAAyC,CAAC;AAElF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,4BAA4B;IAC3C,6FAA6F;IAC7F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAmCD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,GAAG,gBAAgB,CAgC7F"}

package/dist/auth/link-base-url.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RESET_LINK_BASE_URL = void 0;
+exports.resolveAuthLinkBaseUrls = resolveAuthLinkBaseUrls;
+/**
+ * The two link bases the framework mails (security hardening Phase 13 #1):
+ *  - the password-reset link `${RESET_LINK_BASE_URL}?token=…` (`POST /auth/forgot-password`);
+ *  - the email-change confirm link `${emailChangeLinkBaseUrl}#t=…` (`PATCH /account/profile`).
+ *
+ * Precedence: the `emailChangeLinkBaseUrl` option > `EMAIL_CHANGE_LINK_BASE_URL` > dev default;
+ * the reset link: `RESET_LINK_BASE_URL` > dev default. A blank value counts as unset.
+ *
+ * Boot rule (fail closed): outside `NODE_ENV` development/test (raw value, unset is NOT dev), with
+ * a mail sender, each base must be set, parse as an `http:`/`https:` URL and name a host that is
+ * not loopback/unspecified (`localhost`, `*.localhost`, `127.0.0.0/8`, `::1`, `0.0.0.0`, `::`).
+ * Otherwise auth composition throws, naming the variable(s) — never the configured value (it may
+ * carry credentials). `emailSender: 'disabled'` skips the rule: the no-op sender delivers nothing,
+ * so no link can reach a user (an omitted sender fails the boot earlier, see `auth.module.ts`).
+ * `https:` is not required (the reset path never required it).
+ */
+const app_config_js_1 = require("../config/app-config.js");
+const email_change_messages_js_1 = require("./email-change-messages.js");
+/** The default reset-page base (a dev Vite origin). */
+exports.DEFAULT_RESET_LINK_BASE_URL = 'http://localhost:5173/reset-password';
+function present(value) {
+    return value !== undefined && value.trim() !== '' ? value.trim() : undefined;
+}
+function isLoopbackOrUnspecifiedHost(hostname) {
+    const host = hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/gu, '')
+        .replace(/\.$/u, '');
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    if (host === '0.0.0.0' || host === '::' || host === '::1')
+        return true;
+    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/u.test(host))
+        return true;
+    // IPv4-mapped loopback/unspecified (`::ffff:127.0.0.1` normalises to `::ffff:7f00:1`).
+    if (/^::ffff:(7f[0-9a-f]{2}:[0-9a-f]{1,4}|0:0)$/u.test(host))
+        return true;
+    return false;
+}
+/** Why a production link base is unusable, or `null` when it is fine. */
+function problemWith(value) {
+    if (value === undefined)
+        return 'is not set';
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'is not a valid URL';
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return 'is not an http(s) URL';
+    if (isLoopbackOrUnspecifiedHost(url.hostname)) {
+        return 'points at a loopback/unspecified host (localhost, 127.0.0.1, ::1, 0.0.0.0)';
+    }
+    return null;
+}
+/**
+ * Resolve both link bases and apply the boot rule. Throws (boot fails) outside development/test
+ * when a base is unset or local and mail is not `'disabled'`.
+ */
+function resolveAuthLinkBaseUrls(input) {
+    const resetConfigured = present(input.env.RESET_LINK_BASE_URL);
+    const optionConfigured = present(input.emailChangeLinkBaseUrlOption);
+    const emailChangeConfigured = optionConfigured ?? present(input.env.EMAIL_CHANGE_LINK_BASE_URL);
+    if (!input.mailDisabled && !(0, app_config_js_1.isDevOrTestNodeEnv)(input.env.NODE_ENV)) {
+        const problems = [];
+        const resetProblem = problemWith(resetConfigured);
+        if (resetProblem)
+            problems.push(`RESET_LINK_BASE_URL ${resetProblem}`);
+        const changeProblem = problemWith(emailChangeConfigured);
+        if (changeProblem) {
+            const name = optionConfigured
+                ? 'the emailChangeLinkBaseUrl option'
+                : 'EMAIL_CHANGE_LINK_BASE_URL (or the emailChangeLinkBaseUrl option)';
+            problems.push(`${name} ${changeProblem}`);
+        }
+        if (problems.length > 0) {
+            const nodeEnv = input.env.NODE_ENV;
+            throw new Error('Astram auth composition: the mailed password-reset and email-change links need a ' +
+                `public base URL when NODE_ENV is not 'development' or 'test' (got: ${nodeEnv === undefined ? 'unset' : `'${nodeEnv}'`}): ${problems.join('; ')}. Set them to your app's /reset-password and /confirm-email ` +
+                "pages, or pass emailSender: 'disabled' if this deployment sends no email.");
+        }
+    }
+    return {
+        resetLinkBaseUrl: resetConfigured ?? exports.DEFAULT_RESET_LINK_BASE_URL,
+        emailChangeLinkBaseUrl: emailChangeConfigured ?? email_change_messages_js_1.DEFAULT_EMAIL_CHANGE_LINK_BASE_URL,
+    };
+}

package/dist/auth/ports/email-address-changer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * EmailAddressChanger — the ONE place a user's email address is read for, and written by, an email
+ * change (security hardening Phase 12, KI #14). Framework default `MariaDbEmailAddressChanger` over
+ * `shield_app.users` + `shield_identity.identity_credential`. Used by guard's self-service routes
+ * and constructed by `@astram/identity` for the administrator path, so the two cannot drift.
+ */
+/** A user's address as stored, for the request-time checks. */
+export interface CurrentEmail {
+    /** `users.u_email` exactly as stored (may be null). */
+    readonly email: string | null;
+    /** `users.u_status === 'active'`. */
+    readonly active: boolean;
+    /** The stored address is collation-equal (`utf8mb4_unicode_ci`) to the candidate. */
+    readonly sameAsCandidate: boolean;
+}
+/** A parameterized statement on the change's own transaction connection. */
+export type TransactionQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
+export interface EmailChangeRequest {
+    readonly principalId: string;
+    /** The CANONICAL new address (`canonicalEmail`, A5). */
+    readonly newEmail: string;
+    /**
+     * When given, the change is refused (`stale`) unless the stored `u_email` still equals it
+     * EXACTLY (A3: an admin or another flow changed it after the request). Omit on the admin path.
+     */
+    readonly expectedOldEmail?: string | null;
+    /** Refuse (`inactive`) unless `u_status = 'active'` (the self-service confirm). */
+    readonly requireActive?: boolean;
+    /**
+     * Runs on the change's transaction AFTER the writes and BEFORE commit (e.g. the admin path's
+     * audit row): a throw rolls the whole change back (fail closed).
+     */
+    readonly withinTransaction?: (query: TransactionQuery, result: {
+        readonly oldEmail: string | null;
+        readonly hintMoved: boolean;
+    }) => Promise<void>;
+}
+export type EmailChangeOutcome = {
+    readonly status: 'changed';
+    readonly oldEmail: string | null;
+    readonly hintMoved: boolean;
+}
+/** Another user's `u_email` or another principal's login hint is collation-equal to it. */
+ | {
+    readonly status: 'unavailable';
+} | {
+    readonly status: 'not_found';
+} | {
+    readonly status: 'inactive';
+} | {
+    readonly status: 'stale';
+};
+export interface EmailAddressChanger {
+    /** The user's stored address and whether it already equals `candidate`; `null` = no such user. */
+    readCurrent(principalId: string, candidate: string): Promise<CurrentEmail | null>;
+    /**
+     * Apply an email change in ONE transaction: lock the user row and the user's credential rows,
+     * refuse a collision (another user's `u_email`, another principal's `ic_identity_hint`;
+     * collation-equal, locked reads, self excluded), write `u_email`, move `ic_identity_hint` when it
+     * equalled the OLD email (a username hint is untouched), and burn the user's pending
+     * email-change tokens. Throws on a store error (caller → 503).
+     */
+    change(request: EmailChangeRequest): Promise<EmailChangeOutcome>;
+}
+//# sourceMappingURL=email-address-changer.d.ts.map

package/dist/auth/ports/email-address-changer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-address-changer.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/email-address-changer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAC3B,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,KACtE,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAC/F,2FAA2F;GACzF;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAClF;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClE"}

package/dist/auth/ports/email-address-changer.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * EmailAddressChanger — the ONE place a user's email address is read for, and written by, an email
+ * change (security hardening Phase 12, KI #14). Framework default `MariaDbEmailAddressChanger` over
+ * `shield_app.users` + `shield_identity.identity_credential`. Used by guard's self-service routes
+ * and constructed by `@astram/identity` for the administrator path, so the two cannot drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/email-change-token-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * EmailChangeTokenStore — persists single-use, TTL'd self-service email-change tokens (security
+ * hardening Phase 12, KI #14). The framework hashes the raw token (SHA-256) before it reaches this
+ * store; the store never sees the raw token.
+ *
+ * A token binds (A3) the user, the CANONICAL new address, the email the user had at request time
+ * and the requesting session. One pending change per user (A2): `issue` invalidates every earlier
+ * unconsumed token of the principal. `consume` is atomic and single-use: it returns the binding iff
+ * the token is unexpired AND unconsumed, and marks it consumed in the same statement.
+ */
+/** What an issued token binds (A3). */
+export interface EmailChangeTokenBinding {
+    readonly principalId: string;
+    /** The canonical new address (trim → NFKC → lower-case, A5). */
+    readonly newEmail: string;
+    /** `users.u_email` when the change was requested (confirm refuses if it changed since). */
+    readonly oldEmail: string | null;
+    /** The requesting session (kept on confirm; every other session is revoked, A7). */
+    readonly sessionId: string;
+    /**
+     * The requesting session's tenant. The confirm step may run with no session, so its audit rows
+     * (`account.email_changed` / `account.email_change_refused`) take the tenant from here
+     * (`audit_log.al_tenant_id` is NOT NULL).
+     */
+    readonly tenantId: string;
+}
+export interface EmailChangeTokenIssue extends EmailChangeTokenBinding {
+    readonly tokenHash: string;
+    readonly expiresAtMs: number;
+}
+export interface EmailChangeTokenStore {
+    /** Delete expired rows, invalidate the principal's other pending tokens, insert this one. */
+    issue(token: EmailChangeTokenIssue): Promise<void>;
+    /** Atomically consume (single use); `null` for unknown / expired / already consumed. */
+    consume(tokenHash: string): Promise<EmailChangeTokenBinding | null>;
+    /** Burn every pending token of the principal (password reset/change, admin change, confirm). */
+    invalidateAllForPrincipal(principalId: string): Promise<void>;
+}
+//# sourceMappingURL=email-change-token-store.d.ts.map

package/dist/auth/ports/email-change-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-change-token-store.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/email-change-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uCAAuC;AACvC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,KAAK,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,wFAAwF;IACxF,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IACpE,gGAAgG;IAChG,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D"}

package/dist/auth/ports/email-change-token-store.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * EmailChangeTokenStore — persists single-use, TTL'd self-service email-change tokens (security
+ * hardening Phase 12, KI #14). The framework hashes the raw token (SHA-256) before it reaches this
+ * store; the store never sees the raw token.
+ *
+ * A token binds (A3) the user, the CANONICAL new address, the email the user had at request time
+ * and the requesting session. One pending change per user (A2): `issue` invalidates every earlier
+ * unconsumed token of the principal. `consume` is atomic and single-use: it returns the binding iff
+ * the token is unexpired AND unconsumed, and marks it consumed in the same statement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/tokens.d.ts

@@ -82,6 +82,43 @@ export declare const SHIELD_CREDENTIAL_WRITER: unique symbol;
  * never the raw token). Consumed by forgot-password + reset-password.
  */
 export declare const SHIELD_RESET_TOKEN_STORE: unique symbol;
+/**
+ * The `EmailChangeTokenStore` (guard port, `../auth/ports/email-change-token-store.ts`) — the
+ * single-use, TTL'd self-service email-change token store (Phase 12, KI #14). Framework default
+ * `MariaDbEmailChangeTokenStore` over `shield_identity.email_change_token`. Consumed by
+ * `PATCH /account/profile` (issue), `POST /auth/confirm-email` (consume), and invalidated by a
+ * password reset / change (A8). Absent → an email change answers 501.
+ */
+export declare const SHIELD_EMAIL_CHANGE_TOKEN_STORE: unique symbol;
+/**
+ * The `EmailAddressChanger` (guard port, `../auth/ports/email-address-changer.ts`) — reads a
+ * user's stored address for the request checks and applies a confirmed change in ONE transaction
+ * (collision refusal + login-hint follow). Framework default `MariaDbEmailAddressChanger` over
+ * {@link SHIELD_DB_POOL}. Phase 12, KI #14.
+ */
+export declare const SHIELD_EMAIL_ADDRESS_CHANGER: unique symbol;
+/**
+ * The email-change confirm-link base URL (a plain `string`, `ShieldModule.forRoot({
+ * emailChangeLinkBaseUrl })` > env `EMAIL_CHANGE_LINK_BASE_URL` > dev default
+ * `http://localhost:5173/confirm-email`; production boot rule in `link-base-url.ts`). The link is
+ * `${base}#t=<rawToken>` — the token rides in the FRAGMENT, never the query (A4), so it is not
+ * sent to the server that serves the page nor leaked through a Referer.
+ */
+export declare const SHIELD_EMAIL_CHANGE_LINK_BASE_URL: unique symbol;
+/**
+ * The per-account email-change REQUEST limiter (Phase 12) — keyed `email-change:pid:<principalId>`,
+ * 3 per 60-min window, so `PATCH /account/profile` cannot be used to spam an inbox. Counted
+ * (`consume`, fail closed → 503) after the current password verified; 429 when exhausted.
+ */
+export declare const SHIELD_EMAIL_CHANGE_LIMITER: unique symbol;
+/**
+ * The `POST /auth/confirm-email` per-client-IP limiter (Phase 12, A6) — keyed
+ * `confirm-email:ip:<ip>`, 10 per 15-min window, like reset-password. Every attempt is counted
+ * (`consume`, fail closed → 503), a successful confirm gives its attempt back; 429 when exhausted.
+ * ENFORCED ONLY with an explicit Express `trust proxy` (`TrustProxyBootCheck`), else OFF — a shared
+ * proxy IP would otherwise lock every user out.
+ */
+export declare const SHIELD_CONFIRM_EMAIL_LIMITER: unique symbol;
 /**
  * The `EmailSender` (guard port, `../auth/ports/email-sender.ts`) — the delivery
  * seam (SendGrid/SMTP/test capturer). The framework builds the message; the
@@ -128,7 +165,8 @@ export declare const SHIELD_SESSION_SWEEPER: unique symbol;
  * composes the emailed reset link as `${base}?token=<rawToken>` so the
  * {@link SHIELD_EMAIL_SENDER} seam stays a dumb delivery channel (no URL/token
  * logic). Bound app-wide by `AuthModule` from the environment
- * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`). Consumed
+ * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`; outside
+ * development/test an unset or loopback value fails the boot, see `link-base-url.ts`). Consumed
  * by `POST /auth/forgot-password`.
  */
 export declare const SHIELD_RESET_LINK_BASE_URL: unique symbol;

package/dist/auth/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAW3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAU7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,eAA4C,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,eAAwC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAW3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,eAA4C,CAAC;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,eAAyC,CAAC;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,eAA8C,CAAC;AAE7F;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,eAAwC,CAAC;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,eAAyC,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAU7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,eAA4C,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,eAAwC,CAAC"}

package/dist/auth/tokens.js

@@ -23,7 +23,7 @@
  * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHIELD_SESSION_RESTRICTIONS = exports.SHIELD_PERMISSION_VERSION_CACHE = exports.SHIELD_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_LOGIN_TOTP_VERIFIER = exports.SHIELD_MFA_STEP_UP = exports.SHIELD_MFA_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_IP_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_MEMBERSHIP_CHECKER = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
+exports.SHIELD_SESSION_RESTRICTIONS = exports.SHIELD_PERMISSION_VERSION_CACHE = exports.SHIELD_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_LOGIN_TOTP_VERIFIER = exports.SHIELD_MFA_STEP_UP = exports.SHIELD_MFA_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_IP_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_MEMBERSHIP_CHECKER = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_CONFIRM_EMAIL_LIMITER = exports.SHIELD_EMAIL_CHANGE_LIMITER = exports.SHIELD_EMAIL_CHANGE_LINK_BASE_URL = exports.SHIELD_EMAIL_ADDRESS_CHANGER = exports.SHIELD_EMAIL_CHANGE_TOKEN_STORE = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
 var argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
 Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
 /**
@@ -94,6 +94,43 @@ exports.SHIELD_CREDENTIAL_WRITER = Symbol('SHIELD_CREDENTIAL_WRITER');
  * never the raw token). Consumed by forgot-password + reset-password.
  */
 exports.SHIELD_RESET_TOKEN_STORE = Symbol('SHIELD_RESET_TOKEN_STORE');
+/**
+ * The `EmailChangeTokenStore` (guard port, `../auth/ports/email-change-token-store.ts`) — the
+ * single-use, TTL'd self-service email-change token store (Phase 12, KI #14). Framework default
+ * `MariaDbEmailChangeTokenStore` over `shield_identity.email_change_token`. Consumed by
+ * `PATCH /account/profile` (issue), `POST /auth/confirm-email` (consume), and invalidated by a
+ * password reset / change (A8). Absent → an email change answers 501.
+ */
+exports.SHIELD_EMAIL_CHANGE_TOKEN_STORE = Symbol('SHIELD_EMAIL_CHANGE_TOKEN_STORE');
+/**
+ * The `EmailAddressChanger` (guard port, `../auth/ports/email-address-changer.ts`) — reads a
+ * user's stored address for the request checks and applies a confirmed change in ONE transaction
+ * (collision refusal + login-hint follow). Framework default `MariaDbEmailAddressChanger` over
+ * {@link SHIELD_DB_POOL}. Phase 12, KI #14.
+ */
+exports.SHIELD_EMAIL_ADDRESS_CHANGER = Symbol('SHIELD_EMAIL_ADDRESS_CHANGER');
+/**
+ * The email-change confirm-link base URL (a plain `string`, `ShieldModule.forRoot({
+ * emailChangeLinkBaseUrl })` > env `EMAIL_CHANGE_LINK_BASE_URL` > dev default
+ * `http://localhost:5173/confirm-email`; production boot rule in `link-base-url.ts`). The link is
+ * `${base}#t=<rawToken>` — the token rides in the FRAGMENT, never the query (A4), so it is not
+ * sent to the server that serves the page nor leaked through a Referer.
+ */
+exports.SHIELD_EMAIL_CHANGE_LINK_BASE_URL = Symbol('SHIELD_EMAIL_CHANGE_LINK_BASE_URL');
+/**
+ * The per-account email-change REQUEST limiter (Phase 12) — keyed `email-change:pid:<principalId>`,
+ * 3 per 60-min window, so `PATCH /account/profile` cannot be used to spam an inbox. Counted
+ * (`consume`, fail closed → 503) after the current password verified; 429 when exhausted.
+ */
+exports.SHIELD_EMAIL_CHANGE_LIMITER = Symbol('SHIELD_EMAIL_CHANGE_LIMITER');
+/**
+ * The `POST /auth/confirm-email` per-client-IP limiter (Phase 12, A6) — keyed
+ * `confirm-email:ip:<ip>`, 10 per 15-min window, like reset-password. Every attempt is counted
+ * (`consume`, fail closed → 503), a successful confirm gives its attempt back; 429 when exhausted.
+ * ENFORCED ONLY with an explicit Express `trust proxy` (`TrustProxyBootCheck`), else OFF — a shared
+ * proxy IP would otherwise lock every user out.
+ */
+exports.SHIELD_CONFIRM_EMAIL_LIMITER = Symbol('SHIELD_CONFIRM_EMAIL_LIMITER');
 /**
  * The `EmailSender` (guard port, `../auth/ports/email-sender.ts`) — the delivery
  * seam (SendGrid/SMTP/test capturer). The framework builds the message; the
@@ -140,7 +177,8 @@ exports.SHIELD_SESSION_SWEEPER = Symbol('SHIELD_SESSION_SWEEPER');
  * composes the emailed reset link as `${base}?token=<rawToken>` so the
  * {@link SHIELD_EMAIL_SENDER} seam stays a dumb delivery channel (no URL/token
  * logic). Bound app-wide by `AuthModule` from the environment
- * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`). Consumed
+ * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`; outside
+ * development/test an unset or loopback value fails the boot, see `link-base-url.ts`). Consumed
  * by `POST /auth/forgot-password`.
  */
 exports.SHIELD_RESET_LINK_BASE_URL = Symbol('SHIELD_RESET_LINK_BASE_URL');

package/dist/authentication/mariadb-email-address-changer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MariaDbEmailAddressChanger — the framework-default {@link EmailAddressChanger} (security hardening
+ * Phase 12, KI #14) over `shield_app.users`, `shield_identity.identity_credential` and
+ * `shield_identity.email_change_token`. Guard's `POST /auth/confirm-email` uses it over the auth
+ * pool; `@astram/identity`'s administrator path constructs it over its authz pool, so the two
+ * paths share one collision rule and one login-hint rule.
+ *
+ * `change` (one MariaDB transaction, lock-then-recheck):
+ *   0. `GET_LOCK('shield_email_change')` — serialises email changes. `u_email` has no index, so the
+ *      locked collision read below locks a scan of `users`; without the named lock two concurrent
+ *      changes would deadlock on each other's row locks.
+ *   1. lock the user row (`FOR UPDATE`); refuse `not_found`, `inactive` (when required), `stale`
+ *      (stored email ≠ the expected old one, exact compare — A3);
+ *   2. refuse `unavailable` when another user's `u_email` or another principal's login hint is
+ *      collation-equal (`utf8mb4_unicode_ci`: case-, accent- and trailing-space-insensitive) to
+ *      the new address — locked reads, self excluded;
+ *   3. lock the user's own credential rows; write `u_email`;
+ *   4. login-hint follow: `ic_identity_hint` (the PK) is updated IN PLACE to the new address when it
+ *      equalled the OLD email (collation-equal); a username hint matches nothing and stays;
+ *   5. burn the user's pending email-change tokens; run `withinTransaction`; commit.
+ * Every query is parameterized; addresses are compared by the column collation in SQL.
+ */
+import type { Pool } from 'mariadb';
+import type { CurrentEmail, EmailAddressChanger, EmailChangeOutcome, EmailChangeRequest } from '../auth/ports/email-address-changer.js';
+export declare class MariaDbEmailAddressChanger implements EmailAddressChanger {
+    private readonly pool;
+    private readonly now;
+    constructor(pool: Pool, now?: () => number);
+    readCurrent(principalId: string, candidate: string): Promise<CurrentEmail | null>;
+    change(request: EmailChangeRequest): Promise<EmailChangeOutcome>;
+    private changeLocked;
+}
+//# sourceMappingURL=mariadb-email-address-changer.d.ts.map

package/dist/authentication/mariadb-email-address-changer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-email-address-changer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-email-address-changer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,SAAS,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,wCAAwC,CAAC;AAWhD,qBAAa,0BAA2B,YAAW,mBAAmB;IAElE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,MAAM,MAAiB;IAGzC,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAejF,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;YA6BxD,YAAY;CA+D3B"}

package/dist/authentication/mariadb-email-address-changer.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbEmailAddressChanger = void 0;
+/** Seconds to wait for the email-change named lock before giving up (caller → 503). */
+const LOCK_TIMEOUT_S = 10;
+class MariaDbEmailAddressChanger {
+    pool;
+    now;
+    constructor(pool, now = Date.now) {
+        this.pool = pool;
+        this.now = now;
+    }
+    async readCurrent(principalId, candidate) {
+        const rows = (await this.pool.query(`SELECT u_email, u_status, (u_email = ?) AS same_as_candidate
+         FROM \`shield_app\`.\`users\` WHERE u_uuid = ? LIMIT 1`, [candidate, principalId]));
+        const row = rows[0];
+        if (row === undefined)
+            return null;
+        return {
+            email: row.u_email ?? null,
+            active: row.u_status === 'active',
+            sameAsCandidate: Number(row.same_as_candidate ?? 0) === 1,
+        };
+    }
+    async change(request) {
+        const conn = await this.pool.getConnection();
+        let locked = false;
+        try {
+            const got = (await conn.query("SELECT GET_LOCK('shield_email_change', ?) AS got", [
+                LOCK_TIMEOUT_S,
+            ]));
+            if (Number(got[0]?.got ?? 0) !== 1)
+                throw new Error('email change lock unavailable');
+            locked = true;
+            await conn.beginTransaction();
+            try {
+                const outcome = await this.changeLocked(conn, request);
+                if (outcome.status === 'changed')
+                    await conn.commit();
+                else
+                    await conn.rollback();
+                return outcome;
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+        }
+        finally {
+            if (locked) {
+                await conn
+                    .query("SELECT RELEASE_LOCK('shield_email_change') AS released")
+                    .catch(() => undefined);
+            }
+            conn.release();
+        }
+    }
+    async changeLocked(conn, request) {
+        const { principalId, newEmail } = request;
+        const self = (await conn.query('SELECT u_email, u_status FROM `shield_app`.`users` WHERE u_uuid = ? FOR UPDATE', [principalId]));
+        const row = self[0];
+        if (row === undefined)
+            return { status: 'not_found' };
+        if (request.requireActive === true && row.u_status !== 'active')
+            return { status: 'inactive' };
+        const oldEmail = row.u_email ?? null;
+        if (request.expectedOldEmail !== undefined && oldEmail !== request.expectedOldEmail) {
+            return { status: 'stale' };
+        }
+        const otherUser = (await conn.query('SELECT u_uuid FROM `shield_app`.`users` WHERE u_email = ? AND u_uuid <> ? LIMIT 1 FOR UPDATE', [newEmail, principalId]));
+        if (otherUser.length > 0)
+            return { status: 'unavailable' };
+        const hintOwners = (await conn.query('SELECT ic_principal_id FROM `shield_identity`.`identity_credential` WHERE ic_identity_hint = ? FOR UPDATE', [newEmail]));
+        if (hintOwners.some((h) => h.ic_principal_id !== principalId))
+            return { status: 'unavailable' };
+        const selfAlreadyHasNewHint = hintOwners.length > 0;
+        await conn.query('SELECT ic_identity_hint FROM `shield_identity`.`identity_credential` WHERE ic_principal_id = ? FOR UPDATE', [principalId]);
+        await conn.query('UPDATE `shield_app`.`users` SET u_email = ? WHERE u_uuid = ?', [
+            newEmail,
+            principalId,
+        ]);
+        let hintMoved = false;
+        if (oldEmail !== null && oldEmail !== '' && !selfAlreadyHasNewHint) {
+            const moved = (await conn.query(`UPDATE \`shield_identity\`.\`identity_credential\`
+            SET ic_identity_hint = ?, ic_updated_at_ms = ?
+          WHERE ic_principal_id = ? AND ic_identity_hint = ?`, [newEmail, this.now(), principalId, oldEmail]));
+            hintMoved = moved.affectedRows > 0;
+        }
+        await conn.query(`UPDATE \`shield_identity\`.\`email_change_token\` SET ect_consumed_at_ms = ?
+        WHERE ect_principal_id = ? AND ect_consumed_at_ms IS NULL`, [this.now(), principalId]);
+        if (request.withinTransaction !== undefined) {
+            await request.withinTransaction((sql, params) => conn.query(sql, params ?? []), { oldEmail, hintMoved });
+        }
+        return { status: 'changed', oldEmail, hintMoved };
+    }
+}
+exports.MariaDbEmailAddressChanger = MariaDbEmailAddressChanger;

package/dist/authentication/mariadb-email-change-token-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MariaDbEmailChangeTokenStore — the framework-DEFAULT {@link EmailChangeTokenStore} (security
+ * hardening Phase 12, KI #14), over `shield_identity`.`email_change_token` (identity migration
+ * `1710000000020`). The framework hashes the raw token (SHA-256) BEFORE it reaches this store.
+ *
+ *  - `issue` runs ONE transaction: it locks the user row (`shield_app.users ... FOR UPDATE`) so two
+ *    concurrent requests of one user serialise, deletes expired rows (A11), invalidates the user's
+ *    pending tokens (A2: one pending change) and inserts the new one. An unknown user rolls back.
+ *  - `consume` is ONE conditional UPDATE (`... WHERE hash = ? AND consumed IS NULL AND not expired`):
+ *    `affectedRows === 1` wins, so of two concurrent confirms exactly one gets the binding. Unknown /
+ *    expired / used all return `null` (no distinguishing throw); a store outage propagates.
+ *
+ * Every query is parameterized; the token hash is never logged nor placed in an error.
+ */
+import type { Pool } from 'mariadb';
+import type { EmailChangeTokenBinding, EmailChangeTokenIssue, EmailChangeTokenStore } from '../auth/ports/email-change-token-store.js';
+export declare class MariaDbEmailChangeTokenStore implements EmailChangeTokenStore {
+    private readonly pool;
+    private readonly now;
+    constructor(pool: Pool, now?: () => number);
+    issue(token: EmailChangeTokenIssue): Promise<void>;
+    consume(tokenHash: string): Promise<EmailChangeTokenBinding | null>;
+    invalidateAllForPrincipal(principalId: string): Promise<void>;
+}
+//# sourceMappingURL=mariadb-email-change-token-store.d.ts.map

package/dist/authentication/mariadb-email-change-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-email-change-token-store.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-email-change-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,SAAS,CAAC;AACpD,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,2CAA2C,CAAC;AAYnD,qBAAa,4BAA6B,YAAW,qBAAqB;IAEtE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,MAAM,MAAiB;IAGzC,KAAK,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2ClD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAwBnE,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpE"}