@dereekb/firebase-server 14.0.1 → 14.2.0

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

@@ -1,8 +1,26 @@
-import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
-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";
+import { type FirebaseAuthUserId, type UserExternalConnectionExternalAccountId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * The UserExternalConnection error codes, re-exported from `@dereekb/firebase`.
+ *
+ * They live in the shared package because the BROWSER branches on them too — a login page deciding
+ * what to say about a refused sign-in cannot import from a server package. Re-exported here so the
+ * codes stay importable beside the factories that throw them.
+ */
+export { USER_EXTERNAL_CONNECTION_PROVIDER_NOT_CONNECTED_ERROR_CODE, USER_EXTERNAL_CONNECTION_PROVIDER_NOT_ALLOWED_ERROR_CODE, USER_EXTERNAL_CONNECTION_ALREADY_EXISTS_ERROR_CODE, USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRED_ERROR_CODE, USER_EXTERNAL_CONNECTION_EXTERNAL_ACCOUNT_IN_USE_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_NOT_ENABLED_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_DENIED_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_EMAIL_CONFLICT_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_USER_MISSING_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_IDENTITY_UNAVAILABLE_ERROR_CODE, USER_EXTERNAL_CONNECTION_LINK_NOT_ENABLED_ERROR_CODE, USER_EXTERNAL_CONNECTION_UNLINK_LAST_LOGIN_METHOD_ERROR_CODE, USER_EXTERNAL_CONNECTION_SIGN_IN_REPORTABLE_ERROR_CODES } from '@dereekb/firebase';
+/**
+ * Reads the reportable error code off a thrown sign-in failure.
+ *
+ * Reads `HttpsError.details.code` — where every helper in `@dereekb/firebase-server` puts it — and
+ * returns it only when it is in `USER_EXTERNAL_CONNECTION_SIGN_IN_REPORTABLE_ERROR_CODES`. Anything
+ * else, including a plain `Error`, yields null.
+ *
+ * @param e - The thrown value.
+ * @returns The reportable code, or null when there is none.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionSignInErrorCode(e: unknown): Maybe<string>;
 /**
  * Creates an error indicating the user already has a connection document.
  *
@@ -42,3 +60,98 @@ export declare function userExternalConnectionCredentialsExpiredError(providerTy
  * @returns A precondition-conflict HttpsError.
  */
 export declare function userExternalConnectionProviderNotAllowedError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating another user already holds the external account being connected.
+ *
+ * Raised only for a provider whose policy declares its connections `unique` with `onCollision: 'block'`.
+ * The holder's uid is deliberately absent from the message and present only in `data`, which is
+ * server-side: telling a caller which account owns a Discord id is an account-enumeration oracle.
+ *
+ * @param providerType - The provider whose account is contested.
+ * @param externalAccountId - The contested external account id.
+ * @param existingUid - The uid that already holds it.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionExternalAccountInUseError(providerType: UserExternalConnectionProviderType, externalAccountId: UserExternalConnectionExternalAccountId, existingUid: FirebaseAuthUserId): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the provider is not configured to be used for signing in.
+ *
+ * Distinct from {@link userExternalConnectionProviderNotAllowedError}: the provider IS allowed, just
+ * not in the sign-in direction. Sign-in is opt-in per provider precisely so an app cannot acquire an
+ * unauthenticated account-creation surface by registering a connect provider.
+ *
+ * @param providerType - The provider a sign-in was attempted with.
+ * @returns A forbidden HttpsError.
+ */
+export declare function userExternalConnectionSignInNotEnabledError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the app's sign-in delegate refused the identity.
+ *
+ * The delegate's `reason` rides in `data` rather than the message: it typically describes why an
+ * account does not qualify (no subscription, not a guild member), which is not something to hand back
+ * to an unauthenticated caller.
+ *
+ * @param providerType - The provider the sign-in was attempted with.
+ * @param reason - The delegate's reason, for the server log.
+ * @returns A forbidden HttpsError.
+ */
+export declare function userExternalConnectionSignInDeniedError(providerType: UserExternalConnectionProviderType, reason: string): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating a new user could not be created because the provider's email already
+ * belongs to a Firebase user.
+ *
+ * Adopting that account would let whoever controls the third-party email take over the Firebase one,
+ * so the sign-in fails instead. The remedy is an explicit link performed by the already-signed-in
+ * user — which is what the connect flow is.
+ *
+ * @param providerType - The provider the sign-in was attempted with.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionSignInEmailConflictError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the uid a sign-in resolved to no longer exists in Firebase Auth.
+ *
+ * Reachable when a user is deleted from Auth without their connection documents being cleaned up:
+ * minting a token for a deleted uid produces a signed-in session with no user record behind it.
+ *
+ * @param providerType - The provider the sign-in was attempted with.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionSignInUserMissingError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the provider returned no stable account id to identify the user by.
+ *
+ * A connect can proceed without one (it only costs the settings row its label), but a sign-in cannot:
+ * with no stable id there is nothing to key the identity on, and falling back to a mutable username
+ * or an email would be the takeover vector this design exists to avoid.
+ *
+ * @param providerType - The provider the sign-in was attempted with.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionSignInIdentityUnavailableError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the provider is not configured to be used as a login method.
+ *
+ * The same `policy.signIn` opt-in that gates the sign-in direction gates this one: linking a provider
+ * as a login method is what MAKES a later sign-in through it resolve to this account, so an app that
+ * has not enabled sign-in must not be able to acquire the binding by another route.
+ *
+ * @param providerType - The provider a link was attempted with.
+ * @returns A forbidden HttpsError.
+ */
+export declare function userExternalConnectionLinkNotEnabledError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the unlink would leave the account with no way to sign back in.
+ *
+ * Deliberately CONSERVATIVE: it refuses whenever the account would be left with no remaining login
+ * link and no Firebase-native provider, which is exactly the state a custom-token-only user is in.
+ * Guessing wrong in the other direction produces an account nobody — including support — can get back
+ * into, so the ambiguous case is refused rather than allowed.
+ *
+ * A rare edge rather than the normal outcome of unlinking: the sign-in service gives every user it
+ * creates with an email a password credential, so "forgot password" is a working way back in.
+ *
+ * @param providerType - The provider the unlink was attempted on.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionUnlinkLastLoginMethodError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;

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

@@ -2,10 +2,11 @@ import { type InjectionToken, type ModuleMetadata, type Provider } from '@nestjs
 import { ConfigService } from '@nestjs/config';
 import { type Maybe, type Milliseconds } from '@dereekb/util';
 import { type FirestoreContext, type FirestoreContextReference, type UserExternalConnectionFirestoreCollections } from '@dereekb/firebase';
-import { FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type FirebaseServerAuthService, FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { type AES256GCMEncryptionSecret } from '@dereekb/nestjs';
 import { type UserExternalConnectionPrivateConverterConfig, UserExternalConnectionServerFirestoreCollections } from './userexternalconnection.private';
 import { type UserExternalConnectionServerActionsContext } from './userexternalconnection.action.server';
+import { type UserExternalConnectionProviderPolicy } from './userexternalconnection.policy';
 /**
  * Environment variable name for the external-connection credentials encryption secret
  * (hex-encoded AES-256 key).
@@ -55,9 +56,11 @@ export declare function userExternalConnectionServerFirestoreCollectionsFactory(
  *
  * @param appCollections - The app's collections, carrying the public UserExternalConnection collection.
  * @param serverCollections - The module-owned private collection.
+ * @param authService - The app's auth service, when sign-in is configured. Only the unlink lockout
+ *   guard reads it; an app with no sign-in writes no login links and never reaches the guard.
  * @returns The assembled server actions context.
  */
-export declare function userExternalConnectionServerActionsContextFactory(appCollections: UserExternalConnectionFirestoreCollections & FirestoreContextReference, serverCollections: UserExternalConnectionServerFirestoreCollections): UserExternalConnectionServerActionsContext;
+export declare function userExternalConnectionServerActionsContextFactory(appCollections: UserExternalConnectionFirestoreCollections & FirestoreContextReference, serverCollections: UserExternalConnectionServerFirestoreCollections, authService?: Maybe<FirebaseServerAuthService>): UserExternalConnectionServerActionsContext;
 /**
  * NestJS injection token for the assembled {@link UserExternalConnectionServerActionsContext}.
  */
@@ -75,6 +78,53 @@ export interface ProvideAppUserExternalConnectionModuleMetadataConfig extends Pi
      * Taking this as a token is what keeps the package from ever naming an app's collections class.
      */
     readonly appCollectionsToken: InjectionToken;
+    /**
+     * Per-provider rules the connect and sign-in paths enforce.
+     *
+     * Omitted means every provider takes {@link DEFAULT_USER_EXTERNAL_CONNECTION_PROVIDER_POLICY} —
+     * shared accounts permitted, connect-only — which is exactly how this module behaved before
+     * policies existed.
+     */
+    readonly providerPolicies?: Maybe<readonly UserExternalConnectionProviderPolicy[]>;
+    /**
+     * Configuration for the sign-in half of the module.
+     *
+     * Omitted means no {@link UserExternalConnectionSignInService} is provided at all, and every
+     * provider's sign-in routes refuse. That is the correct shape for an app that only CONNECTS
+     * providers: enabling sign-in creates an unauthenticated account-creation surface, and it should
+     * take a deliberate declaration to acquire one.
+     */
+    readonly signIn?: Maybe<ProvideAppUserExternalConnectionSignInConfig>;
+}
+/**
+ * Configuration for the sign-in half of the UserExternalConnection module.
+ */
+export interface ProvideAppUserExternalConnectionSignInConfig {
+    /**
+     * Token resolving the app's `FirebaseServerAuthService`.
+     *
+     * Taken as a token because the auth service is the app's own subclass — this package must never
+     * name it.
+     */
+    readonly authServiceToken: InjectionToken;
+    /**
+     * Token resolving the app's {@link UserExternalConnectionSignInDelegate}.
+     *
+     * Omitted means {@link denyNewUserSignInDelegate}: a returning user signs in, a stranger is
+     * refused. Provisioning strangers is an explicit opt-in.
+     */
+    readonly delegateToken?: Maybe<InjectionToken>;
+    /**
+     * Whether a created user may ADOPT an existing Firebase account whose email matches the provider's
+     * VERIFIED email. Defaults to false — see the field docs on the service config.
+     */
+    readonly allowVerifiedEmailLinking?: Maybe<boolean>;
+    /**
+     * Whether a created user is also given a password credential, so the account keeps a
+     * Firebase-native recovery path after the third-party provider is unlinked. Defaults to TRUE — see the
+     * field docs on the service config.
+     */
+    readonly provisionPasswordCredential?: Maybe<boolean>;
 }
 /**
  * Convenience function used to generate ModuleMetadata for an app's UserExternalConnectionModule.

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

@@ -0,0 +1,117 @@
+import { type Maybe } from '@dereekb/util';
+import { type UserExternalConnectionProviderType } from '@dereekb/firebase';
+/**
+ * What happens when the external account being connected is already held by a different user.
+ *
+ * - `block` — refuse the connect. The default, and the only one that is safe without thought.
+ * - `transfer` — disconnect the prior holder in the same transaction and connect the new one. Right
+ *   when the third-party account is the identity of record and a person may have created a stray
+ *   Firebase user by another route.
+ * - `allow` — permit both. Correct only for a provider whose accounts are legitimately shared
+ *   (a team's shared Zoom account, say), and incompatible with using that provider to sign in.
+ */
+export type UserExternalConnectionCollisionPolicy = 'block' | 'transfer' | 'allow';
+/**
+ * Per-provider rules the connect and sign-in paths enforce.
+ *
+ * Declared by the app rather than by the provider adapter: whether two users may share a Discord
+ * account, and whether Discord may be used to log in at all, are product decisions, not facts about
+ * Discord's API.
+ */
+export interface UserExternalConnectionProviderPolicy {
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * At most one Firebase user per external account. Defaults to false.
+     *
+     * A provider used for SIGN-IN should almost always be unique — otherwise "who is this account?" has
+     * more than one answer and the sign-in resolves arbitrarily.
+     *
+     * Do not turn this on for a provider with existing connections until the `ec` backfill has run:
+     * uniqueness is enforced against `ec`, and a document written before that field existed has none.
+     */
+    readonly unique?: Maybe<boolean>;
+    /**
+     * The provider may be used to sign in. Defaults to FALSE.
+     *
+     * Opt-in because enabling it turns `/oauth/<provider>/signin` into an unauthenticated
+     * account-creation surface; registering a provider for the connect direction must not silently
+     * grant that.
+     */
+    readonly signIn?: Maybe<boolean>;
+    /**
+     * A SIGN-IN through this provider also establishes the DATA connection, storing the credentials the
+     * sign-in exchange produced. Defaults to FALSE.
+     *
+     * Off by default because the two grants are not the same grant. A sign-in requests the identity
+     * scopes (`identify`, `email`); a data connection requests whatever the integration actually reads.
+     * Writing the sign-in's credentials into the data connection therefore REPLACES a broad grant with a
+     * narrow one every time the user signs in — silently downgrading a working integration.
+     *
+     * Turn it on only for an app whose sign-in scopes are a superset of its data scopes, or one that has
+     * no data integration and just wants the connection row to show up.
+     */
+    readonly signInConnects?: Maybe<boolean>;
+    /**
+     * What to do when `unique` is set and another user already holds the account. Defaults to `block`.
+     */
+    readonly onCollision?: Maybe<UserExternalConnectionCollisionPolicy>;
+}
+/**
+ * The policy applied to a provider the app declared nothing for.
+ *
+ * Every field is the restrictive option: an unlisted provider behaves exactly as it did before
+ * policies existed (shared accounts permitted, connect-only), so adding the registry changes no
+ * existing app's behavior.
+ */
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_PROVIDER_POLICY: Omit<Required<UserExternalConnectionProviderPolicy>, 'providerType'>;
+/**
+ * Resolves the {@link UserExternalConnectionProviderPolicy} for a provider.
+ *
+ * An abstract class so it is its own injection token. Optional to provide — a missing registry reads
+ * as "every provider takes the default policy".
+ */
+export declare abstract class UserExternalConnectionProviderPolicyRegistry {
+    abstract readonly policyForProviderType: (providerType: UserExternalConnectionProviderType) => UserExternalConnectionResolvedProviderPolicy;
+}
+/**
+ * A policy with every optional field resolved, so enforcement sites never re-apply defaults.
+ */
+export interface UserExternalConnectionResolvedProviderPolicy {
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly unique: boolean;
+    readonly signIn: boolean;
+    readonly signInConnects: boolean;
+    readonly onCollision: UserExternalConnectionCollisionPolicy;
+}
+/**
+ * Resolves a declared policy against {@link DEFAULT_USER_EXTERNAL_CONNECTION_PROVIDER_POLICY}.
+ *
+ * @param providerType - The provider being resolved.
+ * @param policy - The app's declaration for it, when there is one.
+ * @returns The policy with every field populated.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveUserExternalConnectionProviderPolicy(providerType: UserExternalConnectionProviderType, policy?: Maybe<UserExternalConnectionProviderPolicy>): UserExternalConnectionResolvedProviderPolicy;
+/**
+ * Creates a {@link UserExternalConnectionProviderPolicyRegistry} from the app's declarations.
+ *
+ * @param policies - The per-provider policies the app declares. Providers absent from the list take
+ *   the default policy.
+ * @returns The registry.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionProviderPolicyRegistry(policies?: Maybe<readonly UserExternalConnectionProviderPolicy[]>): UserExternalConnectionProviderPolicyRegistry;
+/**
+ * Resolves a provider's policy, treating a missing registry as "all defaults".
+ *
+ * The registry is optional, so every enforcement site would otherwise repeat this fallback.
+ *
+ * @param registry - The registry, when the app provided one.
+ * @param providerType - The provider to resolve.
+ * @returns The resolved policy.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionPolicyForProviderType(registry: Maybe<UserExternalConnectionProviderPolicyRegistry>, providerType: UserExternalConnectionProviderType): UserExternalConnectionResolvedProviderPolicy;

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

@@ -0,0 +1,286 @@
+import { type EmailAddress, type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId, type UserExternalConnectionExternalAccountId, type UserExternalConnectionFirestoreCollections, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type FirebaseServerAuthService } from '@dereekb/firebase-server';
+/**
+ * What a provider reported about the account a sign-in is being attempted with.
+ *
+ * Every field is read SERVER-SIDE from a token the server itself obtained. Nothing here may come
+ * from the client: an `id_token` handed over by a browser is unverified (nothing in this workspace
+ * is a JWKS verifier), and accepting one would let a caller assert any identity it liked.
+ */
+export interface UserExternalConnectionSignInIdentity {
+    /**
+     * The provider's STABLE id for the account — a Discord snowflake, not a username.
+     *
+     * Identity is keyed on this and nothing else. Usernames are mutable on most providers (Discord
+     * made them so in 2023), so keying on one would hand an account over to whoever claimed the name
+     * next.
+     */
+    readonly externalAccountId: UserExternalConnectionExternalAccountId;
+    /**
+     * The account's email, when the provider reported one.
+     */
+    readonly email?: Maybe<EmailAddress>;
+    /**
+     * Whether the PROVIDER considers that email verified.
+     *
+     * Load-bearing: an unverified third-party email matching an existing Firebase user is an
+     * account-takeover vector, so linking on email is refused unless this is true AND the app opted in.
+     */
+    readonly emailVerified?: Maybe<boolean>;
+    /**
+     * Human-readable label for the account, e.g. a display name.
+     */
+    readonly label?: Maybe<string>;
+}
+/**
+ * Input handed to a {@link UserExternalConnectionSignInDelegate}.
+ */
+export interface UserExternalConnectionSignInInput {
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly identity: UserExternalConnectionSignInIdentity;
+    /**
+     * The uid already holding this external account, when one does.
+     *
+     * Set means "a returning user"; absent means "nobody in this project has ever signed in as this
+     * third-party account", which is the decision the delegate exists to make.
+     */
+    readonly existingUid?: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * What the app decided to do about a sign-in attempt.
+ */
+export type UserExternalConnectionSignInResolution = UserExternalConnectionSignInResolutionSignIn | UserExternalConnectionSignInResolutionCreateUser | UserExternalConnectionSignInResolutionDeny;
+export interface UserExternalConnectionSignInResolutionSignIn {
+    readonly action: 'signIn';
+    readonly uid: FirebaseAuthUserId;
+}
+export interface UserExternalConnectionSignInResolutionCreateUser {
+    readonly action: 'createUser';
+    readonly email?: Maybe<EmailAddress>;
+    readonly displayName?: Maybe<string>;
+    /**
+     * Claims to set on the newly created user, before the custom token is minted.
+     */
+    readonly claims?: Maybe<object>;
+}
+export interface UserExternalConnectionSignInResolutionDeny {
+    readonly action: 'deny';
+    /**
+     * Why the sign-in was refused. Logged server-side; never returned to the browser, since it may
+     * describe why an account does not qualify.
+     */
+    readonly reason: string;
+}
+/**
+ * Decides whether a third-party identity may sign in, and as whom.
+ *
+ * This is the app's policy hook and the ONLY place that decision is made. It is an abstract class so
+ * it is its own injection token, matching the other members of this module.
+ *
+ * The library default is {@link denyNewUserSignInDelegate} — a returning user signs in, a stranger is
+ * refused. Provisioning strangers is an explicit opt-in, because a sign-in endpoint that creates
+ * users is an unauthenticated account-creation surface.
+ */
+export declare abstract class UserExternalConnectionSignInDelegate {
+    abstract readonly resolveSignIn: (input: UserExternalConnectionSignInInput) => Promise<UserExternalConnectionSignInResolution>;
+}
+/**
+ * The DEFAULT sign-in delegate: an existing user signs in, an unrecognized one is refused.
+ *
+ * Deny-by-default because the alternative — creating a Firebase user for anyone who can complete a
+ * consent screen at a third party — is a decision an app has to make deliberately. Pair with
+ * {@link autoCreateUserSignInDelegate} when open registration IS the intent.
+ *
+ * @returns A delegate that never provisions a new user.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function denyNewUserSignInDelegate(): UserExternalConnectionSignInDelegate;
+/**
+ * How much of an email the provider must report before a new Firebase user may be provisioned.
+ *
+ * - `verified` — the provider must report an email AND consider it verified.
+ * - `any` — the provider must report an email; whether it is verified is not checked.
+ * - `none` — no email is required, and an emailless user may be created.
+ */
+export type UserExternalConnectionSignInEmailRequirement = 'verified' | 'any' | 'none';
+/**
+ * The default {@link UserExternalConnectionSignInEmailRequirement}.
+ */
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_SIGN_IN_EMAIL_REQUIREMENT: UserExternalConnectionSignInEmailRequirement;
+/**
+ * Configuration for {@link autoCreateUserSignInDelegate}.
+ */
+export interface AutoCreateUserSignInDelegateConfig {
+    /**
+     * Whether to carry the provider's email onto the created Firebase user.
+     *
+     * Defaults to true, and applies ONLY to the created user's own record — it does not permit
+     * adopting an existing account that already holds the email. That is
+     * {@link UserExternalConnectionSignInServiceConfig.allowVerifiedEmailLinking}.
+     *
+     * NOTE that setting this false while {@link requireEmailToCreateUser} is anything other than
+     * `'none'` still GATES on the provider's email but omits it from the created record — which also
+     * suppresses the service's own `getUserByEmail` collision check, since that check reads the email
+     * this delegate returns.
+     */
+    readonly useProviderEmail?: Maybe<boolean>;
+    /**
+     * What the provider must report about the account's email before a user is created.
+     *
+     * Defaults to {@link DEFAULT_USER_EXTERNAL_CONNECTION_SIGN_IN_EMAIL_REQUIREMENT} (`'verified'`).
+     * Provisioning an account off an UNVERIFIED third-party email is the takeover vector the service's
+     * own docs warn about, and it is the one case the service-side collision check cannot cover: an
+     * absent email skips the check entirely, and Discord's default scopes report none at all.
+     */
+    readonly requireEmailToCreateUser?: Maybe<UserExternalConnectionSignInEmailRequirement>;
+}
+/**
+ * Returns why an identity's email does not meet a requirement, or null when it does.
+ *
+ * @param requirement - The requirement to check against.
+ * @param identity - The identity the provider reported.
+ * @returns The refusal reason, or null when the requirement is met.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionSignInEmailRequirementDenyReason(requirement: UserExternalConnectionSignInEmailRequirement, identity: UserExternalConnectionSignInIdentity): Maybe<string>;
+/**
+ * An OPT-IN sign-in delegate that provisions a new user for an unrecognized third-party account.
+ *
+ * Open registration. Use it when anyone able to authenticate at the provider is meant to get an
+ * account; use a bespoke delegate when they are not (checking a subscription, a guild membership, or
+ * an invite list before returning `createUser`).
+ *
+ * By default a new user is created ONLY for an identity carrying a provider-VERIFIED email — see
+ * {@link AutoCreateUserSignInDelegateConfig.requireEmailToCreateUser}.
+ *
+ * @param config - Optional configuration.
+ * @returns A delegate that creates a user on a miss.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function autoCreateUserSignInDelegate(config?: Maybe<AutoCreateUserSignInDelegateConfig>): UserExternalConnectionSignInDelegate;
+/**
+ * Input for {@link UserExternalConnectionSignInService.resolveSignIn}.
+ */
+export interface ResolveUserExternalConnectionSignInInput {
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly identity: UserExternalConnectionSignInIdentity;
+}
+/**
+ * The uid a sign-in resolved to.
+ */
+export interface UserExternalConnectionSignInResult {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * Whether a new Firebase user was provisioned for this sign-in.
+     */
+    readonly created: boolean;
+}
+/**
+ * Resolves a third-party identity to a Firebase uid and mints the custom token that signs them in.
+ *
+ * Split out of the OAuth service so the identity → uid decision, which is app policy, is not tangled
+ * with any one provider's OAuth mechanics — and so a provider adapter needs no knowledge of Firebase
+ * Auth at all.
+ *
+ * Optional to provide: an app that only ever CONNECTS providers never registers one, and its OAuth
+ * services then reject sign-in requests outright.
+ */
+export declare abstract class UserExternalConnectionSignInService {
+    /**
+     * Resolves the uid a third-party identity signs in as, provisioning one if the app's delegate says
+     * to.
+     */
+    abstract readonly resolveSignIn: (input: ResolveUserExternalConnectionSignInInput) => Promise<UserExternalConnectionSignInResult>;
+    /**
+     * Mints the Firebase custom token the client exchanges via `signInWithCustomToken`.
+     */
+    abstract readonly mintCustomTokenForUser: (input: UserExternalConnectionMintCustomTokenInput) => Promise<string>;
+}
+export interface UserExternalConnectionMintCustomTokenInput {
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * Configuration for {@link userExternalConnectionSignInService}.
+ */
+export interface UserExternalConnectionSignInServiceConfig extends UserExternalConnectionFirestoreCollections {
+    readonly authService: FirebaseServerAuthService;
+    /**
+     * The app's policy hook. Defaults to {@link denyNewUserSignInDelegate}.
+     */
+    readonly delegate?: Maybe<UserExternalConnectionSignInDelegate>;
+    /**
+     * Whether a `createUser` resolution may ADOPT an existing Firebase user whose email matches the
+     * provider's — and only when the provider reported that email VERIFIED.
+     *
+     * Defaults to false. Even with a verified email this is a policy choice rather than an obviously
+     * safe one: it means whoever controls the third-party account controls the Firebase account. The
+     * safe alternative is an explicit link step performed by an already-signed-in user, which is what
+     * the connect flow already is.
+     */
+    readonly allowVerifiedEmailLinking?: Maybe<boolean>;
+    /**
+     * Whether a newly created user is also given a PASSWORD credential, so the account has a
+     * Firebase-native way back in that does not depend on the third-party provider.
+     *
+     * Defaults to TRUE, and only applies when the user is created with an email — a password credential
+     * on an emailless user is unreachable, since there is no address to sign in with or reset against.
+     *
+     * The password is high-entropy, generated per user, and DISCARDED — nobody, including this server,
+     * ever learns it. It is not a credential the user is expected to use directly: it exists so
+     * "forgot password" against their own verified email is a working recovery path. That is what makes
+     * removing the third-party provider a safe operation rather than a lockout, which is why
+     * {@link userExternalConnectionUnlinkLastLoginMethodError} is a rare edge rather than the normal
+     * outcome of unlinking.
+     *
+     * Turn it off for an app that wants federated-only accounts and accepts that unlinking the last
+     * provider will be refused.
+     */
+    readonly provisionPasswordCredential?: Maybe<boolean>;
+}
+/**
+ * How many random bytes back a provisioned password credential.
+ *
+ * 48 bytes is 384 bits. Deliberately NOT the six-digit `generateRandomSetupPassword()` the new-user
+ * service uses: that is an INVITATION password, delivered to the user and meant to be typed once. This
+ * one is never delivered to anyone, so its only job is to be unguessable — and a six-digit password
+ * sitting on an account nobody is watching would be a genuine takeover vector.
+ */
+export declare const USER_EXTERNAL_CONNECTION_PROVISIONED_PASSWORD_BYTES = 48;
+/**
+ * Generates the password credential a newly created federated user is provisioned with.
+ *
+ * The value is returned to exactly one caller, handed straight to `auth.createUser()`, and never
+ * stored, logged, or returned to the client. Recovery goes through the user's own verified email.
+ *
+ * @returns A high-entropy password.
+ */
+export declare function generateUserExternalConnectionProvisionedPassword(): string;
+/**
+ * Creates the {@link UserExternalConnectionSignInService}.
+ *
+ * User creation deliberately does NOT go through `AbstractFirebaseServerNewUserService.initializeNewUser()`:
+ * that assigns a random six-digit password and writes a setup-password claim, which are INVITATION
+ * semantics — the password is delivered to the user and the account is expected to complete a setup
+ * step. A federated sign-in has neither, so `auth.createUser()` is called directly.
+ *
+ * It DOES provision a password credential of its own (see `provisionPasswordCredential`), but for the
+ * opposite reason: that one is never delivered to anyone. It exists so the account has a
+ * Firebase-native recovery path via the user's own verified email, which is what makes unlinking the
+ * third-party provider a safe operation instead of a lockout.
+ *
+ * @param config - The auth service, the public collection, and the app's delegate.
+ * @returns The sign-in service.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionSignInService(config: UserExternalConnectionSignInServiceConfig): UserExternalConnectionSignInService;
+/**
+ * Reference to a {@link UserExternalConnectionSignInService} instance.
+ */
+export interface UserExternalConnectionSignInServiceRef {
+    readonly userExternalConnectionSignInService: UserExternalConnectionSignInService;
+}

package/oidc/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "14.0.1",
+  "version": "14.2.0",
+  "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.0.1",
-    "@dereekb/date": "14.0.1",
-    "@dereekb/firebase": "14.0.1",
-    "@dereekb/firebase-server": "14.0.1",
-    "@dereekb/model": "14.0.1",
-    "@dereekb/nestjs": "14.0.1",
-    "@dereekb/rxjs": "14.0.1",
-    "@dereekb/util": "14.0.1",
-    "@dereekb/zoho": "14.0.1",
+    "@dereekb/analytics": "14.2.0",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/firebase-server": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/nestjs": "14.2.0",
+    "@dereekb/rxjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
+    "@dereekb/zoho": "14.2.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",