@aooth/user 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,6 +2,14 @@
2
2
  interface UserCredentials {
3
3
  id: string;
4
4
  username: string;
5
+ /**
6
+ * Unique login/contact handle. Indexed `@db.index.unique 'email_idx'` on the
7
+ * `AoothUserCredentials` model so it is independently unique from `username`
8
+ * and resolvable via `UserStore.findByHandle` / `findByIdentifier`. Optional
9
+ * because not every deployment populates it (and the invite flow sets
10
+ * `username := email`).
11
+ */
12
+ email?: string;
5
13
  /**
6
14
  * Server-managed optimistic-concurrency counter. Bumped by `UserStore.update`
7
15
  * on every successful write; checked against `UserStoreUpdate.expectedVersion`
@@ -13,12 +21,6 @@ interface UserCredentials {
13
21
  password: PasswordData;
14
22
  account: AccountData;
15
23
  mfa: MfaData;
16
- /**
17
- * Hashed backup codes (SHA-256, hex-encoded). Generated via
18
- * `UserService.generateBackupCodes`. Undefined when the user has not
19
- * enrolled backup codes; an empty array means all codes were consumed.
20
- */
21
- backupCodes?: string[];
22
24
  /**
23
25
  * Persisted device-trust records ("remember this device, skip MFA next
24
26
  * time"). Managed by `UserService.{issue,add,verify,revoke,list}TrustedDevice`.
@@ -225,30 +227,152 @@ interface WithCasOptions {
225
227
  */
226
228
  maxAttempts?: number;
227
229
  }
230
+ /**
231
+ * Storage seam for user credentials, keyed by the stable surrogate **`id`**
232
+ * (the token subject). Reads come in three flavours:
233
+ *
234
+ * - `findById` — strict, by the surrogate id; the canonical identity read used
235
+ * by authenticated flows that resolve the session subject (`getUserId()`).
236
+ * - `findByHandle` — deterministic LOGIN resolver (`username` then `email`).
237
+ * - `findByIdentifier` — permissive internal/admin/recovery lookup (`id`, then
238
+ * `username`, then `email`).
239
+ *
240
+ * Writes (`update`/`delete`/`withCas`) all key on the surrogate `id`.
241
+ */
228
242
  declare abstract class UserStore<T extends object = object> {
229
- abstract exists(username: string): Promise<boolean>;
230
- abstract findByUsername(username: string): Promise<(UserCredentials & T) | null>;
243
+ /** True when a user with this login handle (`username`) exists. */
244
+ abstract exists(handle: string): Promise<boolean>;
245
+ /**
246
+ * Strict read by the stable surrogate `id` — the token subject. Authenticated
247
+ * flows resolve the session subject (`useAuth().getUserId()`) through this.
248
+ */
249
+ abstract findById(id: string): Promise<(UserCredentials & T) | null>;
250
+ /**
251
+ * Deterministic LOGIN resolver: matches `username` exactly, then `email`
252
+ * exactly (in that order). Intentionally NOT a permissive `$or` — `id`,
253
+ * `username`, and `email` are all strings, so a permissive match could
254
+ * silently resolve a value that is one user's username and another's email
255
+ * to an arbitrary account.
256
+ */
257
+ abstract findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
258
+ /**
259
+ * Permissive lookup for internal / admin / recovery callers: `id`, then
260
+ * `username`, then `email` (ordered, first match). NOT for the login path —
261
+ * use `findByHandle` there.
262
+ */
263
+ abstract findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
231
264
  abstract create(data: UserCredentials & T): Promise<void>;
232
- abstract update(username: string, update: UserStoreUpdate): Promise<boolean>;
265
+ /** Apply a patch to the row identified by the stable `id`. */
266
+ abstract update(id: string, update: UserStoreUpdate): Promise<boolean>;
233
267
  /**
234
- * Hard-delete the row. Returns `true` when a row was removed, `false` when
235
- * the username was not found. Used by `UserService.deleteUser` (and in turn
236
- * by the invite workflow's `auth/invite/cancel` step).
268
+ * Hard-delete the row by `id`. Returns `true` when a row was removed, `false`
269
+ * when the id was not found.
237
270
  */
238
- abstract delete(username: string): Promise<boolean>;
271
+ abstract delete(id: string): Promise<boolean>;
239
272
  /**
240
- * Run a read-modify-write cycle under optimistic concurrency. Each attempt
241
- * fetches the current row, calls `mutator` with it, and applies the returned
242
- * patch under CAS (`expectedVersion = current.version`). On CAS miss the
243
- * cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null` to
244
- * exit early without writing — used for "race-loser detects nothing left to
245
- * do" paths (e.g. the backup code was already consumed by the winner).
273
+ * Run a read-modify-write cycle under optimistic concurrency, keyed by `id`.
274
+ * Each attempt re-reads (via `findById`), calls `mutator`, and applies the
275
+ * returned patch under CAS (`expectedVersion = current.version`). On CAS miss
276
+ * the cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null`
277
+ * to exit early without writing (race-loser "nothing left to do").
246
278
  *
247
- * Throws `UserAuthError("NOT_FOUND")` when no row matches `username`, or
248
- * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors
249
- * thrown from inside `mutator` propagate immediately without retry.
279
+ * Throws `UserAuthError("NOT_FOUND")` when no row matches `id`, or
280
+ * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors thrown
281
+ * from inside `mutator` propagate immediately without retry.
282
+ */
283
+ abstract withCas(id: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
284
+ }
285
+ //#endregion
286
+ //#region src/store/federated-identity-store.d.ts
287
+ /**
288
+ * Display fields snapshotted from an IdP profile onto a federated-identity row.
289
+ * Refreshed on each login via {@link FederatedIdentityStore.touchLogin}; never
290
+ * a join key (the stable join is `(provider, subject)`). Phase-2's
291
+ * `NormalizedProfile` (in `@aooth/idp`) is a structural superset of this — it
292
+ * is declared HERE rather than imported so `@aooth/user` keeps no dependency on
293
+ * the layer above it.
294
+ */
295
+ interface FederatedProfileSnapshot {
296
+ email?: string;
297
+ emailVerified?: boolean;
298
+ displayName?: string;
299
+ avatarUrl?: string;
300
+ }
301
+ /**
302
+ * Copy only the DEFINED display fields — so a `touchLogin` / `link` with a
303
+ * partial profile (e.g. Apple omitting the email on a repeat login) never
304
+ * overwrites a stored value with `undefined`. Shared by every
305
+ * {@link FederatedIdentityStore} impl.
306
+ */
307
+ declare function pickDefinedProfile(src: FederatedProfileSnapshot): FederatedProfileSnapshot;
308
+ /**
309
+ * A persisted federated-identity row: one external-provider account
310
+ * (`provider` + the IdP's stable `subject`) linked to exactly one aooth user
311
+ * (`userId` = the user's surrogate `id`). Mirrors the shipped
312
+ * `AoothFederatedIdentity` `.as` model by construction.
313
+ */
314
+ interface FederatedIdentity extends FederatedProfileSnapshot {
315
+ /** Surrogate PK. Server-assigned (`@db.default.uuid` / `randomUUID`). */
316
+ id: string;
317
+ provider: string;
318
+ subject: string;
319
+ /** Owner — the user's stable surrogate `id`. */
320
+ userId: string;
321
+ /** When the link was first created. */
322
+ linkedAt: number;
323
+ /** Last federated login through this identity; absent until first `touchLogin`. */
324
+ lastLoginAt?: number;
325
+ }
326
+ /**
327
+ * Input to {@link FederatedIdentityStore.link} — the identity keys + owner plus
328
+ * an optional first-login profile snapshot. `id` and `linkedAt` are assigned by
329
+ * the store.
330
+ */
331
+ interface NewFederatedIdentity extends FederatedProfileSnapshot {
332
+ provider: string;
333
+ subject: string;
334
+ userId: string;
335
+ }
336
+ /**
337
+ * Storage seam for the account-linking table (RFC IDP.md §3.3). The stable
338
+ * lookup key is the composite `(provider, subject)`; a user may own many rows
339
+ * (one per linked provider account), so `userId` reads return a list.
340
+ *
341
+ * In-memory + atscript-db implementations ship alongside; the abstract surface
342
+ * keeps the federated-login core (`@aooth/idp`, phase 2) storage-agnostic.
343
+ */
344
+ declare abstract class FederatedIdentityStore {
345
+ /** Resolve a provider account to its linked row, or `null`. The federated-login hot path. */
346
+ abstract find(provider: string, subject: string): Promise<FederatedIdentity | null>;
347
+ /** All identities linked to a user — the "connected accounts" view. */
348
+ abstract listForUser(userId: string): Promise<FederatedIdentity[]>;
349
+ /**
350
+ * Link a provider account to a user. Throws `UserAuthError("ALREADY_EXISTS")`
351
+ * when `(provider, subject)` is already linked — to ANY user — which is the
352
+ * DB-enforced guarantee that one provider account maps to one aooth user.
353
+ */
354
+ abstract link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
355
+ /**
356
+ * Remove a single provider link. Returns `true` when a row was removed,
357
+ * `false` when `(provider, subject)` was not linked. (The "don't strand the
358
+ * user without a usable credential" guard lives in the service layer, not
359
+ * here — this is the raw delete.)
360
+ */
361
+ abstract unlink(provider: string, subject: string): Promise<boolean>;
362
+ /**
363
+ * Stamp `lastLoginAt = now` and merge any DEFINED `profile` fields onto the
364
+ * row. Profile is optional and merged field-by-field, so a provider that
365
+ * omits the email on a repeat login (e.g. Apple after the first auth) never
366
+ * nulls the stored snapshot. No-op when `(provider, subject)` is not linked.
367
+ */
368
+ abstract touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
369
+ /**
370
+ * Remove every identity linked to a user — GDPR hard-delete / "disconnect
371
+ * everything". Returns the number of rows removed. The app-level complement
372
+ * to a DB `onDelete cascade` (which this design deliberately does not use —
373
+ * `userId` is a plain column, not an FK).
250
374
  */
251
- abstract withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
375
+ abstract deleteAllForUser(userId: string): Promise<number>;
252
376
  }
253
377
  //#endregion
254
- export { UserServiceConfig as C, UserCredentials as S, PolicyCheckResult as _, LockStatus as a, TrustedDeviceRecord as b, MfaData as c, PasswordConfig as d, PasswordData as f, PasswordPolicyInstance as g, PasswordPolicyEvalFn as h, DeepPartial as i, MfaMethod as l, PasswordPolicyDef as m, WithCasOptions as n, LockoutConfig as o, PasswordPolicyContext as p, AccountData as r, LoginResult as s, UserStore as t, MfaMethodInfo as u, TotpConfig as v, UserStoreUpdate as w, UserAuthErrorType as x, TransferablePolicy as y };
378
+ export { TotpConfig as C, UserCredentials as D, UserAuthErrorType as E, UserServiceConfig as O, PolicyCheckResult as S, TrustedDeviceRecord as T, PasswordData as _, pickDefinedProfile as a, PasswordPolicyEvalFn as b, AccountData as c, LockoutConfig as d, LoginResult as f, PasswordConfig as g, MfaMethodInfo as h, NewFederatedIdentity as i, UserStoreUpdate as k, DeepPartial as l, MfaMethod as m, FederatedIdentityStore as n, UserStore as o, MfaData as p, FederatedProfileSnapshot as r, WithCasOptions as s, FederatedIdentity as t, LockStatus as u, PasswordPolicyContext as v, TransferablePolicy as w, PasswordPolicyInstance as x, PasswordPolicyDef as y };
@@ -2,6 +2,14 @@
2
2
  interface UserCredentials {
3
3
  id: string;
4
4
  username: string;
5
+ /**
6
+ * Unique login/contact handle. Indexed `@db.index.unique 'email_idx'` on the
7
+ * `AoothUserCredentials` model so it is independently unique from `username`
8
+ * and resolvable via `UserStore.findByHandle` / `findByIdentifier`. Optional
9
+ * because not every deployment populates it (and the invite flow sets
10
+ * `username := email`).
11
+ */
12
+ email?: string;
5
13
  /**
6
14
  * Server-managed optimistic-concurrency counter. Bumped by `UserStore.update`
7
15
  * on every successful write; checked against `UserStoreUpdate.expectedVersion`
@@ -13,12 +21,6 @@ interface UserCredentials {
13
21
  password: PasswordData;
14
22
  account: AccountData;
15
23
  mfa: MfaData;
16
- /**
17
- * Hashed backup codes (SHA-256, hex-encoded). Generated via
18
- * `UserService.generateBackupCodes`. Undefined when the user has not
19
- * enrolled backup codes; an empty array means all codes were consumed.
20
- */
21
- backupCodes?: string[];
22
24
  /**
23
25
  * Persisted device-trust records ("remember this device, skip MFA next
24
26
  * time"). Managed by `UserService.{issue,add,verify,revoke,list}TrustedDevice`.
@@ -225,30 +227,152 @@ interface WithCasOptions {
225
227
  */
226
228
  maxAttempts?: number;
227
229
  }
230
+ /**
231
+ * Storage seam for user credentials, keyed by the stable surrogate **`id`**
232
+ * (the token subject). Reads come in three flavours:
233
+ *
234
+ * - `findById` — strict, by the surrogate id; the canonical identity read used
235
+ * by authenticated flows that resolve the session subject (`getUserId()`).
236
+ * - `findByHandle` — deterministic LOGIN resolver (`username` then `email`).
237
+ * - `findByIdentifier` — permissive internal/admin/recovery lookup (`id`, then
238
+ * `username`, then `email`).
239
+ *
240
+ * Writes (`update`/`delete`/`withCas`) all key on the surrogate `id`.
241
+ */
228
242
  declare abstract class UserStore<T extends object = object> {
229
- abstract exists(username: string): Promise<boolean>;
230
- abstract findByUsername(username: string): Promise<(UserCredentials & T) | null>;
243
+ /** True when a user with this login handle (`username`) exists. */
244
+ abstract exists(handle: string): Promise<boolean>;
245
+ /**
246
+ * Strict read by the stable surrogate `id` — the token subject. Authenticated
247
+ * flows resolve the session subject (`useAuth().getUserId()`) through this.
248
+ */
249
+ abstract findById(id: string): Promise<(UserCredentials & T) | null>;
250
+ /**
251
+ * Deterministic LOGIN resolver: matches `username` exactly, then `email`
252
+ * exactly (in that order). Intentionally NOT a permissive `$or` — `id`,
253
+ * `username`, and `email` are all strings, so a permissive match could
254
+ * silently resolve a value that is one user's username and another's email
255
+ * to an arbitrary account.
256
+ */
257
+ abstract findByHandle(handle: string): Promise<(UserCredentials & T) | null>;
258
+ /**
259
+ * Permissive lookup for internal / admin / recovery callers: `id`, then
260
+ * `username`, then `email` (ordered, first match). NOT for the login path —
261
+ * use `findByHandle` there.
262
+ */
263
+ abstract findByIdentifier(value: string): Promise<(UserCredentials & T) | null>;
231
264
  abstract create(data: UserCredentials & T): Promise<void>;
232
- abstract update(username: string, update: UserStoreUpdate): Promise<boolean>;
265
+ /** Apply a patch to the row identified by the stable `id`. */
266
+ abstract update(id: string, update: UserStoreUpdate): Promise<boolean>;
233
267
  /**
234
- * Hard-delete the row. Returns `true` when a row was removed, `false` when
235
- * the username was not found. Used by `UserService.deleteUser` (and in turn
236
- * by the invite workflow's `auth/invite/cancel` step).
268
+ * Hard-delete the row by `id`. Returns `true` when a row was removed, `false`
269
+ * when the id was not found.
237
270
  */
238
- abstract delete(username: string): Promise<boolean>;
271
+ abstract delete(id: string): Promise<boolean>;
239
272
  /**
240
- * Run a read-modify-write cycle under optimistic concurrency. Each attempt
241
- * fetches the current row, calls `mutator` with it, and applies the returned
242
- * patch under CAS (`expectedVersion = current.version`). On CAS miss the
243
- * cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null` to
244
- * exit early without writing — used for "race-loser detects nothing left to
245
- * do" paths (e.g. the backup code was already consumed by the winner).
273
+ * Run a read-modify-write cycle under optimistic concurrency, keyed by `id`.
274
+ * Each attempt re-reads (via `findById`), calls `mutator`, and applies the
275
+ * returned patch under CAS (`expectedVersion = current.version`). On CAS miss
276
+ * the cycle repeats up to `opts.maxAttempts`. The mutator MAY return `null`
277
+ * to exit early without writing (race-loser "nothing left to do").
246
278
  *
247
- * Throws `UserAuthError("NOT_FOUND")` when no row matches `username`, or
248
- * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors
249
- * thrown from inside `mutator` propagate immediately without retry.
279
+ * Throws `UserAuthError("NOT_FOUND")` when no row matches `id`, or
280
+ * `UserAuthError("CAS_EXHAUSTED")` when retries are saturated. Errors thrown
281
+ * from inside `mutator` propagate immediately without retry.
282
+ */
283
+ abstract withCas(id: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
284
+ }
285
+ //#endregion
286
+ //#region src/store/federated-identity-store.d.ts
287
+ /**
288
+ * Display fields snapshotted from an IdP profile onto a federated-identity row.
289
+ * Refreshed on each login via {@link FederatedIdentityStore.touchLogin}; never
290
+ * a join key (the stable join is `(provider, subject)`). Phase-2's
291
+ * `NormalizedProfile` (in `@aooth/idp`) is a structural superset of this — it
292
+ * is declared HERE rather than imported so `@aooth/user` keeps no dependency on
293
+ * the layer above it.
294
+ */
295
+ interface FederatedProfileSnapshot {
296
+ email?: string;
297
+ emailVerified?: boolean;
298
+ displayName?: string;
299
+ avatarUrl?: string;
300
+ }
301
+ /**
302
+ * Copy only the DEFINED display fields — so a `touchLogin` / `link` with a
303
+ * partial profile (e.g. Apple omitting the email on a repeat login) never
304
+ * overwrites a stored value with `undefined`. Shared by every
305
+ * {@link FederatedIdentityStore} impl.
306
+ */
307
+ declare function pickDefinedProfile(src: FederatedProfileSnapshot): FederatedProfileSnapshot;
308
+ /**
309
+ * A persisted federated-identity row: one external-provider account
310
+ * (`provider` + the IdP's stable `subject`) linked to exactly one aooth user
311
+ * (`userId` = the user's surrogate `id`). Mirrors the shipped
312
+ * `AoothFederatedIdentity` `.as` model by construction.
313
+ */
314
+ interface FederatedIdentity extends FederatedProfileSnapshot {
315
+ /** Surrogate PK. Server-assigned (`@db.default.uuid` / `randomUUID`). */
316
+ id: string;
317
+ provider: string;
318
+ subject: string;
319
+ /** Owner — the user's stable surrogate `id`. */
320
+ userId: string;
321
+ /** When the link was first created. */
322
+ linkedAt: number;
323
+ /** Last federated login through this identity; absent until first `touchLogin`. */
324
+ lastLoginAt?: number;
325
+ }
326
+ /**
327
+ * Input to {@link FederatedIdentityStore.link} — the identity keys + owner plus
328
+ * an optional first-login profile snapshot. `id` and `linkedAt` are assigned by
329
+ * the store.
330
+ */
331
+ interface NewFederatedIdentity extends FederatedProfileSnapshot {
332
+ provider: string;
333
+ subject: string;
334
+ userId: string;
335
+ }
336
+ /**
337
+ * Storage seam for the account-linking table (RFC IDP.md §3.3). The stable
338
+ * lookup key is the composite `(provider, subject)`; a user may own many rows
339
+ * (one per linked provider account), so `userId` reads return a list.
340
+ *
341
+ * In-memory + atscript-db implementations ship alongside; the abstract surface
342
+ * keeps the federated-login core (`@aooth/idp`, phase 2) storage-agnostic.
343
+ */
344
+ declare abstract class FederatedIdentityStore {
345
+ /** Resolve a provider account to its linked row, or `null`. The federated-login hot path. */
346
+ abstract find(provider: string, subject: string): Promise<FederatedIdentity | null>;
347
+ /** All identities linked to a user — the "connected accounts" view. */
348
+ abstract listForUser(userId: string): Promise<FederatedIdentity[]>;
349
+ /**
350
+ * Link a provider account to a user. Throws `UserAuthError("ALREADY_EXISTS")`
351
+ * when `(provider, subject)` is already linked — to ANY user — which is the
352
+ * DB-enforced guarantee that one provider account maps to one aooth user.
353
+ */
354
+ abstract link(rec: NewFederatedIdentity): Promise<FederatedIdentity>;
355
+ /**
356
+ * Remove a single provider link. Returns `true` when a row was removed,
357
+ * `false` when `(provider, subject)` was not linked. (The "don't strand the
358
+ * user without a usable credential" guard lives in the service layer, not
359
+ * here — this is the raw delete.)
360
+ */
361
+ abstract unlink(provider: string, subject: string): Promise<boolean>;
362
+ /**
363
+ * Stamp `lastLoginAt = now` and merge any DEFINED `profile` fields onto the
364
+ * row. Profile is optional and merged field-by-field, so a provider that
365
+ * omits the email on a repeat login (e.g. Apple after the first auth) never
366
+ * nulls the stored snapshot. No-op when `(provider, subject)` is not linked.
367
+ */
368
+ abstract touchLogin(provider: string, subject: string, profile?: FederatedProfileSnapshot): Promise<void>;
369
+ /**
370
+ * Remove every identity linked to a user — GDPR hard-delete / "disconnect
371
+ * everything". Returns the number of rows removed. The app-level complement
372
+ * to a DB `onDelete cascade` (which this design deliberately does not use —
373
+ * `userId` is a plain column, not an FK).
250
374
  */
251
- abstract withCas(username: string, mutator: (current: UserCredentials & T) => UserStoreUpdate | null, opts?: WithCasOptions): Promise<void>;
375
+ abstract deleteAllForUser(userId: string): Promise<number>;
252
376
  }
253
377
  //#endregion
254
- export { UserServiceConfig as C, UserCredentials as S, PolicyCheckResult as _, LockStatus as a, TrustedDeviceRecord as b, MfaData as c, PasswordConfig as d, PasswordData as f, PasswordPolicyInstance as g, PasswordPolicyEvalFn as h, DeepPartial as i, MfaMethod as l, PasswordPolicyDef as m, WithCasOptions as n, LockoutConfig as o, PasswordPolicyContext as p, AccountData as r, LoginResult as s, UserStore as t, MfaMethodInfo as u, TotpConfig as v, UserStoreUpdate as w, UserAuthErrorType as x, TransferablePolicy as y };
378
+ export { TotpConfig as C, UserCredentials as D, UserAuthErrorType as E, UserServiceConfig as O, PolicyCheckResult as S, TrustedDeviceRecord as T, PasswordData as _, pickDefinedProfile as a, PasswordPolicyEvalFn as b, AccountData as c, LockoutConfig as d, LoginResult as f, PasswordConfig as g, MfaMethodInfo as h, NewFederatedIdentity as i, UserStoreUpdate as k, DeepPartial as l, MfaMethod as m, FederatedIdentityStore as n, UserStore as o, MfaData as p, FederatedProfileSnapshot as r, WithCasOptions as s, FederatedIdentity as t, LockStatus as u, PasswordPolicyContext as v, TransferablePolicy as w, PasswordPolicyInstance as x, PasswordPolicyDef as y };
@@ -15,6 +15,8 @@ const defaultMessages = {
15
15
  CAS_EXHAUSTED: "Update conflict — please retry"
16
16
  };
17
17
  var UserAuthError = class extends Error {
18
+ type;
19
+ details;
18
20
  name = "UserAuthError";
19
21
  constructor(type, message, details) {
20
22
  super(message ?? defaultMessages[type]);
@@ -92,8 +94,51 @@ function incrementAtPath(obj, path, amount) {
92
94
  }
93
95
  //#endregion
94
96
  //#region src/store/user-store.ts
97
+ /**
98
+ * Storage seam for user credentials, keyed by the stable surrogate **`id`**
99
+ * (the token subject). Reads come in three flavours:
100
+ *
101
+ * - `findById` — strict, by the surrogate id; the canonical identity read used
102
+ * by authenticated flows that resolve the session subject (`getUserId()`).
103
+ * - `findByHandle` — deterministic LOGIN resolver (`username` then `email`).
104
+ * - `findByIdentifier` — permissive internal/admin/recovery lookup (`id`, then
105
+ * `username`, then `email`).
106
+ *
107
+ * Writes (`update`/`delete`/`withCas`) all key on the surrogate `id`.
108
+ */
95
109
  var UserStore = class {};
96
110
  //#endregion
111
+ //#region src/store/federated-identity-store.ts
112
+ /**
113
+ * Copy only the DEFINED display fields — so a `touchLogin` / `link` with a
114
+ * partial profile (e.g. Apple omitting the email on a repeat login) never
115
+ * overwrites a stored value with `undefined`. Shared by every
116
+ * {@link FederatedIdentityStore} impl.
117
+ */
118
+ function pickDefinedProfile(src) {
119
+ const out = {};
120
+ if (src.email !== void 0) out.email = src.email;
121
+ if (src.emailVerified !== void 0) out.emailVerified = src.emailVerified;
122
+ if (src.displayName !== void 0) out.displayName = src.displayName;
123
+ if (src.avatarUrl !== void 0) out.avatarUrl = src.avatarUrl;
124
+ return out;
125
+ }
126
+ /**
127
+ * Storage seam for the account-linking table (RFC IDP.md §3.3). The stable
128
+ * lookup key is the composite `(provider, subject)`; a user may own many rows
129
+ * (one per linked provider account), so `userId` reads return a list.
130
+ *
131
+ * In-memory + atscript-db implementations ship alongside; the abstract surface
132
+ * keeps the federated-login core (`@aooth/idp`, phase 2) storage-agnostic.
133
+ */
134
+ var FederatedIdentityStore = class {};
135
+ //#endregion
136
+ Object.defineProperty(exports, "FederatedIdentityStore", {
137
+ enumerable: true,
138
+ get: function() {
139
+ return FederatedIdentityStore;
140
+ }
141
+ });
97
142
  Object.defineProperty(exports, "UserAuthError", {
98
143
  enumerable: true,
99
144
  get: function() {
@@ -142,6 +187,12 @@ Object.defineProperty(exports, "maskPhone", {
142
187
  return maskPhone;
143
188
  }
144
189
  });
190
+ Object.defineProperty(exports, "pickDefinedProfile", {
191
+ enumerable: true,
192
+ get: function() {
193
+ return pickDefinedProfile;
194
+ }
195
+ });
145
196
  Object.defineProperty(exports, "setAtPath", {
146
197
  enumerable: true,
147
198
  get: function() {