@aooth/user 0.1.18 → 0.1.20

package/dist/atscript-db.d.cts

@@ -1,4 +1,4 @@
-import { D as UserCredentials, i as NewFederatedIdentity, k as UserStoreUpdate, n as FederatedIdentityStore, o as UserStore, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity } from "./federated-identity-store-CI7Vgllp.cjs";
+import { D as UserCredentials, i as NewFederatedIdentity, k as UserStoreUpdate, n as FederatedIdentityStore, o as UserStore, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity } from "./federated-identity-store-I0uyqf2M.cjs";
 
 //#region src/atscript-db/federated-identity-store.d.ts
 /**

package/dist/atscript-db.d.mts

@@ -1,4 +1,4 @@
-import { D as UserCredentials, i as NewFederatedIdentity, k as UserStoreUpdate, n as FederatedIdentityStore, o as UserStore, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity } from "./federated-identity-store-CI7Vgllp.mjs";
+import { D as UserCredentials, i as NewFederatedIdentity, k as UserStoreUpdate, n as FederatedIdentityStore, o as UserStore, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity } from "./federated-identity-store-I0uyqf2M.mjs";
 
 //#region src/atscript-db/federated-identity-store.d.ts
 /**

package/dist/{federated-identity-store-CI7Vgllp.d.cts → federated-identity-store-I0uyqf2M.d.cts}

@@ -19,6 +19,16 @@ interface UserCredentials {
    * Absent when the user has never opted in.
    */
   trustedDevices?: TrustedDeviceRecord[];
+  /**
+   * Recognition ledger — devices that completed a login. Used purely to
+   * suppress the "new sign-in" notification; carries NO security bypass
+   * (unlike `trustedDevices`, which skips MFA). Same record shape as trust
+   * (`ip` stays unused for recognition). Capped + LRU-evicted by most-recent
+   * verification — `expiresAt` is the LRU key, since verification slides it.
+   * Managed by `UserService.{issue,add,verify,list}SeenDevice` /
+   * `revokeSeenDevices`.
+   */
+  seenDevices?: TrustedDeviceRecord[];
 }
 interface TrustedDeviceRecord {
   /** `<raw>.<sig>` — what we hand back to the consumer and what they round-trip. */
@@ -55,6 +65,14 @@ interface AccountData {
    * the invite has been accepted.
    */
   pendingInvitation?: boolean;
+  /**
+   * Correspondence address whose inbox the user PROVED ownership of — written
+   * at every inbox-proof moment (invite magic-link click, signup / recovery
+   * OTP, email-channel confirm, trusted federated profile). Auth-owned; NOT a
+   * login handle (no uniqueness, never used for account resolution). Read
+   * through `UserService.getCorrespondenceEmail`.
+   */
+  verifiedEmail?: string;
 }
 interface MfaData {
   /** Registered MFA methods */
@@ -85,12 +103,20 @@ interface UserServiceConfig {
   clock?: () => number;
   /**
    * Device-trust config. Required (with a non-empty `secret`) when any
-   * `issueTrustedDevice` / `verifyTrustedDevice` API is called; the methods
-   * throw clearly when invoked without it.
+   * `issueTrustedDevice` / `verifyTrustedDevice` API — or any `*SeenDevice`
+   * recognition API, which reuses the same secret with a domain-separated
+   * payload — is called; the methods throw clearly when invoked without it.
    */
   deviceTrust?: {
-    /** HMAC-SHA256 signing secret for trust-device tokens. */secret: string;
+    /** HMAC-SHA256 signing secret for trust-device and seen-device (recognition) tokens. */secret: string;
   };
+  /**
+   * Name of the consumer's `@aooth.user.email`-annotated column (resolved at
+   * boot by `getAoothUserHandleSpec` in arbac-moost and threaded here as
+   * plain config). When set, `getCorrespondenceEmail` prefers that column's
+   * value over `account.verifiedEmail` and the confirmed email MFA method.
+   */
+  emailField?: string;
 }
 interface PasswordConfig {
   /** Pepper string prepended to password before hashing */

package/dist/{federated-identity-store-CI7Vgllp.d.mts → federated-identity-store-I0uyqf2M.d.mts}

@@ -19,6 +19,16 @@ interface UserCredentials {
    * Absent when the user has never opted in.
    */
   trustedDevices?: TrustedDeviceRecord[];
+  /**
+   * Recognition ledger — devices that completed a login. Used purely to
+   * suppress the "new sign-in" notification; carries NO security bypass
+   * (unlike `trustedDevices`, which skips MFA). Same record shape as trust
+   * (`ip` stays unused for recognition). Capped + LRU-evicted by most-recent
+   * verification — `expiresAt` is the LRU key, since verification slides it.
+   * Managed by `UserService.{issue,add,verify,list}SeenDevice` /
+   * `revokeSeenDevices`.
+   */
+  seenDevices?: TrustedDeviceRecord[];
 }
 interface TrustedDeviceRecord {
   /** `<raw>.<sig>` — what we hand back to the consumer and what they round-trip. */
@@ -55,6 +65,14 @@ interface AccountData {
    * the invite has been accepted.
    */
   pendingInvitation?: boolean;
+  /**
+   * Correspondence address whose inbox the user PROVED ownership of — written
+   * at every inbox-proof moment (invite magic-link click, signup / recovery
+   * OTP, email-channel confirm, trusted federated profile). Auth-owned; NOT a
+   * login handle (no uniqueness, never used for account resolution). Read
+   * through `UserService.getCorrespondenceEmail`.
+   */
+  verifiedEmail?: string;
 }
 interface MfaData {
   /** Registered MFA methods */
@@ -85,12 +103,20 @@ interface UserServiceConfig {
   clock?: () => number;
   /**
    * Device-trust config. Required (with a non-empty `secret`) when any
-   * `issueTrustedDevice` / `verifyTrustedDevice` API is called; the methods
-   * throw clearly when invoked without it.
+   * `issueTrustedDevice` / `verifyTrustedDevice` API — or any `*SeenDevice`
+   * recognition API, which reuses the same secret with a domain-separated
+   * payload — is called; the methods throw clearly when invoked without it.
    */
   deviceTrust?: {
-    /** HMAC-SHA256 signing secret for trust-device tokens. */secret: string;
+    /** HMAC-SHA256 signing secret for trust-device and seen-device (recognition) tokens. */secret: string;
   };
+  /**
+   * Name of the consumer's `@aooth.user.email`-annotated column (resolved at
+   * boot by `getAoothUserHandleSpec` in arbac-moost and threaded here as
+   * plain config). When set, `getCorrespondenceEmail` prefers that column's
+   * value over `account.verifiedEmail` and the confirmed email MFA method.
+   */
+  emailField?: string;
 }
 interface PasswordConfig {
   /** Pepper string prepended to password before hashing */

package/dist/index.cjs

@@ -293,14 +293,30 @@ function resolveConfig(config) {
 			duration: config?.lockout?.duration ?? 0
 		},
 		clock: config?.clock ?? Date.now,
-		...config?.deviceTrust && { deviceTrust: config.deviceTrust }
+		...config?.deviceTrust && { deviceTrust: config.deviceTrust },
+		...config?.emailField && { emailField: config.emailField }
 	};
 }
 const DEVICE_TRUST_TOKEN_BYTES = 32;
 const DEVICE_TRUST_SEPARATOR = ".";
+const SEEN_DEVICES_DEFAULT_CAP = 5;
 function signDeviceTrust(secret, payload) {
 	return (0, node_crypto.createHmac)("sha256", secret).update(payload).digest("hex");
 }
+function trustedDevicePayload(userId, raw, ip) {
+	return `${userId}|${raw}|${ip ?? ""}`;
+}
+function seenDevicePayload(userId, raw) {
+	return `seen|${userId}|${raw}`;
+}
+function parseDeviceTrustToken(token) {
+	const sepIdx = token.lastIndexOf(DEVICE_TRUST_SEPARATOR);
+	if (sepIdx <= 0) return void 0;
+	return {
+		raw: token.slice(0, sepIdx),
+		sig: token.slice(sepIdx + 1)
+	};
+}
 function deviceTrustSafeEqual(a, b) {
 	const ab = Buffer.from(a);
 	const bb = Buffer.from(b);
@@ -451,8 +467,15 @@ var UserService = class {
 		if (!await this.store.update(id, { set: patch })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 		return this.getUser(id);
 	}
-	async activateAccount(id) {
-		if (!await this.store.update(id, { set: { account: { active: true } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
+	/**
+	* Flip the account active. `opts.verifiedEmail` lets callers that just
+	* proved an inbox (invite magic link, signup OTP) record the correspondence
+	* address in the same store write — see {@link setVerifiedEmail}.
+	*/
+	async activateAccount(id, opts) {
+		const account = { active: true };
+		if (opts?.verifiedEmail !== void 0) account.verifiedEmail = opts.verifiedEmail;
+		if (!await this.store.update(id, { set: { account } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 	}
 	async deactivateAccount(id) {
 		if (!await this.store.update(id, { set: { account: { active: false } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
@@ -638,17 +661,7 @@ var UserService = class {
 	* `addTrustedDevice`). Throws when `deviceTrust.secret` is unset.
 	*/
 	issueTrustedDevice(userId, opts) {
-		const secret = this.requireDeviceTrustSecret();
-		const raw = (0, node_crypto.randomBytes)(DEVICE_TRUST_TOKEN_BYTES).toString("hex");
-		const sig = signDeviceTrust(secret, `${userId}|${raw}|${opts.ip ?? ""}`);
-		const now = this.config.clock();
-		return {
-			token: `${raw}${DEVICE_TRUST_SEPARATOR}${sig}`,
-			...opts.ip !== void 0 && { ip: opts.ip },
-			issuedAt: now,
-			expiresAt: now + opts.ttlMs,
-			...opts.name !== void 0 && { name: opts.name }
-		};
+		return this.mintDeviceRecord((raw) => trustedDevicePayload(userId, raw, opts.ip), opts);
 	}
 	/**
 	* Append a trust record to the user's `trustedDevices` list. Read-modify-
@@ -666,11 +679,7 @@ var UserService = class {
 	* within its expiry window and whose bound IP (if any) matches.
 	*/
 	async verifyTrustedDevice(userId, token, ip) {
-		const secret = this.requireDeviceTrustSecret();
-		const sepIdx = token.lastIndexOf(DEVICE_TRUST_SEPARATOR);
-		if (sepIdx <= 0) return false;
-		const raw = token.slice(0, sepIdx);
-		if (!deviceTrustSafeEqual(token.slice(sepIdx + 1), signDeviceTrust(secret, `${userId}|${raw}|${ip ?? ""}`))) return false;
+		if (!this.checkDeviceTokenSig(token, (raw) => trustedDevicePayload(userId, raw, ip))) return false;
 		const user = await this.store.findById(userId);
 		if (!user) return false;
 		const list = user.trustedDevices ?? [];
@@ -700,6 +709,167 @@ var UserService = class {
 		if (!secret) throw new Error("UserService: deviceTrust.secret is required to use trusted-device APIs");
 		return secret;
 	}
+	/**
+	* Shared mint core for trust + recognition records — the HMAC domain is set
+	* by `payloadFor` (see `trustedDevicePayload` / `seenDevicePayload`).
+	*/
+	mintDeviceRecord(payloadFor, opts) {
+		const secret = this.requireDeviceTrustSecret();
+		const raw = (0, node_crypto.randomBytes)(DEVICE_TRUST_TOKEN_BYTES).toString("hex");
+		const sig = signDeviceTrust(secret, payloadFor(raw));
+		const now = this.config.clock();
+		return {
+			token: `${raw}${DEVICE_TRUST_SEPARATOR}${sig}`,
+			...opts.ip !== void 0 && { ip: opts.ip },
+			issuedAt: now,
+			expiresAt: now + opts.ttlMs,
+			...opts.name !== void 0 && { name: opts.name }
+		};
+	}
+	/**
+	* Parse + constant-time HMAC check of a device token. Only the stateless
+	* half of verification — the persisted-record (expiry/IP) check stays with
+	* the caller. Throws only on a missing secret.
+	*/
+	checkDeviceTokenSig(token, payloadFor) {
+		const secret = this.requireDeviceTrustSecret();
+		const parsed = parseDeviceTrustToken(token);
+		if (!parsed) return false;
+		return deviceTrustSafeEqual(parsed.sig, signDeviceTrust(secret, payloadFor(parsed.raw)));
+	}
+	/**
+	* Mint a freshly-signed recognition record (does NOT persist — pair with
+	* `addSeenDevice`). No IP binding — recognition is pure noise control.
+	* Throws when `deviceTrust.secret` is unset.
+	*/
+	issueSeenDevice(userId, opts) {
+		return this.mintDeviceRecord((raw) => seenDevicePayload(userId, raw), opts);
+	}
+	/**
+	* Append a recognition record to the user's `seenDevices` ledger and enforce
+	* the cap (default 5): expired records are dropped first, then the
+	* least-recently-verified records (smallest `expiresAt` — verification
+	* slides it, so it doubles as the LRU key) are evicted until at cap.
+	* Read-modify-write under CAS — the array shape is preserved end-to-end so
+	* DB adapters with a merge strategy replace the whole array.
+	*/
+	async addSeenDevice(id, record, opts) {
+		const cap = opts?.cap ?? 5;
+		await this.store.withCas(id, (user) => {
+			let next = [...user.seenDevices ?? [], record];
+			if (next.length > cap) {
+				const now = this.config.clock();
+				next = next.filter((r) => r.expiresAt > now);
+				if (next.length > cap) {
+					next.sort((a, b) => a.expiresAt - b.expiresAt);
+					next = next.slice(next.length - cap);
+				}
+			}
+			return { set: { seenDevices: next } };
+		});
+	}
+	/**
+	* Returns true when the supplied token signs against the user with the
+	* configured secret (recognition domain) AND matches a persisted
+	* `seenDevices` record still within its expiry window. On a valid hit with
+	* `opts.slideTtlMs` set, the record's `expiresAt` is slid to
+	* `clock() + slideTtlMs` under CAS — the LRU bump. Never throws on a bad
+	* token (only on a missing secret, mirroring `verifyTrustedDevice`).
+	*/
+	async verifySeenDevice(userId, token, opts) {
+		if (!this.checkDeviceTokenSig(token, (raw) => seenDevicePayload(userId, raw))) return false;
+		const slideTtlMs = opts?.slideTtlMs;
+		if (slideTtlMs === void 0) {
+			const user = await this.store.findById(userId);
+			if (!user) return false;
+			const now = this.config.clock();
+			return (user.seenDevices ?? []).some((r) => r.token === token && r.expiresAt > now);
+		}
+		let matched = false;
+		try {
+			await this.store.withCas(userId, (current) => {
+				matched = false;
+				const list = current.seenDevices ?? [];
+				const now = this.config.clock();
+				const idx = list.findIndex((r) => r.token === token && r.expiresAt > now);
+				if (idx === -1) return null;
+				matched = true;
+				const next = [...list];
+				next[idx] = {
+					...next[idx],
+					expiresAt: now + slideTtlMs
+				};
+				return { set: { seenDevices: next } };
+			});
+		} catch (error) {
+			if (error instanceof require_federated_identity_store.UserAuthError && error.type === "NOT_FOUND") return false;
+			throw error;
+		}
+		return matched;
+	}
+	async listSeenDevices(id) {
+		return (await this.getUser(id)).seenDevices ?? [];
+	}
+	/**
+	* Clear the whole recognition ledger. Unconditional single write — `update`
+	* already no-ops on a missing row, and an empty `seenDevices` is equivalent
+	* to an absent one everywhere it is read.
+	*/
+	async revokeSeenDevices(id) {
+		await this.store.update(id, { set: { seenDevices: [] } });
+	}
+	/**
+	* True when `deviceTrust.secret` is configured — lets the workflow layer
+	* skip device recognition entirely (degrade gracefully) instead of throwing.
+	*/
+	hasDeviceTrustSecret() {
+		return !!this.config.deviceTrust?.secret;
+	}
+	/**
+	* Record `account.verifiedEmail` — the correspondence address whose inbox
+	* the user just PROVED (invite magic-link click, signup / recovery OTP,
+	* email-channel confirm, trusted federated profile). Plain write — a later
+	* proof for a different address overwrites the previous one. Throws
+	* `UserAuthError("NOT_FOUND")` when no row matches, like the other account
+	* mutators.
+	*/
+	async setVerifiedEmail(id, email) {
+		if (!await this.store.update(id, { set: { account: { verifiedEmail: email } } })) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
+	}
+	/**
+	* Resolve the address security notices should go to — a pure accessor over
+	* a row the caller already holds (no store round-trip). PROVEN-first chain:
+	*   1. `account.verifiedEmail` — the auth-proven capture written by
+	*      {@link setVerifiedEmail} at inbox-proof moments;
+	*   2. the first CONFIRMED `email` MFA method's value — also a proven inbox
+	*      (pre-capture legacy rows; going forward the confirm step writes
+	*      `verifiedEmail` too, so this level fades to a fallback);
+	*   3. the consumer's email column (`config.emailField`, the
+	*      `@aooth.user.email`-annotated handle) — app-canonical but UNPROVEN
+	*      (an admin-typed address proves nothing about the inbox).
+	* Returns `undefined` when none yields a non-empty address.
+	*
+	* Proven-first is deliberate for SECURITY notices: when an email changes,
+	* the notice should reach the previously-proven inbox, not an address
+	* nobody has demonstrated control of (mirrors the standard
+	* "your-email-was-changed goes to the OLD address" posture). Deployments
+	* that want app-canonical-first override this method.
+	*
+	* OVERRIDE SEAM: subclasses may source the address from anywhere (a profile
+	* table, a tenant directory, an external CRM) — the return type admits
+	* `Promise` so an override can hit a store; the default stays sync (no
+	* Promise allocation). Callers `await` the result.
+	*/
+	getCorrespondenceEmail(user) {
+		if (user.account.verifiedEmail) return user.account.verifiedEmail;
+		const mfaEmail = user.mfa.methods.find((m) => m.name === "email" && m.confirmed && m.value);
+		if (mfaEmail) return mfaEmail.value;
+		const emailField = this.config.emailField;
+		if (emailField) {
+			const value = user[emailField];
+			if (typeof value === "string" && value) return value;
+		}
+	}
 	async applyPasswordChange(id, user, newPassword) {
 		const policyResult = await this.checkPolicies(newPassword, user.password);
 		if (!policyResult.passed) throw new require_federated_identity_store.UserAuthError("POLICY_VIOLATION", policyResult.errors.join("; "), { policies: policyResult.policies });
@@ -1019,6 +1189,7 @@ exports.FederatedIdentityStore = require_federated_identity_store.FederatedIdent
 exports.FederatedIdentityStoreMemory = FederatedIdentityStoreMemory;
 exports.PasswordHasher = PasswordHasher;
 exports.PasswordPolicy = PasswordPolicy;
+exports.SEEN_DEVICES_DEFAULT_CAP = SEEN_DEVICES_DEFAULT_CAP;
 exports.UserAuthError = require_federated_identity_store.UserAuthError;
 exports.UserService = UserService;
 exports.UserStore = require_federated_identity_store.UserStore;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-CI7Vgllp.cjs";
+import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-I0uyqf2M.cjs";
 
 //#region src/errors.d.ts
 declare class UserAuthError extends Error {
@@ -70,7 +70,9 @@ interface ResolvedConfig {
   deviceTrust?: {
     secret: string;
   };
+  emailField?: string;
 }
+declare const SEEN_DEVICES_DEFAULT_CAP = 5;
 /**
  * Orchestrates user credentials over a pluggable {@link UserStore}.
  *
@@ -138,7 +140,14 @@ declare class UserService<T extends object = object> {
    * Used by the invite workflow's `applyProfile` default fallback.
    */
   update(id: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
-  activateAccount(id: string): Promise<void>;
+  /**
+   * Flip the account active. `opts.verifiedEmail` lets callers that just
+   * proved an inbox (invite magic link, signup OTP) record the correspondence
+   * address in the same store write — see {@link setVerifiedEmail}.
+   */
+  activateAccount(id: string, opts?: {
+    verifiedEmail?: string;
+  }): Promise<void>;
   deactivateAccount(id: string): Promise<void>;
   lockAccount(id: string, reason: string, duration?: number): Promise<void>;
   unlockAccount(id: string): Promise<void>;
@@ -213,6 +222,94 @@ declare class UserService<T extends object = object> {
   revokeTrustedDevice(id: string, token: string): Promise<void>;
   listTrustedDevices(id: string): Promise<TrustedDeviceRecord[]>;
   private requireDeviceTrustSecret;
+  /**
+   * Shared mint core for trust + recognition records — the HMAC domain is set
+   * by `payloadFor` (see `trustedDevicePayload` / `seenDevicePayload`).
+   */
+  private mintDeviceRecord;
+  /**
+   * Parse + constant-time HMAC check of a device token. Only the stateless
+   * half of verification — the persisted-record (expiry/IP) check stays with
+   * the caller. Throws only on a missing secret.
+   */
+  private checkDeviceTokenSig;
+  /**
+   * Mint a freshly-signed recognition record (does NOT persist — pair with
+   * `addSeenDevice`). No IP binding — recognition is pure noise control.
+   * Throws when `deviceTrust.secret` is unset.
+   */
+  issueSeenDevice(userId: string, opts: {
+    ttlMs: number;
+    name?: string;
+  }): TrustedDeviceRecord;
+  /**
+   * Append a recognition record to the user's `seenDevices` ledger and enforce
+   * the cap (default 5): expired records are dropped first, then the
+   * least-recently-verified records (smallest `expiresAt` — verification
+   * slides it, so it doubles as the LRU key) are evicted until at cap.
+   * Read-modify-write under CAS — the array shape is preserved end-to-end so
+   * DB adapters with a merge strategy replace the whole array.
+   */
+  addSeenDevice(id: string, record: TrustedDeviceRecord, opts?: {
+    cap?: number;
+  }): Promise<void>;
+  /**
+   * Returns true when the supplied token signs against the user with the
+   * configured secret (recognition domain) AND matches a persisted
+   * `seenDevices` record still within its expiry window. On a valid hit with
+   * `opts.slideTtlMs` set, the record's `expiresAt` is slid to
+   * `clock() + slideTtlMs` under CAS — the LRU bump. Never throws on a bad
+   * token (only on a missing secret, mirroring `verifyTrustedDevice`).
+   */
+  verifySeenDevice(userId: string, token: string, opts?: {
+    slideTtlMs?: number;
+  }): Promise<boolean>;
+  listSeenDevices(id: string): Promise<TrustedDeviceRecord[]>;
+  /**
+   * Clear the whole recognition ledger. Unconditional single write — `update`
+   * already no-ops on a missing row, and an empty `seenDevices` is equivalent
+   * to an absent one everywhere it is read.
+   */
+  revokeSeenDevices(id: string): Promise<void>;
+  /**
+   * True when `deviceTrust.secret` is configured — lets the workflow layer
+   * skip device recognition entirely (degrade gracefully) instead of throwing.
+   */
+  hasDeviceTrustSecret(): boolean;
+  /**
+   * Record `account.verifiedEmail` — the correspondence address whose inbox
+   * the user just PROVED (invite magic-link click, signup / recovery OTP,
+   * email-channel confirm, trusted federated profile). Plain write — a later
+   * proof for a different address overwrites the previous one. Throws
+   * `UserAuthError("NOT_FOUND")` when no row matches, like the other account
+   * mutators.
+   */
+  setVerifiedEmail(id: string, email: string): Promise<void>;
+  /**
+   * Resolve the address security notices should go to — a pure accessor over
+   * a row the caller already holds (no store round-trip). PROVEN-first chain:
+   *   1. `account.verifiedEmail` — the auth-proven capture written by
+   *      {@link setVerifiedEmail} at inbox-proof moments;
+   *   2. the first CONFIRMED `email` MFA method's value — also a proven inbox
+   *      (pre-capture legacy rows; going forward the confirm step writes
+   *      `verifiedEmail` too, so this level fades to a fallback);
+   *   3. the consumer's email column (`config.emailField`, the
+   *      `@aooth.user.email`-annotated handle) — app-canonical but UNPROVEN
+   *      (an admin-typed address proves nothing about the inbox).
+   * Returns `undefined` when none yields a non-empty address.
+   *
+   * Proven-first is deliberate for SECURITY notices: when an email changes,
+   * the notice should reach the previously-proven inbox, not an address
+   * nobody has demonstrated control of (mirrors the standard
+   * "your-email-was-changed goes to the OLD address" posture). Deployments
+   * that want app-canonical-first override this method.
+   *
+   * OVERRIDE SEAM: subclasses may source the address from anywhere (a profile
+   * table, a tenant directory, an external CRM) — the return type admits
+   * `Promise` so an override can hit a store; the default stays sync (no
+   * Promise allocation). Callers `await` the result.
+   */
+  getCorrespondenceEmail(user: UserCredentials & T): string | undefined | Promise<string | undefined>;
   private applyPasswordChange;
   private hasConfirmedMfaMethods;
   /**
@@ -343,4 +440,4 @@ declare function maskPhone(phone: string): string;
 declare function maskMfaValue(method: MfaMethod): string;
 declare function setAtPath(obj: object, path: string, value: unknown): void;
 //#endregion
-export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, SEEN_DEVICES_DEFAULT_CAP, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-CI7Vgllp.mjs";
+import { C as TotpConfig, D as UserCredentials, E as UserAuthErrorType, O as UserServiceConfig, S as PolicyCheckResult, T as TrustedDeviceRecord, _ as PasswordData, a as pickDefinedProfile, b as PasswordPolicyEvalFn, c as AccountData, d as LockoutConfig, f as LoginResult, g as PasswordConfig, h as MfaMethodInfo, i as NewFederatedIdentity, k as UserStoreUpdate, l as DeepPartial, m as MfaMethod, n as FederatedIdentityStore, o as UserStore, p as MfaData, r as FederatedProfileSnapshot, s as WithCasOptions, t as FederatedIdentity, u as LockStatus, v as PasswordPolicyContext, w as TransferablePolicy, x as PasswordPolicyInstance, y as PasswordPolicyDef } from "./federated-identity-store-I0uyqf2M.mjs";
 
 //#region src/errors.d.ts
 declare class UserAuthError extends Error {
@@ -70,7 +70,9 @@ interface ResolvedConfig {
   deviceTrust?: {
     secret: string;
   };
+  emailField?: string;
 }
+declare const SEEN_DEVICES_DEFAULT_CAP = 5;
 /**
  * Orchestrates user credentials over a pluggable {@link UserStore}.
  *
@@ -138,7 +140,14 @@ declare class UserService<T extends object = object> {
    * Used by the invite workflow's `applyProfile` default fallback.
    */
   update(id: string, patch: Partial<UserCredentials & T>): Promise<UserCredentials & T>;
-  activateAccount(id: string): Promise<void>;
+  /**
+   * Flip the account active. `opts.verifiedEmail` lets callers that just
+   * proved an inbox (invite magic link, signup OTP) record the correspondence
+   * address in the same store write — see {@link setVerifiedEmail}.
+   */
+  activateAccount(id: string, opts?: {
+    verifiedEmail?: string;
+  }): Promise<void>;
   deactivateAccount(id: string): Promise<void>;
   lockAccount(id: string, reason: string, duration?: number): Promise<void>;
   unlockAccount(id: string): Promise<void>;
@@ -213,6 +222,94 @@ declare class UserService<T extends object = object> {
   revokeTrustedDevice(id: string, token: string): Promise<void>;
   listTrustedDevices(id: string): Promise<TrustedDeviceRecord[]>;
   private requireDeviceTrustSecret;
+  /**
+   * Shared mint core for trust + recognition records — the HMAC domain is set
+   * by `payloadFor` (see `trustedDevicePayload` / `seenDevicePayload`).
+   */
+  private mintDeviceRecord;
+  /**
+   * Parse + constant-time HMAC check of a device token. Only the stateless
+   * half of verification — the persisted-record (expiry/IP) check stays with
+   * the caller. Throws only on a missing secret.
+   */
+  private checkDeviceTokenSig;
+  /**
+   * Mint a freshly-signed recognition record (does NOT persist — pair with
+   * `addSeenDevice`). No IP binding — recognition is pure noise control.
+   * Throws when `deviceTrust.secret` is unset.
+   */
+  issueSeenDevice(userId: string, opts: {
+    ttlMs: number;
+    name?: string;
+  }): TrustedDeviceRecord;
+  /**
+   * Append a recognition record to the user's `seenDevices` ledger and enforce
+   * the cap (default 5): expired records are dropped first, then the
+   * least-recently-verified records (smallest `expiresAt` — verification
+   * slides it, so it doubles as the LRU key) are evicted until at cap.
+   * Read-modify-write under CAS — the array shape is preserved end-to-end so
+   * DB adapters with a merge strategy replace the whole array.
+   */
+  addSeenDevice(id: string, record: TrustedDeviceRecord, opts?: {
+    cap?: number;
+  }): Promise<void>;
+  /**
+   * Returns true when the supplied token signs against the user with the
+   * configured secret (recognition domain) AND matches a persisted
+   * `seenDevices` record still within its expiry window. On a valid hit with
+   * `opts.slideTtlMs` set, the record's `expiresAt` is slid to
+   * `clock() + slideTtlMs` under CAS — the LRU bump. Never throws on a bad
+   * token (only on a missing secret, mirroring `verifyTrustedDevice`).
+   */
+  verifySeenDevice(userId: string, token: string, opts?: {
+    slideTtlMs?: number;
+  }): Promise<boolean>;
+  listSeenDevices(id: string): Promise<TrustedDeviceRecord[]>;
+  /**
+   * Clear the whole recognition ledger. Unconditional single write — `update`
+   * already no-ops on a missing row, and an empty `seenDevices` is equivalent
+   * to an absent one everywhere it is read.
+   */
+  revokeSeenDevices(id: string): Promise<void>;
+  /**
+   * True when `deviceTrust.secret` is configured — lets the workflow layer
+   * skip device recognition entirely (degrade gracefully) instead of throwing.
+   */
+  hasDeviceTrustSecret(): boolean;
+  /**
+   * Record `account.verifiedEmail` — the correspondence address whose inbox
+   * the user just PROVED (invite magic-link click, signup / recovery OTP,
+   * email-channel confirm, trusted federated profile). Plain write — a later
+   * proof for a different address overwrites the previous one. Throws
+   * `UserAuthError("NOT_FOUND")` when no row matches, like the other account
+   * mutators.
+   */
+  setVerifiedEmail(id: string, email: string): Promise<void>;
+  /**
+   * Resolve the address security notices should go to — a pure accessor over
+   * a row the caller already holds (no store round-trip). PROVEN-first chain:
+   *   1. `account.verifiedEmail` — the auth-proven capture written by
+   *      {@link setVerifiedEmail} at inbox-proof moments;
+   *   2. the first CONFIRMED `email` MFA method's value — also a proven inbox
+   *      (pre-capture legacy rows; going forward the confirm step writes
+   *      `verifiedEmail` too, so this level fades to a fallback);
+   *   3. the consumer's email column (`config.emailField`, the
+   *      `@aooth.user.email`-annotated handle) — app-canonical but UNPROVEN
+   *      (an admin-typed address proves nothing about the inbox).
+   * Returns `undefined` when none yields a non-empty address.
+   *
+   * Proven-first is deliberate for SECURITY notices: when an email changes,
+   * the notice should reach the previously-proven inbox, not an address
+   * nobody has demonstrated control of (mirrors the standard
+   * "your-email-was-changed goes to the OLD address" posture). Deployments
+   * that want app-canonical-first override this method.
+   *
+   * OVERRIDE SEAM: subclasses may source the address from anywhere (a profile
+   * table, a tenant directory, an external CRM) — the return type admits
+   * `Promise` so an override can hit a store; the default stays sync (no
+   * Promise allocation). Callers `await` the result.
+   */
+  getCorrespondenceEmail(user: UserCredentials & T): string | undefined | Promise<string | undefined>;
   private applyPasswordChange;
   private hasConfirmedMfaMethods;
   /**
@@ -343,4 +440,4 @@ declare function maskPhone(phone: string): string;
 declare function maskMfaValue(method: MfaMethod): string;
 declare function setAtPath(obj: object, path: string, value: unknown): void;
 //#endregion
-export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { type AccountData, type DeepPartial, type FederatedIdentity, FederatedIdentityStore, FederatedIdentityStoreMemory, type FederatedIdentityStoreMemoryOptions, type FederatedProfileSnapshot, type LockStatus, type LockoutConfig, type LoginResult, type MfaData, type MfaMethod, type MfaMethodInfo, type NewFederatedIdentity, type PasswordConfig, type PasswordData, PasswordHasher, PasswordPolicy, type PasswordPolicyContext, type PasswordPolicyDef, type PasswordPolicyEvalFn, type PasswordPolicyInstance, type PolicyCheckResult, SEEN_DEVICES_DEFAULT_CAP, type TotpConfig, type TransferablePolicy, type TrustedDeviceRecord, UserAuthError, type UserAuthErrorType, type UserCredentials, UserService, type UserServiceConfig, UserStore, UserStoreMemory, type UserStoreUpdate, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };

package/dist/index.mjs

@@ -292,14 +292,30 @@ function resolveConfig(config) {
 			duration: config?.lockout?.duration ?? 0
 		},
 		clock: config?.clock ?? Date.now,
-		...config?.deviceTrust && { deviceTrust: config.deviceTrust }
+		...config?.deviceTrust && { deviceTrust: config.deviceTrust },
+		...config?.emailField && { emailField: config.emailField }
 	};
 }
 const DEVICE_TRUST_TOKEN_BYTES = 32;
 const DEVICE_TRUST_SEPARATOR = ".";
+const SEEN_DEVICES_DEFAULT_CAP = 5;
 function signDeviceTrust(secret, payload) {
 	return createHmac("sha256", secret).update(payload).digest("hex");
 }
+function trustedDevicePayload(userId, raw, ip) {
+	return `${userId}|${raw}|${ip ?? ""}`;
+}
+function seenDevicePayload(userId, raw) {
+	return `seen|${userId}|${raw}`;
+}
+function parseDeviceTrustToken(token) {
+	const sepIdx = token.lastIndexOf(DEVICE_TRUST_SEPARATOR);
+	if (sepIdx <= 0) return void 0;
+	return {
+		raw: token.slice(0, sepIdx),
+		sig: token.slice(sepIdx + 1)
+	};
+}
 function deviceTrustSafeEqual(a, b) {
 	const ab = Buffer.from(a);
 	const bb = Buffer.from(b);
@@ -450,8 +466,15 @@ var UserService = class {
 		if (!await this.store.update(id, { set: patch })) throw new UserAuthError("NOT_FOUND");
 		return this.getUser(id);
 	}
-	async activateAccount(id) {
-		if (!await this.store.update(id, { set: { account: { active: true } } })) throw new UserAuthError("NOT_FOUND");
+	/**
+	* Flip the account active. `opts.verifiedEmail` lets callers that just
+	* proved an inbox (invite magic link, signup OTP) record the correspondence
+	* address in the same store write — see {@link setVerifiedEmail}.
+	*/
+	async activateAccount(id, opts) {
+		const account = { active: true };
+		if (opts?.verifiedEmail !== void 0) account.verifiedEmail = opts.verifiedEmail;
+		if (!await this.store.update(id, { set: { account } })) throw new UserAuthError("NOT_FOUND");
 	}
 	async deactivateAccount(id) {
 		if (!await this.store.update(id, { set: { account: { active: false } } })) throw new UserAuthError("NOT_FOUND");
@@ -637,17 +660,7 @@ var UserService = class {
 	* `addTrustedDevice`). Throws when `deviceTrust.secret` is unset.
 	*/
 	issueTrustedDevice(userId, opts) {
-		const secret = this.requireDeviceTrustSecret();
-		const raw = randomBytes(DEVICE_TRUST_TOKEN_BYTES).toString("hex");
-		const sig = signDeviceTrust(secret, `${userId}|${raw}|${opts.ip ?? ""}`);
-		const now = this.config.clock();
-		return {
-			token: `${raw}${DEVICE_TRUST_SEPARATOR}${sig}`,
-			...opts.ip !== void 0 && { ip: opts.ip },
-			issuedAt: now,
-			expiresAt: now + opts.ttlMs,
-			...opts.name !== void 0 && { name: opts.name }
-		};
+		return this.mintDeviceRecord((raw) => trustedDevicePayload(userId, raw, opts.ip), opts);
 	}
 	/**
 	* Append a trust record to the user's `trustedDevices` list. Read-modify-
@@ -665,11 +678,7 @@ var UserService = class {
 	* within its expiry window and whose bound IP (if any) matches.
 	*/
 	async verifyTrustedDevice(userId, token, ip) {
-		const secret = this.requireDeviceTrustSecret();
-		const sepIdx = token.lastIndexOf(DEVICE_TRUST_SEPARATOR);
-		if (sepIdx <= 0) return false;
-		const raw = token.slice(0, sepIdx);
-		if (!deviceTrustSafeEqual(token.slice(sepIdx + 1), signDeviceTrust(secret, `${userId}|${raw}|${ip ?? ""}`))) return false;
+		if (!this.checkDeviceTokenSig(token, (raw) => trustedDevicePayload(userId, raw, ip))) return false;
 		const user = await this.store.findById(userId);
 		if (!user) return false;
 		const list = user.trustedDevices ?? [];
@@ -699,6 +708,167 @@ var UserService = class {
 		if (!secret) throw new Error("UserService: deviceTrust.secret is required to use trusted-device APIs");
 		return secret;
 	}
+	/**
+	* Shared mint core for trust + recognition records — the HMAC domain is set
+	* by `payloadFor` (see `trustedDevicePayload` / `seenDevicePayload`).
+	*/
+	mintDeviceRecord(payloadFor, opts) {
+		const secret = this.requireDeviceTrustSecret();
+		const raw = randomBytes(DEVICE_TRUST_TOKEN_BYTES).toString("hex");
+		const sig = signDeviceTrust(secret, payloadFor(raw));
+		const now = this.config.clock();
+		return {
+			token: `${raw}${DEVICE_TRUST_SEPARATOR}${sig}`,
+			...opts.ip !== void 0 && { ip: opts.ip },
+			issuedAt: now,
+			expiresAt: now + opts.ttlMs,
+			...opts.name !== void 0 && { name: opts.name }
+		};
+	}
+	/**
+	* Parse + constant-time HMAC check of a device token. Only the stateless
+	* half of verification — the persisted-record (expiry/IP) check stays with
+	* the caller. Throws only on a missing secret.
+	*/
+	checkDeviceTokenSig(token, payloadFor) {
+		const secret = this.requireDeviceTrustSecret();
+		const parsed = parseDeviceTrustToken(token);
+		if (!parsed) return false;
+		return deviceTrustSafeEqual(parsed.sig, signDeviceTrust(secret, payloadFor(parsed.raw)));
+	}
+	/**
+	* Mint a freshly-signed recognition record (does NOT persist — pair with
+	* `addSeenDevice`). No IP binding — recognition is pure noise control.
+	* Throws when `deviceTrust.secret` is unset.
+	*/
+	issueSeenDevice(userId, opts) {
+		return this.mintDeviceRecord((raw) => seenDevicePayload(userId, raw), opts);
+	}
+	/**
+	* Append a recognition record to the user's `seenDevices` ledger and enforce
+	* the cap (default 5): expired records are dropped first, then the
+	* least-recently-verified records (smallest `expiresAt` — verification
+	* slides it, so it doubles as the LRU key) are evicted until at cap.
+	* Read-modify-write under CAS — the array shape is preserved end-to-end so
+	* DB adapters with a merge strategy replace the whole array.
+	*/
+	async addSeenDevice(id, record, opts) {
+		const cap = opts?.cap ?? 5;
+		await this.store.withCas(id, (user) => {
+			let next = [...user.seenDevices ?? [], record];
+			if (next.length > cap) {
+				const now = this.config.clock();
+				next = next.filter((r) => r.expiresAt > now);
+				if (next.length > cap) {
+					next.sort((a, b) => a.expiresAt - b.expiresAt);
+					next = next.slice(next.length - cap);
+				}
+			}
+			return { set: { seenDevices: next } };
+		});
+	}
+	/**
+	* Returns true when the supplied token signs against the user with the
+	* configured secret (recognition domain) AND matches a persisted
+	* `seenDevices` record still within its expiry window. On a valid hit with
+	* `opts.slideTtlMs` set, the record's `expiresAt` is slid to
+	* `clock() + slideTtlMs` under CAS — the LRU bump. Never throws on a bad
+	* token (only on a missing secret, mirroring `verifyTrustedDevice`).
+	*/
+	async verifySeenDevice(userId, token, opts) {
+		if (!this.checkDeviceTokenSig(token, (raw) => seenDevicePayload(userId, raw))) return false;
+		const slideTtlMs = opts?.slideTtlMs;
+		if (slideTtlMs === void 0) {
+			const user = await this.store.findById(userId);
+			if (!user) return false;
+			const now = this.config.clock();
+			return (user.seenDevices ?? []).some((r) => r.token === token && r.expiresAt > now);
+		}
+		let matched = false;
+		try {
+			await this.store.withCas(userId, (current) => {
+				matched = false;
+				const list = current.seenDevices ?? [];
+				const now = this.config.clock();
+				const idx = list.findIndex((r) => r.token === token && r.expiresAt > now);
+				if (idx === -1) return null;
+				matched = true;
+				const next = [...list];
+				next[idx] = {
+					...next[idx],
+					expiresAt: now + slideTtlMs
+				};
+				return { set: { seenDevices: next } };
+			});
+		} catch (error) {
+			if (error instanceof UserAuthError && error.type === "NOT_FOUND") return false;
+			throw error;
+		}
+		return matched;
+	}
+	async listSeenDevices(id) {
+		return (await this.getUser(id)).seenDevices ?? [];
+	}
+	/**
+	* Clear the whole recognition ledger. Unconditional single write — `update`
+	* already no-ops on a missing row, and an empty `seenDevices` is equivalent
+	* to an absent one everywhere it is read.
+	*/
+	async revokeSeenDevices(id) {
+		await this.store.update(id, { set: { seenDevices: [] } });
+	}
+	/**
+	* True when `deviceTrust.secret` is configured — lets the workflow layer
+	* skip device recognition entirely (degrade gracefully) instead of throwing.
+	*/
+	hasDeviceTrustSecret() {
+		return !!this.config.deviceTrust?.secret;
+	}
+	/**
+	* Record `account.verifiedEmail` — the correspondence address whose inbox
+	* the user just PROVED (invite magic-link click, signup / recovery OTP,
+	* email-channel confirm, trusted federated profile). Plain write — a later
+	* proof for a different address overwrites the previous one. Throws
+	* `UserAuthError("NOT_FOUND")` when no row matches, like the other account
+	* mutators.
+	*/
+	async setVerifiedEmail(id, email) {
+		if (!await this.store.update(id, { set: { account: { verifiedEmail: email } } })) throw new UserAuthError("NOT_FOUND");
+	}
+	/**
+	* Resolve the address security notices should go to — a pure accessor over
+	* a row the caller already holds (no store round-trip). PROVEN-first chain:
+	*   1. `account.verifiedEmail` — the auth-proven capture written by
+	*      {@link setVerifiedEmail} at inbox-proof moments;
+	*   2. the first CONFIRMED `email` MFA method's value — also a proven inbox
+	*      (pre-capture legacy rows; going forward the confirm step writes
+	*      `verifiedEmail` too, so this level fades to a fallback);
+	*   3. the consumer's email column (`config.emailField`, the
+	*      `@aooth.user.email`-annotated handle) — app-canonical but UNPROVEN
+	*      (an admin-typed address proves nothing about the inbox).
+	* Returns `undefined` when none yields a non-empty address.
+	*
+	* Proven-first is deliberate for SECURITY notices: when an email changes,
+	* the notice should reach the previously-proven inbox, not an address
+	* nobody has demonstrated control of (mirrors the standard
+	* "your-email-was-changed goes to the OLD address" posture). Deployments
+	* that want app-canonical-first override this method.
+	*
+	* OVERRIDE SEAM: subclasses may source the address from anywhere (a profile
+	* table, a tenant directory, an external CRM) — the return type admits
+	* `Promise` so an override can hit a store; the default stays sync (no
+	* Promise allocation). Callers `await` the result.
+	*/
+	getCorrespondenceEmail(user) {
+		if (user.account.verifiedEmail) return user.account.verifiedEmail;
+		const mfaEmail = user.mfa.methods.find((m) => m.name === "email" && m.confirmed && m.value);
+		if (mfaEmail) return mfaEmail.value;
+		const emailField = this.config.emailField;
+		if (emailField) {
+			const value = user[emailField];
+			if (typeof value === "string" && value) return value;
+		}
+	}
 	async applyPasswordChange(id, user, newPassword) {
 		const policyResult = await this.checkPolicies(newPassword, user.password);
 		if (!policyResult.passed) throw new UserAuthError("POLICY_VIOLATION", policyResult.errors.join("; "), { policies: policyResult.policies });
@@ -1014,4 +1184,4 @@ function verifyMfaCode(submitted, expectedHash) {
 	return timingSafeEqual(a, b);
 }
 //#endregion
-export { FederatedIdentityStore, FederatedIdentityStoreMemory, PasswordHasher, PasswordPolicy, UserAuthError, UserService, UserStore, UserStoreMemory, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };
+export { FederatedIdentityStore, FederatedIdentityStoreMemory, PasswordHasher, PasswordPolicy, SEEN_DEVICES_DEFAULT_CAP, UserAuthError, UserService, UserStore, UserStoreMemory, definePasswordPolicy, generateMfaCode, generateTotpCode, generateTotpSecret, generateTotpUri, hashMfaCode, maskEmail, maskMfaValue, maskPhone, normalizePolicies, pickDefinedProfile, ppHasLowerCase, ppHasMinLength, ppHasNumber, ppHasSpecialChar, ppHasUpperCase, ppMaxRepeatedChars, setAtPath, verifyMfaCode, verifyTotpCode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/user",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "User credential primitives for aoothjs",
   "keywords": [
     "aoothjs",
@@ -60,14 +60,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.75",
-    "@atscript/db": "^0.1.104",
-    "@atscript/db-sql-tools": "^0.1.104",
-    "@atscript/db-sqlite": "^0.1.104",
-    "@atscript/typescript": "^0.1.75",
+    "@atscript/core": "^0.1.76",
+    "@atscript/db": "^0.1.105",
+    "@atscript/db-sql-tools": "^0.1.105",
+    "@atscript/db-sqlite": "^0.1.105",
+    "@atscript/typescript": "^0.1.76",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.6.2",
-    "unplugin-atscript": "^0.1.75"
+    "unplugin-atscript": "^0.1.76"
   },
   "peerDependencies": {
     "@atscript/db": ">=0.1.79"

package/src/atscript-db/user-credentials.as

@@ -28,6 +28,8 @@ export interface AoothUserCredentials {
         failedLoginAttempts: number
         lastLogin: number.timestamp
         pendingInvitation?: boolean
+        // Correspondence address whose inbox the user proved (invite click, OTP, email confirm); auth-owned, not a login handle
+        verifiedEmail?: string
     }
 
     @db.patch.strategy 'merge'
@@ -46,4 +48,14 @@ export interface AoothUserCredentials {
         expiresAt: number.timestamp
         name?: string
     }[]
+
+    // Recognition ledger — devices that completed a login (suppresses the new-sign-in notification; no security bypass)
+    @db.patch.strategy 'merge'
+    seenDevices?: {
+        token: string
+        ip?: string
+        issuedAt: number.timestamp
+        expiresAt: number.timestamp
+        name?: string
+    }[]
 }

package/src/atscript-db/user-credentials.as.d.ts

@@ -31,6 +31,7 @@ export declare class AoothUserCredentials {
     failedLoginAttempts: number
     lastLogin: number /* timestamp */
     pendingInvitation?: boolean
+    verifiedEmail?: string
   }
   mfa: {
     methods: {
@@ -49,6 +50,13 @@ export declare class AoothUserCredentials {
     expiresAt: number /* timestamp */
     name?: string
   }[]
+  seenDevices?: {
+    token: string
+    ip?: string
+    issuedAt: number /* timestamp */
+    expiresAt: number /* timestamp */
+    name?: string
+  }[]
   static __is_atscript_annotated_type: true
   static type: TAtscriptTypeObject<keyof AoothUserCredentials, AoothUserCredentials>
   static metadata: TMetadataMap<AtscriptMetadata>