@aooth/user 0.1.6 → 0.1.8

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-oRjhnR5l.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,76 @@ 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`) plus the unique `username` / `email` indexes; writes key
+* on `id`.
 */
-var UsersStoreAtscriptDb = class extends require_user_store.UserStore {
+var UsersStoreAtscriptDb = class extends require_federated_identity_store.UserStore {
 	table;
 	constructor(opts) {
 		super();
 		this.table = opts.table;
 	}
-	async exists(username) {
-		return await this.table.count({ filter: { username } }) > 0;
+	async exists(handle) {
+		return await this.table.count({ filter: { username: handle } }) > 0;
+	}
+	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;
+		return await this.table.findOne({ filter: { email: handle } });
 	}
-	async findByUsername(username) {
-		return await this.table.findOne({ filter: { username } }) ?? 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;
 	}
-	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-B3EStUfT.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-DEEed8lA.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
@@ -40,26 +92,31 @@ interface UsersStoreAtscriptDbOptions<TUserCustom extends object> {
 /**
  * `@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`) plus the unique `username` / `email` indexes; writes key
+ * on `id`.
  */
 declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends UserStore<TUserCustom> {
   protected table: AuthUserTable<TUserCustom>;
   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-C1lxahSB.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-DEEed8lA.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
@@ -40,26 +92,31 @@ interface UsersStoreAtscriptDbOptions<TUserCustom extends object> {
 /**
  * `@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`) plus the unique `username` / `email` indexes; writes key
+ * on `id`.
  */
 declare class UsersStoreAtscriptDb<TUserCustom extends object = object> extends UserStore<TUserCustom> {
   protected table: AuthUserTable<TUserCustom>;
   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-Cmc7jBrw.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,7 +78,9 @@ 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`) plus the unique `username` / `email` indexes; writes key
+* on `id`.
 */
 var UsersStoreAtscriptDb = class extends UserStore {
 	table;
@@ -14,11 +88,21 @@ var UsersStoreAtscriptDb = class extends UserStore {
 		super();
 		this.table = opts.table;
 	}
-	async exists(username) {
-		return await this.table.count({ filter: { username } }) > 0;
+	async exists(handle) {
+		return await this.table.count({ filter: { username: handle } }) > 0;
+	}
+	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;
+		return await this.table.findOne({ filter: { email: handle } });
 	}
-	async findByUsername(username) {
-		return await this.table.findOne({ filter: { username } }) ?? 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 +112,35 @@ 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;
 	}
-	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 +149,4 @@ var UsersStoreAtscriptDb = class extends UserStore {
 	}
 };
 //#endregion
-export { UsersStoreAtscriptDb };
+export { FederatedIdentityStoreAtscriptDb, UsersStoreAtscriptDb };

package/dist/{user-store-BaBmH13V.mjs → federated-identity-store-Cmc7jBrw.mjs}

@@ -15,6 +15,8 @@ const defaultMessages = {
 	CAS_EXHAUSTED: "Update conflict — please retry"
 };
 var UserAuthError = class extends Error {
+	type;
+	details;
 	name = "UserAuthError";
 	constructor(type, message, details) {
 		super(message ?? defaultMessages[type]);
@@ -92,6 +94,43 @@ function incrementAtPath(obj, path, amount) {
 }
 //#endregion
 //#region src/store/user-store.ts
+/**
+* Storage seam for user credentials, keyed by the stable surrogate **`id`**
+* (the token subject). Reads come in three flavours:
+*
+* - `findById` — strict, by the surrogate id; the canonical identity read used
+*   by authenticated flows that resolve the session subject (`getUserId()`).
+* - `findByHandle` — deterministic LOGIN resolver (`username` then `email`).
+* - `findByIdentifier` — permissive internal/admin/recovery lookup (`id`, then
+*   `username`, then `email`).
+*
+* Writes (`update`/`delete`/`withCas`) all key on the surrogate `id`.
+*/
 var UserStore = class {};
 //#endregion
-export { maskEmail as a, setAtPath as c, incrementAtPath as i, UserAuthError as l, deepMerge as n, maskMfaValue as o, generateSecureRandom as r, maskPhone as s, UserStore as t };
+//#region src/store/federated-identity-store.ts
+/**
+* Copy only the DEFINED display fields — so a `touchLogin` / `link` with a
+* partial profile (e.g. Apple omitting the email on a repeat login) never
+* overwrites a stored value with `undefined`. Shared by every
+* {@link FederatedIdentityStore} impl.
+*/
+function pickDefinedProfile(src) {
+	const out = {};
+	if (src.email !== void 0) out.email = src.email;
+	if (src.emailVerified !== void 0) out.emailVerified = src.emailVerified;
+	if (src.displayName !== void 0) out.displayName = src.displayName;
+	if (src.avatarUrl !== void 0) out.avatarUrl = src.avatarUrl;
+	return out;
+}
+/**
+* Storage seam for the account-linking table (RFC IDP.md §3.3). The stable
+* lookup key is the composite `(provider, subject)`; a user may own many rows
+* (one per linked provider account), so `userId` reads return a list.
+*
+* In-memory + atscript-db implementations ship alongside; the abstract surface
+* keeps the federated-login core (`@aooth/idp`, phase 2) storage-agnostic.
+*/
+var FederatedIdentityStore = class {};
+//#endregion
+export { generateSecureRandom as a, maskMfaValue as c, UserAuthError as d, deepMerge as i, maskPhone as l, pickDefinedProfile as n, incrementAtPath as o, UserStore as r, maskEmail as s, FederatedIdentityStore as t, setAtPath as u };