@dereekb/firebase 14.0.1 → 14.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "14.0.1",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -22,10 +22,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.0.1",
-    "@dereekb/model": "14.0.1",
-    "@dereekb/rxjs": "14.0.1",
-    "@dereekb/util": "14.0.1",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/rxjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "@firebase/rules-unit-testing": "5.0.2",
     "@marcbachmann/cel-js": "^8.0.0",
     "@typescript-eslint/parser": "8.69.0",

package/src/lib/common/firestore/snapshot/snapshot.field.d.ts

@@ -25,6 +25,8 @@
  * - **Arrays**: `firestoreArray`, `firestoreUniqueArray`, `firestoreEnumArray`, `firestoreEncodedArray`
  * - **Maps**: `firestoreMap`, `firestoreEncodedObjectMap`, `firestoreObjectMap`, `firestoreArrayMap`
  * - **Objects**: `firestoreSubObject`, `firestoreObjectArray`
+ * - **Unmodelled json**: `optionalFirestorePassthroughJsonField` (native map, queryable),
+ *   `optionalFirestoreJsonStringField` (serialized string, holds json a map cannot)
  * - **Specialized**: `firestoreUID`, `firestoreLatLngString`, `firestoreWebsiteLink`,
  *   `firestoreDateCellRange`, `firestoreBitwiseSet`, `firestoreUnitedStatesAddress`
  */
@@ -378,6 +380,71 @@ export interface OptionalFirestorePassthroughJsonFieldConfig<T extends object> e
  * @__NO_SIDE_EFFECTS__
  */
 export declare function optionalFirestorePassthroughJsonField<T extends object>(config?: OptionalFirestorePassthroughJsonFieldConfig<T>): FirestoreModelFieldMapFunctionsConfig<Maybe<T>, Maybe<T>>;
+/**
+ * Configuration for {@link optionalFirestoreJsonStringField}.
+ *
+ * Extends {@link CopyValueDeepConfig} for parity with {@link optionalFirestorePassthroughJsonField}, so a
+ * field can move between the two without its write-side filtering changing meaning.
+ *
+ * `defaultReadValue` is deliberately absent: the base field applies it in DATA space, which here is the
+ * serialized string rather than the object, and a default expressed as raw json is a worse thing to
+ * write than the `?? {}` at the read site it would replace. That leaves nothing for a type parameter to
+ * describe, so — unlike its passthrough sibling — this config is not generic.
+ */
+export interface OptionalFirestoreJsonStringFieldConfig extends CopyValueDeepConfig {
+    /**
+     * Whether to store `null` instead of a value that has no keys left after filtering. Defaults to `false`.
+     */
+    readonly dontStoreIfEmpty?: boolean;
+}
+/**
+ * Creates a field mapping configuration for an optional object field that is stored as a JSON STRING.
+ *
+ * The counterpart to {@link optionalFirestorePassthroughJsonField}, and the one to reach for when the
+ * json is arbitrary rather than merely unmodelled: a json schema, a tool definition, whatever an llm
+ * returned. The passthrough field stores a native Firestore map, and a map cannot represent every legal
+ * json value — Firestore forbids an array directly inside an array, which an array-valued `enum`,
+ * `const`, `default`, or `examples` produces immediately. That write does not degrade, it FAILS, and it
+ * fails from inside whatever was doing the writing with an opaque "invalid nested entity" error.
+ *
+ * Serializing sidesteps the entire Firestore type system: the stored value is one string, so anything
+ * `JSON.stringify` accepts round-trips exactly, including the shapes a map rejects. The cost is that the
+ * field is no longer queryable and no longer readable in the Firestore console — pick this one when the
+ * json is never a query target, and the passthrough field when it is.
+ *
+ * Two behaviours worth knowing:
+ *
+ * - A value only `JSON.stringify` knows how to narrow is narrowed. A `Date` becomes an ISO string and
+ *   stays a string on read, where the passthrough field would have kept it a `Timestamp`. Anything
+ *   carrying non-json values wants the passthrough field, not this one.
+ * - Reads tolerate a legacy native map, so a field migrated from
+ *   {@link optionalFirestorePassthroughJsonField} keeps reading documents written before the switch. New
+ *   writes are always strings, so a document converts itself the next time it is written.
+ *
+ * @param config - Filtering and storage configuration. Defaults to stripping `undefined` values at every depth.
+ * @returns A field mapping configuration for optional json values stored as a string.
+ *
+ * @dbxModelSnapshotField
+ * @dbxModelSnapshotFieldCategory object
+ * @dbxModelSnapshotFieldOptional true
+ * @dbxModelSnapshotFieldTags json, string, serialized, stringify, object, raw, optional, arbitrary, schema, factory
+ * @dbxModelSnapshotFieldRelated optional-firestore-passthrough-json-field, optional-firestore-field, firestore-sub-object
+ * @template T - Type of the model field. Stored as a json string.
+ *
+ * @example
+ * ```ts
+ * fields: {
+ *   // { model: 'm', text: { format: { schema: { enum: [['a']] } } } }
+ *   // stores as the string '{"model":"m","text":{"format":{"schema":{"enum":[["a"]]}}}}'
+ *   config: optionalFirestoreJsonStringField<MyVendorConfig>(),
+ *   // store null rather than the string '{}' when nothing survives the filtering
+ *   usage: optionalFirestoreJsonStringField<MyVendorUsage>({ filterEmptyValues: true, dontStoreIfEmpty: true })
+ * }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function optionalFirestoreJsonStringField<T extends object>(config?: OptionalFirestoreJsonStringFieldConfig): FirestoreModelFieldMapFunctionsConfig<Maybe<T>, Maybe<string>>;
 /**
  * Configuration for a Firestore field with default model value but without conversion functions.
  *

package/src/lib/model/calendar/calendar.d.ts

@@ -242,7 +242,7 @@ export declare const calendarEventItemFields: {
     st: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<CalendarEventStatus>, Maybe<CalendarEventStatus>>;
     q: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<number>, Maybe<number>>;
     ca: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string[]>, Maybe<string[]>>;
-    x: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<Readonly<Record<string, string>>>, Maybe<Readonly<Record<string, string>>>>;
+    x: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<Readonly<Record<string, string>>>, Maybe<string>>;
     cat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, number>;
     uat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, number>;
 };

package/src/lib/model/calendar/calendar.id.d.ts

@@ -70,6 +70,12 @@ export type CalendarType = string;
  *
  * Keys are stored WITHOUT the "X-" prefix and are prefixed at emit time, which is what makes it impossible
  * for a stored key to shadow a standard property like SUMMARY.
+ *
+ * Persisted as a json STRING rather than a native Firestore map, for consistency with the other
+ * unmodelled-json fields in the workspace. Nothing here forces that — a flat map of strings is a shape
+ * Firestore stores perfectly well — so the reason is uniformity plus room for the type to widen, not a
+ * limit this type can currently reach. Nothing queries into it, which is the condition that makes string
+ * storage free.
  */
 export type CalendarExtensionData = Readonly<Record<string, string>>;
 /**

package/src/lib/model/formspace/formspace.d.ts

@@ -162,6 +162,12 @@ export declare const formSpaceFileSubObject: import("../..").FirestoreSubObjectF
  *
  * PASS-THROUGH: the framework never interprets it. The type's handler is what gives it meaning, and an app
  * narrows this generic to its own interface at the point it reads the space.
+ *
+ * Persisted as a json STRING rather than a native Firestore map, because this is genuinely arbitrary json
+ * and a map cannot hold all of it: Firestore forbids an array directly inside an array, which a form
+ * reaches the moment a field holds a grid, a matrix, or a repeated group of multi-selects. That write
+ * FAILS rather than degrading, so the shape a form could submit would otherwise be bounded by the storage
+ * rather than by the type. Nothing queries into `d`, which is what makes string storage free here.
  */
 export type FormSpaceData = Record<string, unknown>;
 /**

package/src/lib/model/userexternalconnection/index.d.ts

@@ -4,3 +4,4 @@ export * from './userexternalconnection.util';
 export * from './userexternalconnection.query';
 export * from './userexternalconnection.api';
 export * from './userexternalconnection.action';
+export * from './userexternalconnection.error';

package/src/lib/model/userexternalconnection/userexternalconnection.api.d.ts

@@ -1,4 +1,5 @@
 import { type Type } from 'arktype';
+import { type Maybe } from '@dereekb/util';
 import { type InferredTargetModelParams } from '../../common/model/model/model.param';
 import { type FirebaseFunctionTypeConfigMap, type ModelFirebaseCreateFunction, type ModelFirebaseCrudFunction, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap } from '../../client';
 import { type UserExternalConnectionTypes } from './userexternalconnection';
@@ -41,8 +42,38 @@ export interface ReadUserExternalConnectionAuthorizeStateParams extends Inferred
      * The provider type to begin connecting to.
      */
     readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Which handoff the state begins. Defaults to `connect`.
+     *
+     * - `connect` — attach the provider as a DATA connection, with the data scopes.
+     * - `link` — make the provider a LOGIN METHOD for the already-signed-in caller, with the sign-in
+     *   scopes. A separate round trip because the two scope sets are not guaranteed to be the same,
+     *   so a data grant cannot be assumed to cover an identity read.
+     *
+     * Absent means `connect`, so a client minting a state before `link` existed still gets one.
+     */
+    readonly mode?: Maybe<'connect' | 'link'>;
 }
 export declare const readUserExternalConnectionAuthorizeStateParamsType: Type<ReadUserExternalConnectionAuthorizeStateParams>;
+/**
+ * Parameters for removing a provider as a LOGIN METHOD for the current user.
+ *
+ * Distinct from {@link DisconnectUserExternalConnectionParams}, and strictly larger: a disconnect
+ * drops the data connection and leaves the login link in place, whereas an unlink removes the login
+ * link AND the data connection and its credentials. "Stop using my Discord token" and "Discord is no
+ * longer how I log in" are different requests, so they are different calls.
+ *
+ * If no target model is provided, the current user's connection document is assumed.
+ *
+ * @dbxModelApiParams
+ */
+export interface UnlinkUserExternalConnectionLoginParams extends InferredTargetModelParams {
+    /**
+     * The provider type to unlink.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+}
+export declare const unlinkUserExternalConnectionLoginParamsType: Type<UnlinkUserExternalConnectionLoginParams>;
 /**
  * The opaque, short-lived `state` to carry through a provider's OAuth handoff.
  *
@@ -91,9 +122,17 @@ export type UserExternalConnectionModelCrudFunctionsConfig = {
              * Disconnects the current user from the given provider.
              *
              * Removes the provider's credentials and its entry in one transaction, and recomputes the
-             * connected-provider array from the result.
+             * connected-provider array from the result. The provider's LOGIN LINK is retained — a data
+             * connection ending says nothing about whether the provider is still a way to sign in.
              */
             disconnect: DisconnectUserExternalConnectionParams;
+            /**
+             * Removes the given provider as a login method for the current user.
+             *
+             * Removes the login link, the entry, and the credentials in one transaction. Refused when it
+             * would leave the account with no way to sign back in.
+             */
+            unlink: UnlinkUserExternalConnectionLoginParams;
         };
     };
 };
@@ -111,6 +150,7 @@ export declare abstract class UserExternalConnectionFunctions implements ModelFi
         };
         updateUserExternalConnection: {
             disconnect: ModelFirebaseCrudFunction<DisconnectUserExternalConnectionParams>;
+            unlink: ModelFirebaseCrudFunction<UnlinkUserExternalConnectionLoginParams>;
         };
     };
 }

package/src/lib/model/userexternalconnection/userexternalconnection.d.ts

@@ -1,8 +1,8 @@
-import { type Maybe } from '@dereekb/util';
+import { type EmailAddress, type Maybe } from '@dereekb/util';
 import { type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
 import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext } from '../../common';
 import { type UserRelated, type UserRelatedById } from '../user';
-import { type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionProviderType } from './userexternalconnection.id';
+import { type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionExternalAccountKey, type UserExternalConnectionProviderType } from './userexternalconnection.id';
 /**
  * Provides access to the {@link UserExternalConnection} collection.
  *
@@ -99,6 +99,69 @@ export interface UserExternalConnectionEntry {
  * Map of provider type to the user's connection state for that provider.
  */
 export type UserExternalConnectionEntryMap = Record<UserExternalConnectionProviderType, UserExternalConnectionEntry>;
+/**
+ * A provider that is a LOGIN METHOD for this account.
+ *
+ * Separate from {@link UserExternalConnectionEntry} rather than a flag on it, because the two describe
+ * different kinds of fact and have different lifecycles. Every field on an entry is DERIVED from the
+ * credentials stored beside it — take the credentials away and the entry has nothing left to say — so
+ * an entry is a statement about a grant. A login link is a statement about the ACCOUNT: "this Discord
+ * user is how this person signs in". It survives the credentials expiring, being revoked by the
+ * provider, and the user disconnecting the data connection, and it is removed only by an explicit
+ * unlink.
+ *
+ * Folding it into the entry would mean a disconnect had to choose between destroying the sign-in
+ * binding and retaining a `disconnected` entry that lies about the credentials. Two maps make the
+ * choice unnecessary.
+ *
+ * Written ONLY by an identity-scoped OAuth round trip (the sign-in or `link` direction), never by the
+ * data connect flow: the scopes a data connection is granted are not guaranteed to cover what an
+ * identity read needs.
+ *
+ * @dbxModelSubObject
+ */
+export interface UserExternalConnectionLogin {
+    /**
+     * Identifier of the linked account within the provider. REQUIRED: this IS the identity.
+     *
+     * @dbxModelVariable externalAccountId
+     */
+    ea: UserExternalConnectionExternalAccountId;
+    /**
+     * Human-readable label for the linked account (e.g. the provider-side username).
+     *
+     * @dbxModelVariable label
+     */
+    l?: Maybe<string>;
+    /**
+     * The email the provider reported at link time, when it reported one.
+     *
+     * @dbxModelVariable email
+     */
+    em?: Maybe<EmailAddress>;
+    /**
+     * Whether the PROVIDER considered that email verified at link time.
+     *
+     * @dbxModelVariable emailVerified
+     */
+    emv?: Maybe<boolean>;
+    /**
+     * Date the provider was FIRST linked. Preserved across relinks.
+     *
+     * @dbxModelVariable linkedAt
+     */
+    lat: Date;
+    /**
+     * Date this link was last updated at.
+     *
+     * @dbxModelVariable updatedAt
+     */
+    uat: Date;
+}
+/**
+ * Map of provider type to the login link the user holds for that provider.
+ */
+export type UserExternalConnectionLoginMap = Record<UserExternalConnectionProviderType, UserExternalConnectionLogin>;
 /**
  * The client-readable half of a user's third-party OAuth connection state.
  *
@@ -136,6 +199,37 @@ export interface UserExternalConnection extends UserRelated, UserRelatedById {
      * @dbxModelVariable connectedProviderTypes
      */
     c: UserExternalConnectionProviderType[];
+    /**
+     * Per-provider LOGIN LINKS, keyed by provider type.
+     *
+     * A provider present here is a way this account signs in. Independent of `e`: a provider can be
+     * linked without a data connection (the sign-in wrote the link and the app did not opt into
+     * `signInConnects`), connected without being linked (a connect-only provider), or both.
+     *
+     * @dbxModelVariable logins
+     */
+    li: UserExternalConnectionLoginMap;
+    /**
+     * DERIVED from `e` UNION `li`: the `<providerType>:<externalAccountId>` key of every entry that
+     * names an external account, plus every login link's.
+     *
+     * The `c` array's sibling, and it exists for the same reason: Firestore cannot query across map
+     * keys, so `e.<provider>.ea` is unreachable. `c` answers "who is connected to X?"; this answers
+     * "who IS X?" — the lookup a sign-in performs to resolve a third-party identity to a Firebase uid.
+     *
+     * Both maps contribute because either one alone loses the answer. Sourcing it from `e` only meant
+     * disconnecting a data connection silently destroyed the sign-in binding and the next sign-in minted
+     * a second Firebase user; sourcing it from `li` only would lose a connect-established account that
+     * was never a login method.
+     *
+     * Unlike `c`, membership is NOT filtered by status. Which Discord account a user is is a fact
+     * about their identity, not about whether their credentials currently work: a returning user whose
+     * token expired (`error`) must still resolve to the same uid, or a sign-in would mint them a
+     * second account. Recomputed on every write and never passed in by a caller.
+     *
+     * @dbxModelVariable externalAccountKeys
+     */
+    ec?: Maybe<UserExternalConnectionExternalAccountKey[]>;
     /**
      * Date this document was last updated at.
      *
@@ -147,12 +241,17 @@ export interface UserExternalConnection extends UserRelated, UserRelatedById {
  * Roles for a UserExternalConnection. Users can read their own connection state; all writes go
  * through the server.
  *
- * `connect` and `disconnect` are called out separately from `update` because they are the only
- * operations a client can reach, so an app can withhold either one (a user allowed to drop a
+ * `connect`, `disconnect` and `unlink` are called out separately from `update` because they are the
+ * only operations a client can reach, so an app can withhold any one of them (a user allowed to drop a
  * connection but not to add another, or the reverse) without also withholding the server-driven
  * writes that share `update`.
+ *
+ * `unlink` is distinct from `disconnect` because they remove different things: a disconnect drops the
+ * data connection and keeps the login link, an unlink removes the login link AND everything the
+ * disconnect would have. Removing a way to sign in is the more consequential of the two, so an app can
+ * grant one without the other.
  */
-export type UserExternalConnectionRoles = GrantedReadRole | GrantedUpdateRole | 'connect' | 'disconnect';
+export type UserExternalConnectionRoles = GrantedReadRole | GrantedUpdateRole | 'connect' | 'disconnect' | 'unlink';
 export declare class UserExternalConnectionDocument extends AbstractFirestoreDocument<UserExternalConnection, UserExternalConnectionDocument, typeof userExternalConnectionIdentity> {
     get modelIdentity(): import("../..").RootFirestoreModelIdentity<"userExternalConnection", "uec">;
 }
@@ -169,6 +268,17 @@ export declare const userExternalConnectionEntryFields: {
     uat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, string>;
     er: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<UserExternalConnectionErrorCode>, Maybe<UserExternalConnectionErrorCode>>;
 };
+/**
+ * Field conversions for a {@link UserExternalConnectionLogin}.
+ */
+export declare const userExternalConnectionLoginFields: {
+    ea: import("../..").FirestoreModelFieldMapFunctionsConfig<string, string>;
+    l: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string>, Maybe<string>>;
+    em: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string>, Maybe<string>>;
+    emv: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<boolean>, Maybe<boolean>>;
+    lat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, string>;
+    uat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, string>;
+};
 export declare const userExternalConnectionConverter: import("../..").SnapshotConverterFunctions<UserExternalConnection, Partial<import("@dereekb/util").ReplaceType<UserExternalConnection, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Copies the document id into `uid` on write, so the stored uid can never drift from the document id.

package/src/lib/model/userexternalconnection/userexternalconnection.error.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error codes the UserExternalConnection server surfaces.
+ *
+ * Declared HERE rather than beside the `HttpsError` factories in `@dereekb/firebase-server/model`
+ * because both sides need them: the server throws them, and the client branches on them — a login
+ * page deciding what to say about a refused sign-in, or a client treating a raced
+ * `..._ALREADY_EXISTS` as success. A code the browser cannot import is a code the browser has to
+ * hard-code.
+ */
+export declare const USER_EXTERNAL_CONNECTION_PROVIDER_NOT_CONNECTED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_PROVIDER_NOT_CONNECTED";
+export declare const USER_EXTERNAL_CONNECTION_PROVIDER_NOT_ALLOWED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_PROVIDER_NOT_ALLOWED";
+export declare const USER_EXTERNAL_CONNECTION_ALREADY_EXISTS_ERROR_CODE = "USER_EXTERNAL_CONNECTION_ALREADY_EXISTS";
+export declare const USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRED";
+export declare const USER_EXTERNAL_CONNECTION_EXTERNAL_ACCOUNT_IN_USE_ERROR_CODE = "USER_EXTERNAL_CONNECTION_EXTERNAL_ACCOUNT_IN_USE";
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_NOT_ENABLED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_SIGN_IN_NOT_ENABLED";
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_DENIED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_SIGN_IN_DENIED";
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_EMAIL_CONFLICT_ERROR_CODE = "USER_EXTERNAL_CONNECTION_SIGN_IN_EMAIL_CONFLICT";
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_USER_MISSING_ERROR_CODE = "USER_EXTERNAL_CONNECTION_SIGN_IN_USER_MISSING";
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_IDENTITY_UNAVAILABLE_ERROR_CODE = "USER_EXTERNAL_CONNECTION_SIGN_IN_IDENTITY_UNAVAILABLE";
+/**
+ * Refuses an unlink that would leave the account with no way back in.
+ */
+export declare const USER_EXTERNAL_CONNECTION_UNLINK_LAST_LOGIN_METHOD_ERROR_CODE = "USER_EXTERNAL_CONNECTION_UNLINK_LAST_LOGIN_METHOD";
+/**
+ * Refuses a `link` round trip for a provider the app has not enabled for sign-in.
+ *
+ * Distinct from `..._SIGN_IN_NOT_ENABLED`: nothing is signing in — an already-authenticated user asked
+ * to make the provider a login method, and the same `policy.signIn` opt-in governs both.
+ */
+export declare const USER_EXTERNAL_CONNECTION_LINK_NOT_ENABLED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_LINK_NOT_ENABLED";
+/**
+ * The only error codes a failed SIGN-IN reports back to the browser.
+ *
+ * An ALLOWLIST rather than a filter: a failed sign-in redirects to a URL the user can read, so
+ * anything that reaches it is public. Passing whatever code an internal failure happened to carry
+ * would leak the shape of that failure, and passing a message would leak its text — so a code absent
+ * from this set is reported as nothing at all.
+ *
+ * Shared with the client so a login page's copy map and the server's allowlist cannot drift.
+ */
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_REPORTABLE_ERROR_CODES: ReadonlySet<string>;

package/src/lib/model/userexternalconnection/userexternalconnection.id.d.ts

@@ -49,3 +49,37 @@ export type UserExternalConnectionCapability = string;
  * Identifier for the connected account within the third-party provider.
  */
 export type UserExternalConnectionExternalAccountId = string;
+/**
+ * The delimiter joining a provider type to an external account id in a
+ * {@link UserExternalConnectionExternalAccountKey}.
+ *
+ * A colon is safe on both sides: {@link UserExternalConnectionProviderType} must already be a valid
+ * Firestore map key (no dots or slashes), and the key is only ever a stored/queried string VALUE,
+ * never a document id or field path.
+ */
+export declare const USER_EXTERNAL_CONNECTION_EXTERNAL_ACCOUNT_KEY_DELIMITER = ":";
+/**
+ * A `<providerType>:<externalAccountId>` pair identifying one third-party account globally.
+ *
+ * The provider type is part of the key because an external account id is only unique WITHIN a
+ * provider — a Discord snowflake and a Zoom user id could collide as bare strings.
+ */
+export type UserExternalConnectionExternalAccountKey = string;
+export interface UserExternalConnectionExternalAccountKeyInput {
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly externalAccountId: UserExternalConnectionExternalAccountId;
+}
+/**
+ * Builds the {@link UserExternalConnectionExternalAccountKey} for a provider/account pair.
+ *
+ * The SOLE producer of the key format: the derivation that stores it and the query that reads it
+ * both go through here, so the two can never disagree about the delimiter.
+ *
+ * @param input - The provider type and external account id to join.
+ * @param input.providerType - The provider the account belongs to.
+ * @param input.externalAccountId - The provider's stable id for the account.
+ * @returns The external account key.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionExternalAccountKey(input: UserExternalConnectionExternalAccountKeyInput): UserExternalConnectionExternalAccountKey;

package/src/lib/model/userexternalconnection/userexternalconnection.query.d.ts

@@ -1,5 +1,5 @@
 import { type FirestoreQueryConstraint } from '../../common';
-import { type UserExternalConnectionProviderType } from './userexternalconnection.id';
+import { type UserExternalConnectionExternalAccountKeyInput, type UserExternalConnectionProviderType } from './userexternalconnection.id';
 /**
  * Query for the UserExternalConnection documents that are currently connected to the given provider.
  *
@@ -17,3 +17,24 @@ import { type UserExternalConnectionProviderType } from './userexternalconnectio
  * @dbxModelFirebaseIndexScope COLLECTION
  */
 export declare function userExternalConnectionsWithConnectedProviderQuery(providerType: UserExternalConnectionProviderType): FirestoreQueryConstraint[];
+/**
+ * Query for the UserExternalConnection document holding the given third-party account.
+ *
+ * The sign-in counterpart of {@link userExternalConnectionsWithConnectedProviderQuery}: that one
+ * asks "which users are connected to this provider?", this one asks "which user IS this account?".
+ * Both exist because a per-user document makes `e.<provider>.ea` unqueryable.
+ *
+ * Matches at ANY entry status — see the `ec` field docs. Expect at most one result when the
+ * provider's policy declares the connection unique, but the caller must still handle more than one:
+ * uniqueness is enforced at write time and a provider may only have started enforcing it recently.
+ *
+ * @param input - The provider type and external account id to search for.
+ * @param input.providerType - The provider the account belongs to.
+ * @param input.externalAccountId - The provider's stable id for the account.
+ * @returns Firestore query constraints matching the user holding that external account.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel UserExternalConnection
+ * @dbxModelFirebaseIndexScope COLLECTION
+ */
+export declare function userExternalConnectionsWithExternalAccountQuery(input: UserExternalConnectionExternalAccountKeyInput): FirestoreQueryConstraint[];