@dereekb/firebase-server 14.0.1 → 14.1.0

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

@@ -29,13 +29,29 @@ export declare const TESTING_USER_EXTERNAL_CONNECTION_STATE_SECRET: AES256GCMEnc
  */
 export declare const DEFAULT_USER_EXTERNAL_CONNECTION_STATE_EXPIRATION: Milliseconds;
 /**
- * The payload carried inside an encrypted external-connection OAuth `state`.
+ * How long a minted sign-in ticket stays valid.
+ *
+ * Far shorter than a state: the ticket is redeemed by a page that has just been redirected to, so the
+ * whole window is one client-side navigation plus one POST.
  */
-export interface UserExternalConnectionStatePayload {
-    /**
-     * The user the handoff belongs to.
-     */
-    readonly uid: FirebaseAuthUserId;
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_TICKET_EXPIRATION: Milliseconds;
+/**
+ * Which direction a handoff runs in.
+ *
+ * - `connect` — an ALREADY authenticated user is attaching a third-party account. The state carries
+ *   their uid, minted by an authenticated call before the redirect.
+ * - `signin` — an anonymous visitor is authenticating THROUGH the third party. There is no uid yet;
+ *   the state carries a client-supplied PKCE challenge instead, which the ticket exchange answers.
+ * - `link` — an ALREADY authenticated user is making the third party a LOGIN METHOD for their account.
+ *   Carries their uid like a connect, but runs the sign-in scopes and writes only the login link. A
+ *   third mode rather than a flag on `connect` because the two request different scopes and produce
+ *   different writes, and because a state minted for one must not be usable for the other.
+ */
+export type UserExternalConnectionStateMode = 'connect' | 'signin' | 'link';
+/**
+ * Fields shared by both {@link UserExternalConnectionStatePayload} branches.
+ */
+export interface UserExternalConnectionStatePayloadBase {
     /**
      * The provider the handoff was started for.
      *
@@ -47,17 +63,166 @@ export interface UserExternalConnectionStatePayload {
      * Epoch milliseconds after which the state is rejected.
      */
     readonly exp: number;
+    /**
+     * The PKCE code verifier the authorize request sent the challenge for — the PROVIDER-facing half
+     * of the flow, unrelated to `challenge` below.
+     *
+     * Held here rather than in a server-side store because the state is already an
+     * encrypted-and-authenticated envelope only this server can read, which is exactly what a verifier
+     * needs. Optional so a state minted before PKCE was added still exchanges.
+     */
+    readonly cv?: Maybe<string>;
+}
+/**
+ * A `connect` state: an authenticated user attaching a provider.
+ */
+export interface UserExternalConnectionConnectStatePayload extends UserExternalConnectionStatePayloadBase {
+    /**
+     * Absent on states minted before sign-in mode existed, which is why an ABSENT mode means `connect`
+     * — a state already in flight when this shipped must still verify.
+     */
+    readonly mode?: Maybe<'connect'>;
+    /**
+     * The user the handoff belongs to.
+     */
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * A `signin` state: an anonymous visitor authenticating through a provider.
+ */
+export interface UserExternalConnectionSignInStatePayload extends UserExternalConnectionStatePayloadBase {
+    readonly mode: 'signin';
+    /**
+     * The CLIENT's PKCE challenge (base64url SHA-256 of a verifier held in the browser).
+     *
+     * Binds the eventual ticket to the browser that started the flow: a stolen ticket is useless
+     * without the verifier, which never leaves the originating tab.
+     */
+    readonly challenge: string;
+    /**
+     * Optional app path to return to, already validated against the app's allowlist before minting.
+     */
+    readonly returnPath?: Maybe<string>;
 }
 /**
- * Who a verified state belongs to.
+ * A `link` state: an authenticated user making a provider a login method for their account.
+ *
+ * Shaped like a connect — it carries the uid, and is minted by the same authenticated
+ * `read:authorizeState` call — and differs only in the mode, which is what selects the sign-in scopes
+ * on the way out and the link write on the way back.
  */
-export interface UserExternalConnectionStateActor {
+export interface UserExternalConnectionLinkStatePayload extends UserExternalConnectionStatePayloadBase {
+    readonly mode: 'link';
+    /**
+     * The user the link belongs to.
+     */
     readonly uid: FirebaseAuthUserId;
 }
-export interface MintUserExternalConnectionStateInput {
+/**
+ * The payload carried inside an encrypted external-connection OAuth `state`.
+ */
+export type UserExternalConnectionStatePayload = UserExternalConnectionConnectStatePayload | UserExternalConnectionSignInStatePayload | UserExternalConnectionLinkStatePayload;
+/**
+ * The payload carried inside an encrypted sign-in ticket.
+ *
+ * Shares the state's secret and envelope, and is distinguished from it by {@link USER_EXTERNAL_CONNECTION_TICKET_PAYLOAD_TYPE}:
+ * without that tag a captured state could be submitted where a ticket is expected.
+ */
+export interface UserExternalConnectionSignInTicketPayload {
+    readonly t: typeof USER_EXTERNAL_CONNECTION_TICKET_PAYLOAD_TYPE;
+    /**
+     * The Firebase custom token to hand back once the verifier proves possession.
+     */
+    readonly customToken: string;
+    /**
+     * The same client challenge the state carried.
+     */
+    readonly challenge: string;
+    /**
+     * The user the token was minted for. Returned only for logging/telemetry at the redemption site.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * Epoch milliseconds after which the ticket is rejected.
+     */
+    readonly exp: number;
+}
+/**
+ * Type tag distinguishing a ticket payload from a state payload under the shared secret.
+ */
+export declare const USER_EXTERNAL_CONNECTION_TICKET_PAYLOAD_TYPE = "uec-signin-ticket";
+/**
+ * A verified `connect` state — the user it belongs to.
+ */
+export interface UserExternalConnectionConnectStateActor {
+    readonly mode: 'connect';
+    readonly uid: FirebaseAuthUserId;
+    readonly codeVerifier?: Maybe<string>;
+}
+/**
+ * A verified `signin` state. Carries no uid: resolving one is the callback's job.
+ */
+export interface UserExternalConnectionSignInStateActor {
+    readonly mode: 'signin';
+    readonly challenge: string;
+    readonly codeVerifier?: Maybe<string>;
+    readonly returnPath?: Maybe<string>;
+}
+/**
+ * A verified `link` state — the user the login link will be written for.
+ */
+export interface UserExternalConnectionLinkStateActor {
+    readonly mode: 'link';
+    readonly uid: FirebaseAuthUserId;
+    readonly codeVerifier?: Maybe<string>;
+}
+/**
+ * Who (or what) a verified state belongs to.
+ */
+export type UserExternalConnectionStateActor = UserExternalConnectionConnectStateActor | UserExternalConnectionSignInStateActor | UserExternalConnectionLinkStateActor;
+/**
+ * Returns whether a verified actor came from a `signin` state.
+ *
+ * @param actor - The verified actor to narrow.
+ * @returns True when the actor is a sign-in actor.
+ */
+export declare function isUserExternalConnectionSignInStateActor(actor: Maybe<UserExternalConnectionStateActor>): actor is UserExternalConnectionSignInStateActor;
+/**
+ * Returns whether a verified actor came from a `link` state.
+ *
+ * @param actor - The verified actor to narrow.
+ * @returns True when the actor is a link actor.
+ */
+export declare function isUserExternalConnectionLinkStateActor(actor: Maybe<UserExternalConnectionStateActor>): actor is UserExternalConnectionLinkStateActor;
+export interface MintUserExternalConnectionConnectStateInput {
+    readonly mode?: Maybe<'connect'>;
     readonly uid: FirebaseAuthUserId;
     readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The PKCE code verifier whose challenge the authorize request sends to the provider.
+     */
+    readonly codeVerifier?: Maybe<string>;
 }
+export interface MintUserExternalConnectionSignInStateInput {
+    readonly mode: 'signin';
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The client's PKCE challenge, already validated as present.
+     */
+    readonly challenge: string;
+    readonly returnPath?: Maybe<string>;
+    readonly codeVerifier?: Maybe<string>;
+}
+export interface MintUserExternalConnectionLinkStateInput {
+    readonly mode: 'link';
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The PKCE code verifier whose challenge the authorize request sends to the provider.
+     */
+    readonly codeVerifier?: Maybe<string>;
+}
+export type MintUserExternalConnectionStateInput = MintUserExternalConnectionConnectStateInput | MintUserExternalConnectionSignInStateInput | MintUserExternalConnectionLinkStateInput;
 export interface VerifyUserExternalConnectionStateInput {
     readonly state: Maybe<string>;
     /**
@@ -65,12 +230,35 @@ export interface VerifyUserExternalConnectionStateInput {
      */
     readonly providerType: UserExternalConnectionProviderType;
 }
+export interface MintUserExternalConnectionTicketInput {
+    readonly customToken: string;
+    readonly challenge: string;
+    readonly uid: FirebaseAuthUserId;
+}
+export interface VerifyUserExternalConnectionTicketInput {
+    readonly ticket: Maybe<string>;
+    /**
+     * The PKCE code verifier the browser retained. Hashed and compared to the ticket's challenge.
+     */
+    readonly verifier: Maybe<string>;
+}
+/**
+ * A redeemed sign-in ticket.
+ */
+export interface UserExternalConnectionSignInTicket {
+    readonly customToken: string;
+    readonly uid: FirebaseAuthUserId;
+}
 export interface UserExternalConnectionStateCoderConfig {
     readonly secret: AES256GCMEncryptionSecret;
     /**
      * How long a minted state stays valid. Defaults to {@link DEFAULT_USER_EXTERNAL_CONNECTION_STATE_EXPIRATION}.
      */
     readonly expiresIn?: Maybe<Milliseconds>;
+    /**
+     * How long a minted sign-in ticket stays valid. Defaults to {@link DEFAULT_USER_EXTERNAL_CONNECTION_TICKET_EXPIRATION}.
+     */
+    readonly ticketExpiresIn?: Maybe<Milliseconds>;
 }
 /**
  * Mints and verifies the OAuth `state` for external-connection handoffs.
@@ -80,14 +268,27 @@ export interface UserExternalConnectionStateCoderConfig {
  */
 export declare abstract class UserExternalConnectionStateCoder {
     /**
-     * Mints a short-lived state for a user's connect handoff with a provider.
+     * Mints a short-lived state for a connect or sign-in handoff with a provider.
      */
     abstract readonly mintState: (input: MintUserExternalConnectionStateInput) => string;
     /**
-     * Resolves the user a state belongs to, or null when it is absent, tampered with, expired, or was
-     * minted for a different provider.
+     * Resolves who a state belongs to, or null when it is absent, tampered with, expired, or was minted
+     * for a different provider.
      */
     abstract readonly verifyState: (input: VerifyUserExternalConnectionStateInput) => Maybe<UserExternalConnectionStateActor>;
+    /**
+     * Mints a short-lived ticket carrying a custom token, redeemable only by the browser holding the
+     * verifier for its challenge.
+     *
+     * The ticket exists so the custom token never rides in a URL, where it would land in browser
+     * history, the Referer header, and any proxy's access log.
+     */
+    abstract readonly mintTicket: (input: MintUserExternalConnectionTicketInput) => string;
+    /**
+     * Redeems a ticket against the verifier the browser retained, or resolves null when the ticket is
+     * absent, tampered with, expired, or the verifier does not answer its challenge.
+     */
+    abstract readonly verifyTicket: (input: VerifyUserExternalConnectionTicketInput) => Promise<Maybe<UserExternalConnectionSignInTicket>>;
 }
 /**
  * Creates the coder that mints and verifies the OAuth `state` for external-connection handoffs.

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

@@ -0,0 +1,81 @@
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+/**
+ * Identifies the caller a throttle decision is made about.
+ *
+ * A client IP is the only thing an unauthenticated sign-in request carries that is even loosely tied
+ * to a caller. It is not a strong identity — NAT shares it, and a determined attacker rotates it —
+ * so this bounds trivial abuse rather than defeating a distributed one.
+ */
+export interface UserExternalConnectionSignInThrottleKeyInput {
+    /**
+     * The provider the request targets. Part of the key so one provider's traffic cannot exhaust
+     * another's budget.
+     */
+    readonly providerType: string;
+    /**
+     * The client's IP, when the request carried a resolvable one.
+     */
+    readonly clientIp?: Maybe<string>;
+}
+/**
+ * Rate limits the unauthenticated sign-in endpoints.
+ *
+ * These are the only routes in this module reachable without a credential, and `/signin` fronts
+ * account creation — so an unlimited one is an open provisioning endpoint. An abstract class so it is
+ * its own injection token; optional to provide, but the OAuth service installs
+ * {@link memoryUserExternalConnectionSignInThrottle} when an app registers none, so a sign-in
+ * provider is never entirely unthrottled.
+ */
+export declare abstract class UserExternalConnectionSignInThrottle {
+    /**
+     * Records an attempt and returns whether it should be REJECTED.
+     */
+    abstract readonly throttleSignInAttempt: (input: UserExternalConnectionSignInThrottleKeyInput) => Promise<boolean>;
+}
+/**
+ * Configuration for {@link memoryUserExternalConnectionSignInThrottle}.
+ */
+export interface MemoryUserExternalConnectionSignInThrottleConfig {
+    /**
+     * Minimum time between two accepted attempts from one key. Defaults to 0 (no minimum gap).
+     *
+     * OFF by default deliberately: the burst limit is the real guard, and a minimum gap punishes the
+     * shared-IP case hardest — every caller behind one NAT, and every caller at all in a deployment
+     * that cannot resolve client IPs, shares a single bucket. Set it for a deployment where per-IP
+     * really does mean per-user.
+     */
+    readonly throttleTime?: Maybe<Milliseconds>;
+    /**
+     * How many attempts one key may make within {@link burstWindow} before being throttled.
+     * Defaults to 10.
+     */
+    readonly burstLimit?: Maybe<number>;
+    /**
+     * The window the burst limit applies over. Defaults to one minute.
+     */
+    readonly burstWindow?: Maybe<Milliseconds>;
+}
+/**
+ * Creates an IN-PROCESS {@link UserExternalConnectionSignInThrottle}.
+ *
+ * ## What this is and is not
+ *
+ * State lives in this process's memory, so in a multi-instance deployment each instance enforces the
+ * budget separately and a cold start clears it. That makes it a guard against a single client
+ * hammering one instance, NOT a distributed rate limiter. An app that needs a real one implements
+ * {@link UserExternalConnectionSignInThrottle} against a shared store and provides that instead —
+ * which is why the throttle is an injectable abstraction rather than a hard-coded check.
+ *
+ * @param config - Optional overrides for the rate and the burst window.
+ * @returns The in-memory throttle.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function memoryUserExternalConnectionSignInThrottle(config?: Maybe<MemoryUserExternalConnectionSignInThrottleConfig>): UserExternalConnectionSignInThrottle;
+/**
+ * Size the in-memory throttle map is swept at.
+ *
+ * High enough that a normal caller set never triggers a sweep, low enough that the map cannot grow
+ * without bound under an IP-rotating flood.
+ */
+export declare const MEMORY_THROTTLE_SWEEP_SIZE = 10000;

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

@@ -1,12 +1,28 @@
 import { type Maybe } from '@dereekb/util';
-import { type FirebaseAuthUserId, type FirestoreContextReference, type UserExternalConnectionDocument, type UserExternalConnectionEntryStatus, type UserExternalConnectionErrorCode, type UserExternalConnectionFirestoreCollections, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type FirebaseAuthUserId, type FirestoreContextReference, type Transaction, type UserExternalConnectionDocument, type UserExternalConnectionEntryStatus, type UserExternalConnectionErrorCode, type UserExternalConnectionExternalAccountId, type UserExternalConnectionFirestoreCollections, type UserExternalConnectionLoginIdentity, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type FirebaseServerAuthService } from '@dereekb/firebase-server';
 import { type UserExternalConnectionCredentials, type UserExternalConnectionServerFirestoreCollections } from './userexternalconnection.private';
+import { type UserExternalConnectionProviderPolicyRegistry } from './userexternalconnection.policy';
 /**
  * Context required by {@link userExternalConnectionServerActions}.
  *
  * Carries BOTH halves of the pair. Nothing else in the workspace should hold the private collection.
  */
 export interface UserExternalConnectionServerActionsContext extends FirestoreContextReference, UserExternalConnectionFirestoreCollections, UserExternalConnectionServerFirestoreCollections {
+    /**
+     * The app's per-provider policies. Optional: a missing registry reads as "all defaults", which is
+     * exactly the behavior this module had before policies existed.
+     */
+    readonly userExternalConnectionProviderPolicyRegistry?: Maybe<UserExternalConnectionProviderPolicyRegistry>;
+    /**
+     * The app's auth service, used ONLY by the unlink lockout guard to read whether the user still has a
+     * Firebase-native login method.
+     *
+     * Optional because an app that never enables sign-in writes no login links and so never reaches the
+     * guard. When it is absent and a link IS being removed, the guard reads the account as having no
+     * native provider — the conservative answer, since the alternative is locking someone out.
+     */
+    readonly userExternalConnectionAuthService?: Maybe<FirebaseServerAuthService>;
 }
 /**
  * Reference to a {@link UserExternalConnectionServerActions} instance.
@@ -59,6 +75,30 @@ export interface UserExternalConnectionDisconnectParams {
     readonly retainEntry?: Maybe<boolean>;
     readonly now?: Maybe<Date>;
 }
+/**
+ * Parameters for linking a provider as a LOGIN METHOD for a user.
+ *
+ * NOTE what is absent, as on {@link UserExternalConnectionConnectParams}: there is no parameter for any
+ * field of the stored link. Every one is derived from `identity`, which the server read from a token it
+ * obtained itself.
+ */
+export interface UserExternalConnectionLinkLoginParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The identity the identity-scoped OAuth round trip resolved.
+     */
+    readonly identity: UserExternalConnectionLoginIdentity;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Parameters for removing a provider as a login method for a user.
+ */
+export interface UserExternalConnectionUnlinkLoginParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly now?: Maybe<Date>;
+}
 /**
  * Parameters for creating a user's connection document.
  */
@@ -92,7 +132,34 @@ export declare abstract class UserExternalConnectionServerActions {
     abstract refreshUserExternalConnectionCredentials(params: UserExternalConnectionRefreshCredentialsParams): Promise<UserExternalConnectionDocument>;
     abstract markUserExternalConnectionError(params: UserExternalConnectionMarkErrorParams): Promise<UserExternalConnectionDocument>;
     abstract disconnectUserExternalConnection(params: UserExternalConnectionDisconnectParams): Promise<UserExternalConnectionDocument>;
+    /**
+     * Records that a provider is a LOGIN METHOD for the user.
+     *
+     * Writes `li` and recomputes `c`/`ec`; `e` and the private credentials document are left untouched.
+     * That separation is the point: the identity-scoped grant a link is established with is not the data
+     * grant, so storing its credentials as the data connection would replace a broad grant with a narrow
+     * one.
+     */
+    abstract linkUserExternalConnectionLogin(params: UserExternalConnectionLinkLoginParams): Promise<UserExternalConnectionDocument>;
+    /**
+     * Removes a provider as a login method for the user.
+     *
+     * Strictly larger than a disconnect: it removes the login link, the entry, AND the credentials in one
+     * transaction. Unlinking is the user saying "this is no longer my account", which cannot leave a
+     * live data connection to it behind.
+     */
+    abstract unlinkUserExternalConnectionLogin(params: UserExternalConnectionUnlinkLoginParams): Promise<UserExternalConnectionDocument>;
     abstract deleteAllUserExternalConnectionsForUser(params: UserExternalConnectionDeleteAllParams): Promise<void>;
+    /**
+     * Recomputes every document's derived `ec` array. A one-off job — see
+     * {@link backfillUserExternalConnectionExternalAccountKeysFactory}.
+     */
+    abstract backfillUserExternalConnectionExternalAccountKeys(params?: Maybe<BackfillUserExternalConnectionParams>): Promise<BackfillUserExternalConnectionResult>;
+    /**
+     * Creates a login link for every connected account that predates `li`. A one-off job — see
+     * {@link backfillUserExternalConnectionLoginsFactory}.
+     */
+    abstract backfillUserExternalConnectionLogins(params?: Maybe<BackfillUserExternalConnectionParams>): Promise<BackfillUserExternalConnectionResult>;
 }
 /**
  * The single write a per-user token cache needs: persisting credentials the provider just issued.
@@ -163,6 +230,95 @@ export interface WriteUserExternalConnectionPairParams {
  * @returns A function that applies one provider's outcome to both documents atomically.
  */
 export declare function writeUserExternalConnectionPairInTransactionFactory(context: UserExternalConnectionServerActionsContext): (params: WriteUserExternalConnectionPairParams) => Promise<UserExternalConnectionDocument>;
+/**
+ * Input for the collision check performed inside the paired write's read phase.
+ */
+export interface ResolveUserExternalAccountCollisionInput {
+    readonly transaction: Transaction;
+    /**
+     * The user doing the connecting. A document already held by THIS user is not a collision.
+     */
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly externalAccountId: UserExternalConnectionExternalAccountId;
+    readonly policy: 'block' | 'transfer' | 'allow';
+}
+/**
+ * A prior holder of an external account, and the write that removes their claim to it.
+ *
+ * Returned rather than performed so the caller keeps every read ahead of every write, which a
+ * Firestore transaction requires.
+ *
+ * `release`, not `disconnect`: it removes the prior holder's LOGIN LINK as well as their entry and
+ * credentials. `ec` is the union of both maps, so dropping only the entry would leave their key in
+ * `ec` and break the very uniqueness invariant the transfer exists to maintain — two users would
+ * answer "who is this account?".
+ */
+export interface DisplacedUserExternalConnectionHolder {
+    readonly uid: FirebaseAuthUserId;
+    readonly release: (now: Date) => Promise<void>;
+}
+/**
+ * Creates the uniqueness check the paired write runs when a provider's policy declares its
+ * connections unique.
+ *
+ * ## Known limitation, stated deliberately
+ *
+ * A Firestore transaction adds the documents a query RETURNED to its read set, but it does not lock
+ * the ABSENCE of a match. Two simultaneous first-time connects to the same external account can
+ * therefore both see no holder and both commit. The window is one transaction wide and every other
+ * case (a second connect while a holder exists) is deterministic. Closing it entirely needs a
+ * doc-id-keyed claim record — `<providerType>_<externalAccountId>` → uid, created in the same
+ * transaction, where the id collision is what serializes the writers. That is additive whenever it
+ * is needed.
+ *
+ * @param context - The context carrying the public collection.
+ * @returns A function resolving the collision inside a transaction.
+ */
+export declare function resolveUserExternalAccountCollisionInTransactionFactory(context: UserExternalConnectionServerActionsContext): (input: ResolveUserExternalAccountCollisionInput) => Promise<Maybe<DisplacedUserExternalConnectionHolder>>;
+/**
+ * Creates the function that records a provider as a LOGIN METHOD for a user.
+ *
+ * Writes ONLY the public document's `li` map, then recomputes `c`/`ec` from both maps. The entry map
+ * and the credentials document are untouched, because the identity-scoped grant this link was
+ * established with is not the data grant — persisting it as one would replace a broad grant with a
+ * narrow one.
+ *
+ * Runs the same uniqueness check the paired write runs, for the same reason: after this write the
+ * user's `ec` claims the account, and `unique` means at most one user may.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A function that applies one provider's login link.
+ */
+export declare function linkUserExternalConnectionLoginFactory(context: UserExternalConnectionServerActionsContext): (params: UserExternalConnectionLinkLoginParams) => Promise<UserExternalConnectionDocument>;
+/**
+ * Creates the function that removes a provider as a login method for a user.
+ *
+ * One transaction removing `li[providerType]`, `e[providerType]` and `cr[providerType]`. Strictly more
+ * than a disconnect: an unlink is the user saying the third-party account is not theirs, which cannot
+ * leave a live data connection to it behind.
+ *
+ * ## The lockout guard
+ *
+ * Refuses when removing the link would leave the account with NO remaining login link and NO
+ * Firebase-native provider on the auth record — the state a custom-token-only user is in, and one
+ * nobody can get back out of. Deliberately conservative: an app that provides no auth service to the
+ * actions context reads as "no native provider", because guessing wrong in the other direction
+ * produces an account no support path can recover.
+ *
+ * In practice this should rarely fire. The sign-in service provisions a password credential alongside
+ * the email on every user it creates (`provisionPasswordCredential`, on by default), so those accounts
+ * carry a `password` provider and can always recover through "forgot password". The guard is the
+ * BACKSTOP for the cases that do not: a user created with no email, an app that turned the option off,
+ * accounts created before it existed, and a user who has since removed their password credential.
+ *
+ * The guard is skipped entirely when the provider has no link to remove: nothing is being taken away
+ * as a login method, and the call degenerates to a disconnect.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A function that unlinks one provider.
+ */
+export declare function unlinkUserExternalConnectionLoginFactory(context: UserExternalConnectionServerActionsContext): (params: UserExternalConnectionUnlinkLoginParams) => Promise<UserExternalConnectionDocument>;
 /**
  * Creates a function that deletes a user's entire connection pair in one transaction.
  *
@@ -170,3 +326,60 @@ export declare function writeUserExternalConnectionPairInTransactionFactory(cont
  * @returns A function that removes both documents for a uid.
  */
 export declare function deleteAllUserExternalConnectionsForUserFactory(context: UserExternalConnectionServerActionsContext): (params: UserExternalConnectionDeleteAllParams) => Promise<void>;
+/**
+ * Parameters shared by the one-off backfills.
+ */
+export interface BackfillUserExternalConnectionParams {
+    /**
+     * How many documents to load per checkpoint. Defaults to 100.
+     */
+    readonly limitPerCheckpoint?: Maybe<number>;
+    /**
+     * When true, report what would change without writing anything. Defaults to false.
+     */
+    readonly dryRun?: Maybe<boolean>;
+}
+/**
+ * The outcome of a backfill.
+ */
+export interface BackfillUserExternalConnectionResult {
+    readonly visited: number;
+    readonly updated: number;
+}
+/**
+ * Creates the one-off job that recomputes every document's derived `ec` array.
+ *
+ * Documents written BEFORE `ec` existed have none, and `ec` is what the uniqueness policy and the
+ * sign-in lookup both query. It is now the union of `e` and `li`, so this also repairs a document whose
+ * `ec` predates login links. Until this has run over a collection, a provider marked `unique` sees a
+ * pre-existing connection as no connection at all — it would let a second user claim an account the
+ * first already holds, and a returning user would be treated as a stranger.
+ *
+ * Idempotent, and safe to re-run: `ec` is derived purely from `e`, so a document already carrying the
+ * correct value is skipped rather than rewritten. Expose it through the app's developer-functions map
+ * (`firebaseServerDevFunctions`) rather than any user-reachable route.
+ *
+ * @param context - The context carrying the public collection.
+ * @returns A function performing the backfill.
+ */
+export declare function backfillUserExternalConnectionExternalAccountKeysFactory(context: UserExternalConnectionServerActionsContext): (params?: Maybe<BackfillUserExternalConnectionParams>) => Promise<BackfillUserExternalConnectionResult>;
+/**
+ * Creates the one-off job that gives every pre-existing connection its LOGIN LINK.
+ *
+ * Connections established before `li` existed carry their identity only in the entry's `ea`. They keep
+ * signing in — `ec` is the union, so the entry still resolves the account — but the settings page shows
+ * the provider as NOT linked until the user runs the link flow once, and disconnecting the data
+ * connection would then take the binding with it.
+ *
+ * Only entries whose provider policy declares `signIn: true` are backfilled. A connect-only provider is
+ * not a login method, and inventing a link for one would put a sign-in binding on an account that never
+ * agreed to it. An entry with no `ea` is skipped: there is no identity to record. A provider that
+ * already has a link is left alone, so `lat` is never rewritten.
+ *
+ * Idempotent and safe to re-run. Expose it through the app's developer-functions map
+ * (`firebaseServerDevFunctions`) rather than any user-reachable route.
+ *
+ * @param context - The context carrying the public collection and the provider policies.
+ * @returns A function performing the backfill.
+ */
+export declare function backfillUserExternalConnectionLoginsFactory(context: UserExternalConnectionServerActionsContext): (params?: Maybe<BackfillUserExternalConnectionParams>) => Promise<BackfillUserExternalConnectionResult>;