@aooth/user 0.1.7 → 0.1.9

package/dist/atscript-db.cjs

@@ -1,5 +1,77 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_user_store = require("./user-store-BPZVAboN.cjs");
+const require_federated_identity_store = require("./federated-identity-store-BEEEcoaP.cjs");
+let node_crypto = require("node:crypto");
+//#region src/atscript-db/federated-identity-store.ts
+function isConflict$1(err) {
+	return typeof err === "object" && err !== null && err.code === "CONFLICT";
+}
+/**
+* `@atscript/db`-backed {@link FederatedIdentityStore}. Pass the resolved table
+* for the `AoothFederatedIdentity` model shipped at
+* `@aooth/user/atscript-db/federated-model`. The compound-unique
+* `(provider, subject)` index makes `find` an O(1) point read and turns a
+* cross-user re-link attempt into a `CONFLICT` (→ `ALREADY_EXISTS`); `userId`
+* is a plain indexed column, so `listForUser` / `deleteAllForUser` scan it
+* natively.
+*/
+var FederatedIdentityStoreAtscriptDb = class extends require_federated_identity_store.FederatedIdentityStore {
+	table;
+	clock;
+	constructor(opts) {
+		super();
+		this.table = opts.table;
+		this.clock = opts.clock ?? Date.now;
+	}
+	async find(provider, subject) {
+		return this.table.findOne({ filter: {
+			provider,
+			subject
+		} });
+	}
+	async listForUser(userId) {
+		return (await this.table.findMany({ filter: { userId } })).toSorted((a, b) => a.linkedAt - b.linkedAt);
+	}
+	async link(rec) {
+		const row = {
+			id: (0, node_crypto.randomUUID)(),
+			provider: rec.provider,
+			subject: rec.subject,
+			userId: rec.userId,
+			...require_federated_identity_store.pickDefinedProfile(rec),
+			linkedAt: this.clock()
+		};
+		try {
+			await this.table.insertOne(row);
+			return row;
+		} catch (e) {
+			if (isConflict$1(e)) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", `Provider account "${rec.provider}:${rec.subject}" is already linked`);
+			throw e;
+		}
+	}
+	async unlink(provider, subject) {
+		return (await this.table.deleteMany({
+			provider,
+			subject
+		})).deletedCount > 0;
+	}
+	async touchLogin(provider, subject, profile) {
+		const row = await this.table.findOne({ filter: {
+			provider,
+			subject
+		} });
+		if (!row) return;
+		const next = {
+			...row,
+			lastLoginAt: this.clock()
+		};
+		if (profile) Object.assign(next, require_federated_identity_store.pickDefinedProfile(profile));
+		await this.table.replaceOne(next);
+	}
+	async deleteAllForUser(userId) {
+		return (await this.table.deleteMany({ userId })).deletedCount;
+	}
+};
+//#endregion
 //#region src/atscript-db/index.ts
 function isConflict(err) {
 	return typeof err === "object" && err !== null && err.code === "CONFLICT";
@@ -7,62 +79,88 @@ function isConflict(err) {
 /**
 * `@atscript/db`-backed `UserStore`. Pass the resolved table for the
 * `AoothUserCredentials` (or a `.as` interface extending it) shipped at the
-* `@aooth/user/atscript-db/model.as` subpath.
+* `@aooth/user/atscript-db/model.as` subpath. Identity reads use the
+* `@meta.id` PK (`id`) and the unique `username` index, plus any
+* annotation-resolved `handleFields`; writes key on `id`.
 */
-var UsersStoreAtscriptDb = class extends require_user_store.UserStore {
+var UsersStoreAtscriptDb = class extends require_federated_identity_store.UserStore {
 	table;
+	/** Secondary handle fields tried (in order) by `findByHandle` after `username`. */
+	handleFields;
 	constructor(opts) {
 		super();
 		this.table = opts.table;
+		this.handleFields = opts.handleFields ?? [];
 	}
-	async exists(username) {
-		return await this.table.count({ filter: { username } }) > 0;
+	async exists(handle) {
+		return await this.table.count({ filter: { username: handle } }) > 0;
 	}
-	async findByUsername(username) {
-		return await this.table.findOne({ filter: { username } }) ?? null;
+	async findById(id) {
+		return await this.table.findOne({ filter: { id } });
+	}
+	async findByHandle(handle) {
+		const byUsername = await this.table.findOne({ filter: { username: handle } });
+		if (byUsername) return byUsername;
+		for (const field of this.handleFields) {
+			const byHandle = await this.table.findOne({ filter: { [field]: handle } });
+			if (byHandle) return byHandle;
+		}
+		return null;
+	}
+	async findByIdentifier(value) {
+		const byId = await this.table.findOne({ filter: { id: value } });
+		if (byId) return byId;
+		return this.findByHandle(value);
 	}
 	async create(data) {
 		try {
 			await this.table.insertOne(data);
 		} catch (e) {
-			if (isConflict(e)) throw new require_user_store.UserAuthError("ALREADY_EXISTS", `User "${data.username}" already exists`);
+			if (isConflict(e)) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", `User "${data.username}" already exists`);
 			throw e;
 		}
 	}
-	async update(username, update) {
-		const patch = { username };
+	async update(id, update) {
+		const patch = { id };
 		if (update.set) Object.assign(patch, update.set);
-		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) require_user_store.setAtPath(patch, path, { $inc: amount });
+		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) require_federated_identity_store.setAtPath(patch, path, { $inc: amount });
 		if (Object.keys(patch).length <= 1) return true;
 		if (update.expectedVersion !== void 0) patch.$cas = { version: update.expectedVersion };
-		return (await this.table.updateOne(patch)).matchedCount > 0;
+		try {
+			return (await this.table.updateOne(patch)).matchedCount > 0;
+		} catch (e) {
+			if (isConflict(e)) throw new require_federated_identity_store.UserAuthError("ALREADY_EXISTS", "Update conflicts with an existing unique value");
+			throw e;
+		}
 	}
-	async delete(username) {
-		return (await this.table.deleteMany({ username })).deletedCount > 0;
+	async delete(id) {
+		return (await this.table.deleteMany({ id })).deletedCount > 0;
 	}
 	/**
 	* Inline retry loop rather than delegating to @atscript/db's
 	* `withOptimisticRetry`: that helper expects the mutator to always return a
 	* patch object, but our contract lets the mutator return `null` (the
-	* race-loser detects nothing to do — see `UserService.consumeBackupCode`).
-	* Bridging would need a sentinel exception. The version-bump + $cas
-	* atomicity still happen at the atscript-db table layer via the
-	* `expectedVersion` we thread through `update()`.
+	* race-loser detects nothing to do — used by callers whose mutator opts
+	* out of a write after re-reading state). Bridging would need a sentinel
+	* exception. The version-bump + $cas atomicity still happen at the
+	* atscript-db table layer via the `expectedVersion` we thread through
+	* `update()`.
 	*/
-	async withCas(username, mutator, opts) {
+	async withCas(id, mutator, opts) {
 		const maxAttempts = opts?.maxAttempts ?? 2;
 		for (let attempt = 0; attempt < maxAttempts; attempt++) {
-			const current = await this.findByUsername(username);
-			if (!current) throw new require_user_store.UserAuthError("NOT_FOUND");
+			const current = await this.findById(id);
+			if (!current) throw new require_federated_identity_store.UserAuthError("NOT_FOUND");
 			const patch = mutator(current);
 			if (patch === null) return;
-			if (await this.update(username, {
+			if (await this.update(id, {
 				...patch,
 				expectedVersion: current.version ?? 0
 			})) return;
 		}
-		throw new require_user_store.UserAuthError("CAS_EXHAUSTED");
+		throw new require_federated_identity_store.UserAuthError("CAS_EXHAUSTED");
 	}
 };
 //#endregion
+exports.FederatedIdentityStoreAtscriptDb = FederatedIdentityStoreAtscriptDb;
 exports.UsersStoreAtscriptDb = UsersStoreAtscriptDb;

package/dist/atscript-db.d.cts

@@ -1,5 +1,57 @@
-import { S as UserCredentials, n as WithCasOptions, t as UserStore, w as UserStoreUpdate } from "./user-store-BZsKtBHy.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-CI7Vgllp.cjs";
 
+//#region src/atscript-db/federated-identity-store.d.ts
+/**
+ * Structural surface of `AtscriptDbTable` covering exactly the methods this
+ * adapter calls — kept loose so `@aooth/user` doesn't pull `@atscript/db` types
+ * into its public surface. Consumers pass `db.getTable(AoothFederatedIdentity)`
+ * directly and TypeScript matches by-shape. Mirrors `AuthCredentialTable` from
+ * `@aooth/auth/atscript-db`.
+ */
+interface FederatedIdentityTable {
+  insertOne(row: FederatedIdentity): Promise<{
+    insertedId: unknown;
+  }>;
+  findOne(query: {
+    filter: Record<string, unknown>;
+  }): Promise<FederatedIdentity | null>;
+  findMany(query: {
+    filter?: Record<string, unknown>;
+  }): Promise<FederatedIdentity[]>;
+  replaceOne(row: FederatedIdentity): Promise<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>;
+  deleteMany(filter: Record<string, unknown>): Promise<{
+    deletedCount: number;
+  }>;
+}
+interface FederatedIdentityStoreAtscriptDbOptions {
+  table: FederatedIdentityTable;
+  /** Injectable clock for `linkedAt` / `lastLoginAt`. Defaults to `Date.now`. */
+  clock?: () => number;
+}
+/**
+ * `@atscript/db`-backed {@link FederatedIdentityStore}. Pass the resolved table
+ * for the `AoothFederatedIdentity` model shipped at
+ * `@aooth/user/atscript-db/federated-model`. The compound-unique
+ * `(provider, subject)` index makes `find` an O(1) point read and turns a
+ * cross-user re-link attempt into a `CONFLICT` (→ `ALREADY_EXISTS`); `userId`
+ * is a plain indexed column, so `listForUser` / `deleteAllForUser` scan it
+ * natively.
+ */
+declare class FederatedIdentityStoreAtscriptDb extends FederatedIdentityStore {
+  private readonly table;
+  private readonly clock;
+  constructor(opts: FederatedIdentityStoreAtscriptDbOptions);
+  find(provider: string, subject: string): Promise<FederatedIdentity | null>;
+  listForUser(userId: string): Promise<FederatedIdentity[]>;
+  link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
+  unlink(provider: string, subject: string): Promise<boolean>;
+  touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
+  deleteAllForUser(userId: string): Promise<number>;
+}
+//#endregion
 //#region src/atscript-db/index.d.ts
 /**
  * Persisted row shape — `UserCredentials` plus the consumer's custom user
@@ -36,30 +88,47 @@ interface AuthUserTable<TUserCustom extends object = object> {
 }
 interface UsersStoreAtscriptDbOptions<TUserCustom extends object> {
   table: AuthUserTable<TUserCustom>;
+  /**
+   * Ordered login-handle field names (e.g. email then phone), resolved from the
+   * model's `@aooth.user.*` annotations by the wiring layer (`handleFields` of
+   * `getAoothUserHandleSpec`). `findByHandle` falls back to a `{ [field]: handle }`
+   * lookup for each, in order, after `username`. Omit/empty to disable handle
+   * resolution (login by anything but `username` unavailable). The base credential
+   * model no longer hardcodes `email` — the field names are whatever the
+   * consumer's `.as` model annotates.
+   */
+  handleFields?: string[];
 }
 /**
  * `@atscript/db`-backed `UserStore`. Pass the resolved table for the
  * `AoothUserCredentials` (or a `.as` interface extending it) shipped at the
- * `@aooth/user/atscript-db/model.as` subpath.
+ * `@aooth/user/atscript-db/model.as` subpath. Identity reads use the
+ * `@meta.id` PK (`id`) and the unique `username` index, plus any
+ * annotation-resolved `handleFields`; writes key on `id`.
  */
 declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends UserStore<TUserCustom> {
   protected table: AuthUserTable<TUserCustom>;
+  /** Secondary handle fields tried (in order) by `findByHandle` after `username`. */
+  protected readonly handleFields: string[];
   constructor(opts: UsersStoreAtscriptDbOptions<TUserCustom>);
-  exists(username: string): Promise<boolean>;
-  findByUsername(username: string): Promise<(UserCredentials & TUserCustom) | null>;
+  exists(handle: string): Promise<boolean>;
+  findById(id: string): Promise<(UserCredentials & TUserCustom) | null>;
+  findByHandle(handle: string): Promise<(UserCredentials & TUserCustom) | null>;
+  findByIdentifier(value: string): Promise<(UserCredentials & TUserCustom) | null>;
   create(data: UserCredentials & TUserCustom): Promise<void>;
-  update(username: string, update: UserStoreUpdate): Promise<boolean>;
-  delete(username: string): Promise<boolean>;
+  update(id: string, update: UserStoreUpdate): Promise<boolean>;
+  delete(id: string): Promise<boolean>;
   /**
    * Inline retry loop rather than delegating to @atscript/db's
    * `withOptimisticRetry`: that helper expects the mutator to always return a
    * patch object, but our contract lets the mutator return `null` (the
-   * race-loser detects nothing to do — see `UserService.consumeBackupCode`).
-   * Bridging would need a sentinel exception. The version-bump + $cas
-   * atomicity still happen at the atscript-db table layer via the
-   * `expectedVersion` we thread through `update()`.
+   * race-loser detects nothing to do — used by callers whose mutator opts
+   * out of a write after re-reading state). Bridging would need a sentinel
+   * exception. The version-bump + $cas atomicity still happen at the
+   * atscript-db table layer via the `expectedVersion` we thread through
+   * `update()`.
    */
-  withCas(username: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+  withCas(id: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
-export { AuthUserTable, UserCredentialsRow, UsersStoreAtscriptDb };
+export { AuthUserTable, FederatedIdentityStoreAtscriptDb, type FederatedIdentityTable, UserCredentialsRow, UsersStoreAtscriptDb };

package/dist/atscript-db.d.mts

@@ -1,5 +1,57 @@
-import { S as UserCredentials, n as WithCasOptions, t as UserStore, w as UserStoreUpdate } from "./user-store-62LCSa8q.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-CI7Vgllp.mjs";
 
+//#region src/atscript-db/federated-identity-store.d.ts
+/**
+ * Structural surface of `AtscriptDbTable` covering exactly the methods this
+ * adapter calls — kept loose so `@aooth/user` doesn't pull `@atscript/db` types
+ * into its public surface. Consumers pass `db.getTable(AoothFederatedIdentity)`
+ * directly and TypeScript matches by-shape. Mirrors `AuthCredentialTable` from
+ * `@aooth/auth/atscript-db`.
+ */
+interface FederatedIdentityTable {
+  insertOne(row: FederatedIdentity): Promise<{
+    insertedId: unknown;
+  }>;
+  findOne(query: {
+    filter: Record<string, unknown>;
+  }): Promise<FederatedIdentity | null>;
+  findMany(query: {
+    filter?: Record<string, unknown>;
+  }): Promise<FederatedIdentity[]>;
+  replaceOne(row: FederatedIdentity): Promise<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>;
+  deleteMany(filter: Record<string, unknown>): Promise<{
+    deletedCount: number;
+  }>;
+}
+interface FederatedIdentityStoreAtscriptDbOptions {
+  table: FederatedIdentityTable;
+  /** Injectable clock for `linkedAt` / `lastLoginAt`. Defaults to `Date.now`. */
+  clock?: () => number;
+}
+/**
+ * `@atscript/db`-backed {@link FederatedIdentityStore}. Pass the resolved table
+ * for the `AoothFederatedIdentity` model shipped at
+ * `@aooth/user/atscript-db/federated-model`. The compound-unique
+ * `(provider, subject)` index makes `find` an O(1) point read and turns a
+ * cross-user re-link attempt into a `CONFLICT` (→ `ALREADY_EXISTS`); `userId`
+ * is a plain indexed column, so `listForUser` / `deleteAllForUser` scan it
+ * natively.
+ */
+declare class FederatedIdentityStoreAtscriptDb extends FederatedIdentityStore {
+  private readonly table;
+  private readonly clock;
+  constructor(opts: FederatedIdentityStoreAtscriptDbOptions);
+  find(provider: string, subject: string): Promise<FederatedIdentity | null>;
+  listForUser(userId: string): Promise<FederatedIdentity[]>;
+  link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
+  unlink(provider: string, subject: string): Promise<boolean>;
+  touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
+  deleteAllForUser(userId: string): Promise<number>;
+}
+//#endregion
 //#region src/atscript-db/index.d.ts
 /**
  * Persisted row shape — `UserCredentials` plus the consumer's custom user
@@ -36,30 +88,47 @@ interface AuthUserTable<TUserCustom extends object = object> {
 }
 interface UsersStoreAtscriptDbOptions<TUserCustom extends object> {
   table: AuthUserTable<TUserCustom>;
+  /**
+   * Ordered login-handle field names (e.g. email then phone), resolved from the
+   * model's `@aooth.user.*` annotations by the wiring layer (`handleFields` of
+   * `getAoothUserHandleSpec`). `findByHandle` falls back to a `{ [field]: handle }`
+   * lookup for each, in order, after `username`. Omit/empty to disable handle
+   * resolution (login by anything but `username` unavailable). The base credential
+   * model no longer hardcodes `email` — the field names are whatever the
+   * consumer's `.as` model annotates.
+   */
+  handleFields?: string[];
 }
 /**
  * `@atscript/db`-backed `UserStore`. Pass the resolved table for the
  * `AoothUserCredentials` (or a `.as` interface extending it) shipped at the
- * `@aooth/user/atscript-db/model.as` subpath.
+ * `@aooth/user/atscript-db/model.as` subpath. Identity reads use the
+ * `@meta.id` PK (`id`) and the unique `username` index, plus any
+ * annotation-resolved `handleFields`; writes key on `id`.
  */
 declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends UserStore<TUserCustom> {
   protected table: AuthUserTable<TUserCustom>;
+  /** Secondary handle fields tried (in order) by `findByHandle` after `username`. */
+  protected readonly handleFields: string[];
   constructor(opts: UsersStoreAtscriptDbOptions<TUserCustom>);
-  exists(username: string): Promise<boolean>;
-  findByUsername(username: string): Promise<(UserCredentials & TUserCustom) | null>;
+  exists(handle: string): Promise<boolean>;
+  findById(id: string): Promise<(UserCredentials & TUserCustom) | null>;
+  findByHandle(handle: string): Promise<(UserCredentials & TUserCustom) | null>;
+  findByIdentifier(value: string): Promise<(UserCredentials & TUserCustom) | null>;
   create(data: UserCredentials & TUserCustom): Promise<void>;
-  update(username: string, update: UserStoreUpdate): Promise<boolean>;
-  delete(username: string): Promise<boolean>;
+  update(id: string, update: UserStoreUpdate): Promise<boolean>;
+  delete(id: string): Promise<boolean>;
   /**
    * Inline retry loop rather than delegating to @atscript/db's
    * `withOptimisticRetry`: that helper expects the mutator to always return a
    * patch object, but our contract lets the mutator return `null` (the
-   * race-loser detects nothing to do — see `UserService.consumeBackupCode`).
-   * Bridging would need a sentinel exception. The version-bump + $cas
-   * atomicity still happen at the atscript-db table layer via the
-   * `expectedVersion` we thread through `update()`.
+   * race-loser detects nothing to do — used by callers whose mutator opts
+   * out of a write after re-reading state). Bridging would need a sentinel
+   * exception. The version-bump + $cas atomicity still happen at the
+   * atscript-db table layer via the `expectedVersion` we thread through
+   * `update()`.
    */
-  withCas(username: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
+  withCas(id: string, mutator: (current: UserCredentials & TUserCustom) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
 }
 //#endregion
-export { AuthUserTable, UserCredentialsRow, UsersStoreAtscriptDb };
+export { AuthUserTable, FederatedIdentityStoreAtscriptDb, type FederatedIdentityTable, UserCredentialsRow, UsersStoreAtscriptDb };

package/dist/atscript-db.mjs

@@ -1,4 +1,76 @@
-import { c as setAtPath, l as UserAuthError, t as UserStore } from "./user-store-BaBmH13V.mjs";
+import { d as UserAuthError, n as pickDefinedProfile, r as UserStore, t as FederatedIdentityStore, u as setAtPath } from "./federated-identity-store-CHW1xtMp.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/atscript-db/federated-identity-store.ts
+function isConflict$1(err) {
+	return typeof err === "object" && err !== null && err.code === "CONFLICT";
+}
+/**
+* `@atscript/db`-backed {@link FederatedIdentityStore}. Pass the resolved table
+* for the `AoothFederatedIdentity` model shipped at
+* `@aooth/user/atscript-db/federated-model`. The compound-unique
+* `(provider, subject)` index makes `find` an O(1) point read and turns a
+* cross-user re-link attempt into a `CONFLICT` (→ `ALREADY_EXISTS`); `userId`
+* is a plain indexed column, so `listForUser` / `deleteAllForUser` scan it
+* natively.
+*/
+var FederatedIdentityStoreAtscriptDb = class extends FederatedIdentityStore {
+	table;
+	clock;
+	constructor(opts) {
+		super();
+		this.table = opts.table;
+		this.clock = opts.clock ?? Date.now;
+	}
+	async find(provider, subject) {
+		return this.table.findOne({ filter: {
+			provider,
+			subject
+		} });
+	}
+	async listForUser(userId) {
+		return (await this.table.findMany({ filter: { userId } })).toSorted((a, b) => a.linkedAt - b.linkedAt);
+	}
+	async link(rec) {
+		const row = {
+			id: randomUUID(),
+			provider: rec.provider,
+			subject: rec.subject,
+			userId: rec.userId,
+			...pickDefinedProfile(rec),
+			linkedAt: this.clock()
+		};
+		try {
+			await this.table.insertOne(row);
+			return row;
+		} catch (e) {
+			if (isConflict$1(e)) throw new UserAuthError("ALREADY_EXISTS", `Provider account "${rec.provider}:${rec.subject}" is already linked`);
+			throw e;
+		}
+	}
+	async unlink(provider, subject) {
+		return (await this.table.deleteMany({
+			provider,
+			subject
+		})).deletedCount > 0;
+	}
+	async touchLogin(provider, subject, profile) {
+		const row = await this.table.findOne({ filter: {
+			provider,
+			subject
+		} });
+		if (!row) return;
+		const next = {
+			...row,
+			lastLoginAt: this.clock()
+		};
+		if (profile) Object.assign(next, pickDefinedProfile(profile));
+		await this.table.replaceOne(next);
+	}
+	async deleteAllForUser(userId) {
+		return (await this.table.deleteMany({ userId })).deletedCount;
+	}
+};
+//#endregion
 //#region src/atscript-db/index.ts
 function isConflict(err) {
 	return typeof err === "object" && err !== null && err.code === "CONFLICT";
@@ -6,19 +78,38 @@ function isConflict(err) {
 /**
 * `@atscript/db`-backed `UserStore`. Pass the resolved table for the
 * `AoothUserCredentials` (or a `.as` interface extending it) shipped at the
-* `@aooth/user/atscript-db/model.as` subpath.
+* `@aooth/user/atscript-db/model.as` subpath. Identity reads use the
+* `@meta.id` PK (`id`) and the unique `username` index, plus any
+* annotation-resolved `handleFields`; writes key on `id`.
 */
 var UsersStoreAtscriptDb = class extends UserStore {
 	table;
+	/** Secondary handle fields tried (in order) by `findByHandle` after `username`. */
+	handleFields;
 	constructor(opts) {
 		super();
 		this.table = opts.table;
+		this.handleFields = opts.handleFields ?? [];
 	}
-	async exists(username) {
-		return await this.table.count({ filter: { username } }) > 0;
+	async exists(handle) {
+		return await this.table.count({ filter: { username: handle } }) > 0;
 	}
-	async findByUsername(username) {
-		return await this.table.findOne({ filter: { username } }) ?? null;
+	async findById(id) {
+		return await this.table.findOne({ filter: { id } });
+	}
+	async findByHandle(handle) {
+		const byUsername = await this.table.findOne({ filter: { username: handle } });
+		if (byUsername) return byUsername;
+		for (const field of this.handleFields) {
+			const byHandle = await this.table.findOne({ filter: { [field]: handle } });
+			if (byHandle) return byHandle;
+		}
+		return null;
+	}
+	async findByIdentifier(value) {
+		const byId = await this.table.findOne({ filter: { id: value } });
+		if (byId) return byId;
+		return this.findByHandle(value);
 	}
 	async create(data) {
 		try {
@@ -28,34 +119,40 @@ var UsersStoreAtscriptDb = class extends UserStore {
 			throw e;
 		}
 	}
-	async update(username, update) {
-		const patch = { username };
+	async update(id, update) {
+		const patch = { id };
 		if (update.set) Object.assign(patch, update.set);
 		if (update.inc) for (const [path, amount] of Object.entries(update.inc)) setAtPath(patch, path, { $inc: amount });
 		if (Object.keys(patch).length <= 1) return true;
 		if (update.expectedVersion !== void 0) patch.$cas = { version: update.expectedVersion };
-		return (await this.table.updateOne(patch)).matchedCount > 0;
+		try {
+			return (await this.table.updateOne(patch)).matchedCount > 0;
+		} catch (e) {
+			if (isConflict(e)) throw new UserAuthError("ALREADY_EXISTS", "Update conflicts with an existing unique value");
+			throw e;
+		}
 	}
-	async delete(username) {
-		return (await this.table.deleteMany({ username })).deletedCount > 0;
+	async delete(id) {
+		return (await this.table.deleteMany({ id })).deletedCount > 0;
 	}
 	/**
 	* Inline retry loop rather than delegating to @atscript/db's
 	* `withOptimisticRetry`: that helper expects the mutator to always return a
 	* patch object, but our contract lets the mutator return `null` (the
-	* race-loser detects nothing to do — see `UserService.consumeBackupCode`).
-	* Bridging would need a sentinel exception. The version-bump + $cas
-	* atomicity still happen at the atscript-db table layer via the
-	* `expectedVersion` we thread through `update()`.
+	* race-loser detects nothing to do — used by callers whose mutator opts
+	* out of a write after re-reading state). Bridging would need a sentinel
+	* exception. The version-bump + $cas atomicity still happen at the
+	* atscript-db table layer via the `expectedVersion` we thread through
+	* `update()`.
 	*/
-	async withCas(username, mutator, opts) {
+	async withCas(id, mutator, opts) {
 		const maxAttempts = opts?.maxAttempts ?? 2;
 		for (let attempt = 0; attempt < maxAttempts; attempt++) {
-			const current = await this.findByUsername(username);
+			const current = await this.findById(id);
 			if (!current) throw new UserAuthError("NOT_FOUND");
 			const patch = mutator(current);
 			if (patch === null) return;
-			if (await this.update(username, {
+			if (await this.update(id, {
 				...patch,
 				expectedVersion: current.version ?? 0
 			})) return;
@@ -64,4 +161,4 @@ var UsersStoreAtscriptDb = class extends UserStore {
 	}
 };
 //#endregion
-export { UsersStoreAtscriptDb };
+export { FederatedIdentityStoreAtscriptDb, UsersStoreAtscriptDb };