@dereekb/firebase-server 14.0.1 → 14.1.0

package/model/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "14.0.1",
+  "version": "14.1.0",
   "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/analytics": "14.1.0",
+    "@dereekb/date": "14.1.0",
+    "@dereekb/firebase": "14.1.0",
+    "@dereekb/firebase-server": "14.1.0",
+    "@dereekb/model": "14.1.0",
+    "@dereekb/nestjs": "14.1.0",
+    "@dereekb/rxjs": "14.1.0",
+    "@dereekb/util": "14.1.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "archiver": "^8.0.0",

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

@@ -4,5 +4,7 @@ export * from './userexternalconnection.accessor.service';
 export * from './userexternalconnection.action.server';
 export * from './userexternalconnection.error';
 export * from './userexternalconnection.module';
+export * from './userexternalconnection.policy';
+export * from './userexternalconnection.signin';
 export * from './userexternalconnection.reader.service';
 export * from './userexternalconnection.refresh.service';

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

@@ -5,3 +5,4 @@ export * from './userexternalconnection.oauth.refresh';
 export * from './userexternalconnection.oauth.registry';
 export * from './userexternalconnection.oauth.service';
 export * from './userexternalconnection.oauth.state';
+export * from './userexternalconnection.oauth.throttle';

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

@@ -68,7 +68,46 @@ export interface UserExternalConnectionOAuthApiConfig {
      * Where the user is sent after a connection fails. Defaults to the `successUrl`.
      */
     readonly failureUrl?: Maybe<WebsiteUrl>;
+    /**
+     * Where the user is sent after a successful SIGN-IN, with the ticket appended. Defaults to the
+     * `successUrl`.
+     *
+     * Usually different from `successUrl`: a connect returns to a settings page, a sign-in returns to
+     * wherever a freshly signed-in user belongs.
+     */
+    readonly signInSuccessUrl?: Maybe<WebsiteUrl>;
+    /**
+     * Where the user is sent after a FAILED sign-in, with the reason code appended. Defaults to the
+     * `failureUrl`.
+     *
+     * Usually different from `failureUrl`: a failed connect returns to the auth-gated settings page the
+     * connect was started from, while a failed sign-in has no signed-in user to show that page to — it
+     * belongs back on the login page, where the refusal can be explained and retried.
+     */
+    readonly signInFailureUrl?: Maybe<WebsiteUrl>;
+    /**
+     * App paths a sign-in request may ask to return to.
+     *
+     * An UNVALIDATED return path is an open redirect, so a path absent from this list is dropped and
+     * the sign-in returns to {@link signInSuccessUrl} instead. Absent or empty means no request-supplied
+     * return path is honored at all, which is the safe default.
+     */
+    readonly allowedReturnPaths?: Maybe<readonly string[]>;
 }
+/**
+ * Returns whether a request-supplied return path may be honored.
+ *
+ * An exact match against the app's declared list — deliberately not a prefix or pattern match, since
+ * every "starts with /app" style check ever written has eventually been defeated by a path that also
+ * starts with it (`/app.evil.com`, `//evil.com/app`).
+ *
+ * @param config - The provider's OAuth config carrying the allowlist.
+ * @param returnPath - The path the request asked to return to.
+ * @returns True when the path is on the allowlist.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isAllowedUserExternalConnectionReturnPath(config: UserExternalConnectionOAuthApiConfig, returnPath: Maybe<string>): boolean;
 /**
  * Configuration for an {@link AbstractUserExternalConnectionOAuthService}.
  *
@@ -94,6 +133,18 @@ export interface UserExternalConnectionOAuthServiceConfigFactoryConfig {
      * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
      */
     readonly failurePath?: Maybe<string>;
+    /**
+     * Path on the app URL a successful SIGN-IN returns to. Defaults to `successPath`.
+     */
+    readonly signInSuccessPath?: Maybe<string>;
+    /**
+     * Path on the app URL a FAILED sign-in returns to, e.g. `/auth/login`. Defaults to `failurePath`.
+     */
+    readonly signInFailurePath?: Maybe<string>;
+    /**
+     * App paths a sign-in request may ask to return to instead of {@link signInSuccessPath}.
+     */
+    readonly allowedReturnPaths?: Maybe<readonly string[]>;
 }
 /**
  * Builds a provider's OAuth configuration from the app's configured origins plus code-declared

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

@@ -20,6 +20,32 @@ export interface UserExternalConnectionOAuthCallbackQuery extends UserExternalCo
     readonly error?: Maybe<string>;
     readonly error_description?: Maybe<string>;
 }
+/**
+ * Body of a sign-in ticket exchange.
+ */
+export interface UserExternalConnectionOAuthTicketExchangeBody {
+    readonly ticket?: Maybe<string>;
+    /**
+     * The PKCE code verifier the browser retained in session storage.
+     */
+    readonly verifier?: Maybe<string>;
+}
+/**
+ * Response of a successful sign-in ticket exchange.
+ */
+export interface UserExternalConnectionOAuthTicketExchangeResponse {
+    /**
+     * The Firebase custom token to pass to `signInWithCustomToken`.
+     */
+    readonly customToken: string;
+}
+/**
+ * HTTP status returned when a sign-in ticket cannot be redeemed.
+ *
+ * A single status for every failure — expired, tampered with, wrong verifier, throttled — so the
+ * endpoint is not an oracle telling an attacker which part of a forged ticket was wrong.
+ */
+export declare const USER_EXTERNAL_CONNECTION_OAUTH_TICKET_REJECTED_STATUS = 401;
 /**
  * The two endpoints of an external-connection authorization-code handoff.
  *
@@ -65,4 +91,27 @@ export declare abstract class AbstractUserExternalConnectionOAuthController {
      * @param response - The response to issue the redirect on.
      */
     callback(query: UserExternalConnectionOAuthCallbackQuery, response: Response): Promise<void>;
+    /**
+     * Begins a SIGN-IN handoff for an anonymous visitor.
+     *
+     * Unauthenticated by necessity: a user who is signing in has no credential to present yet. The
+     * state is minted here rather than by a prior authenticated call, bound to the `challenge` the
+     * browser supplies, and the whole route is refused unless the app's policy enabled sign-in for this
+     * provider.
+     *
+     * @param request - The incoming sign-in request, carrying `challenge` and an optional `returnPath`.
+     * @param response - The response to issue the redirect on.
+     */
+    signIn(request: Request, response: Response): Promise<void>;
+    /**
+     * Redeems a sign-in ticket for the Firebase custom token it carries.
+     *
+     * Unauthenticated for the same reason as `signin`, and safe for the same reason the ticket is: it
+     * can only be redeemed by whoever holds the PKCE verifier the flow started with.
+     *
+     * @param body - The ticket from the redirect and the verifier the browser retained.
+     * @param request - The incoming request, read for the client IP the throttle keys on.
+     * @param response - The response to write the token or the rejection to.
+     */
+    token(body: UserExternalConnectionOAuthTicketExchangeBody, request: Request, response: Response): Promise<void>;
 }

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

@@ -1,3 +1,5 @@
+import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type UserExternalConnectionCredentials } from '../userexternalconnection.private';
 import { type UserExternalConnectionCredentialsRefresher } from '../userexternalconnection.refresh.service';
 import { type UserExternalConnectionOAuthProviderRegistry } from './userexternalconnection.oauth.registry';
 /**
@@ -22,3 +24,36 @@ export interface UserExternalConnectionOAuthRegistryCredentialsRefresherConfig {
  * @__NO_SIDE_EFFECTS__
  */
 export declare function userExternalConnectionOAuthRegistryCredentialsRefresher(config: UserExternalConnectionOAuthRegistryCredentialsRefresherConfig): UserExternalConnectionCredentialsRefresher;
+/**
+ * Input for a {@link UserExternalConnectionCredentialsRevoker}.
+ */
+export interface UserExternalConnectionRevokeCredentialsInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly credentials: UserExternalConnectionCredentials;
+}
+/**
+ * Ends a provider's grant before the credentials are forgotten.
+ */
+export declare abstract class UserExternalConnectionCredentialsRevoker {
+    abstract readonly revokeUserExternalConnectionCredentials: (input: UserExternalConnectionRevokeCredentialsInput) => Promise<void>;
+}
+/**
+ * Creates a {@link UserExternalConnectionCredentialsRevoker} that revokes through the app's
+ * registered OAuth provider services.
+ *
+ * The disconnect counterpart of {@link userExternalConnectionOAuthRegistryCredentialsRefresher}, and
+ * declared beside it for the same reason: the paired write knows the credentials are being discarded
+ * but nothing about providers, while a provider service knows how to revoke but nothing about who is
+ * asking.
+ *
+ * Call this BEFORE `disconnectUserExternalConnection`, which is the last moment the credentials
+ * still exist. A provider the app never registered — or one with no revocation endpoint — resolves to
+ * a no-op, which matches the pre-existing behavior of simply deleting the stored credentials.
+ *
+ * @param config - The provider registry to dispatch through.
+ * @returns A revoker backed by the registry.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRegistryCredentialsRevoker(config: UserExternalConnectionOAuthRegistryCredentialsRefresherConfig): UserExternalConnectionCredentialsRevoker;

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

@@ -5,8 +5,11 @@ import { type Maybe, type WebsiteUrl } from '@dereekb/util';
 import { type UserExternalConnectionCredentials } from '../userexternalconnection.private';
 import { type UserExternalConnectionAccessor } from '../userexternalconnection.accessor.service';
 import { type UserExternalConnectionServerActions } from '../userexternalconnection.action.server';
-import { type UserExternalConnectionStateCoder } from './userexternalconnection.oauth.state';
+import { type UserExternalConnectionSignInIdentity, type UserExternalConnectionSignInService } from '../userexternalconnection.signin';
+import { type UserExternalConnectionProviderPolicyRegistry } from '../userexternalconnection.policy';
+import { type UserExternalConnectionLinkStateActor, type UserExternalConnectionSignInStateActor, type UserExternalConnectionStateActor, type UserExternalConnectionStateCoder, type UserExternalConnectionStateMode } from './userexternalconnection.oauth.state';
 import { type UserExternalConnectionOAuthServiceConfig } from './userexternalconnection.oauth.config';
+import { type UserExternalConnectionSignInThrottle } from './userexternalconnection.oauth.throttle';
 /**
  * The `state` value carried through the authorization-code handoff.
  *
@@ -14,11 +17,12 @@ import { type UserExternalConnectionOAuthServiceConfig } from './userexternalcon
  */
 export type UserExternalConnectionOAuthState = string;
 /**
- * Identifies who a handoff belongs to, as resolved from a verified `state`.
+ * Identifies who (or what) a handoff belongs to, as resolved from a verified `state`.
+ *
+ * An alias of the state coder's own union rather than a second shape: the two would otherwise drift
+ * the moment a mode carried a new field.
  */
-export interface UserExternalConnectionOAuthActor {
-    readonly uid: FirebaseAuthUserId;
-}
+export type UserExternalConnectionOAuthActor = UserExternalConnectionStateActor;
 /**
  * The raw callback query, as the provider sent it.
  *
@@ -49,6 +53,14 @@ export interface UserExternalConnectionOAuthExchangeInput {
      * a request target without checking it against an allowlist first.
      */
     readonly query?: Maybe<UserExternalConnectionOAuthCallbackQueryValues>;
+    /**
+     * The PKCE code verifier whose challenge the authorize request carried, when it carried one.
+     *
+     * Present only for a sign-in, whose state is minted by this server and can therefore hold the
+     * verifier. A connect state is minted by the authenticated `read:authorizeState` call, which sends
+     * no challenge, so its exchange sends no verifier either.
+     */
+    readonly codeVerifier?: Maybe<string>;
 }
 export interface UserExternalConnectionOAuthHandleCallbackInput {
     /**
@@ -96,6 +108,16 @@ export interface UserExternalConnectionOAuthRefreshCredentialsInput {
      */
     readonly credentials: UserExternalConnectionCredentials;
 }
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.revokeCredentials}.
+ */
+export interface UserExternalConnectionOAuthRevokeCredentialsInput {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The credentials being discarded.
+     */
+    readonly credentials: UserExternalConnectionCredentials;
+}
 export interface UserExternalConnectionOAuthCallbackResult {
     readonly success: boolean;
     /**
@@ -103,6 +125,133 @@ export interface UserExternalConnectionOAuthCallbackResult {
      */
     readonly redirectUrl: WebsiteUrl;
 }
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.authorizeUrlForState}.
+ */
+export interface UserExternalConnectionOAuthAuthorizeUrlInput {
+    readonly state: UserExternalConnectionOAuthState;
+    /**
+     * The PKCE code challenge to send to the provider, when the flow has one.
+     *
+     * Set for a sign-in, absent for a connect — see {@link UserExternalConnectionOAuthExchangeInput.codeVerifier}.
+     */
+    readonly codeChallenge?: Maybe<string>;
+    /**
+     * Which direction the handoff runs in. Defaults to `connect`.
+     *
+     * This is how an adapter picks its SCOPE SET: the state is an opaque, encrypted envelope the adapter
+     * cannot read, so it cannot work the mode out for itself. `signin` and `link` both want the identity
+     * scopes; `connect` wants the data scopes, which are usually neither a superset nor a subset.
+     */
+    readonly mode?: Maybe<UserExternalConnectionStateMode>;
+}
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.signInIdentityForCredentials}.
+ */
+export interface UserExternalConnectionOAuthSignInIdentityInput {
+    readonly credentials: UserExternalConnectionCredentials;
+}
+/**
+ * The values a `/signin` request carries.
+ */
+export interface UserExternalConnectionOAuthSignInRequestValues {
+    /**
+     * The browser's PKCE challenge, which the eventual ticket is bound to.
+     */
+    readonly challenge?: Maybe<string>;
+    /**
+     * Where in the app to return to. Validated against the config's allowlist before it is minted into
+     * the state — an unvalidated one is an open redirect.
+     */
+    readonly returnPath?: Maybe<string>;
+    /**
+     * The caller's IP, for the throttle.
+     */
+    readonly clientIp?: Maybe<string>;
+}
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.exchangeSignInTicket}.
+ */
+export interface UserExternalConnectionOAuthTicketExchangeInput {
+    readonly ticket?: Maybe<string>;
+    readonly verifier?: Maybe<string>;
+    readonly clientIp?: Maybe<string>;
+}
+/**
+ * The custom token a redeemed ticket yields.
+ */
+export interface UserExternalConnectionOAuthTicketExchangeResult {
+    readonly customToken: string;
+}
+/**
+ * Reads the `/signin` request's values.
+ *
+ * @param request - The incoming sign-in request.
+ * @returns The challenge, return path, and client IP the request carried.
+ */
+/**
+ * The query parameter the sign-in ticket is returned on.
+ */
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_TICKET_PARAM = "ticket";
+export interface UserExternalConnectionSignInRedirectUrlInput {
+    /**
+     * The configured sign-in success URL.
+     */
+    readonly baseUrl: WebsiteUrl;
+    /**
+     * The allowlisted return path, when the request named one.
+     */
+    readonly returnPath?: Maybe<string>;
+    readonly ticket: string;
+}
+/**
+ * Builds the URL a completed sign-in redirects to.
+ *
+ * `returnPath` REPLACES the base URL's path rather than being appended to it, and has already been
+ * checked against the app's allowlist by the time it gets here — so the origin is always the
+ * configured one and this cannot become an open redirect.
+ *
+ * @param input - The base URL, the validated return path, and the ticket.
+ * @returns The redirect URL carrying the ticket.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionSignInRedirectUrl(input: UserExternalConnectionSignInRedirectUrlInput): WebsiteUrl;
+/**
+ * The query parameter a failed sign-in returns its reason code on.
+ */
+export declare const USER_EXTERNAL_CONNECTION_SIGN_IN_ERROR_PARAM = "signInError";
+export interface UserExternalConnectionSignInFailureRedirectUrlInput {
+    /**
+     * The configured sign-in failure URL.
+     */
+    readonly baseUrl: WebsiteUrl;
+    /**
+     * The allowlisted reason code, when the failure carried a reportable one.
+     */
+    readonly errorCode?: Maybe<string>;
+}
+/**
+ * Builds the URL a failed sign-in redirects to.
+ *
+ * Mirrors {@link userExternalConnectionSignInRedirectUrl}, minus the return path: a refusal belongs
+ * on the page that can explain it, not wherever the sign-in was headed. The reason is a CODE the app
+ * maps to its own copy — a server message rendered verbatim in a browser is both an information leak
+ * and untranslatable.
+ *
+ * @param input - The base URL and the allowlisted reason code.
+ * @returns The redirect URL, carrying the reason when there was one.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionSignInFailureRedirectUrl(input: UserExternalConnectionSignInFailureRedirectUrlInput): WebsiteUrl;
+/**
+ * Reads the values a `/signin` request carries.
+ *
+ * @param request - The incoming sign-in request.
+ * @returns The challenge, return path, and client IP the request carried.
+ */
+export declare function userExternalConnectionOAuthSignInValuesForRequest(request: Request): UserExternalConnectionOAuthSignInRequestValues;
 /**
  * Reads the `state` an authorize request should carry to the provider.
  *
@@ -136,7 +285,29 @@ export declare abstract class AbstractUserExternalConnectionOAuthService {
      * it here would be a cycle. This service needs only the raw read.
      */
     abstract readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+    /**
+     * OPTIONAL: resolves a third-party identity to a Firebase uid and mints its custom token.
+     *
+     * Absent for an app that only ever CONNECTS providers — the sign-in routes then refuse every
+     * request, which is the correct behavior for an app that never asked for them. A provider adapter
+     * makes this available by taking it as an `@Optional()` injected constructor property.
+     */
+    readonly userExternalConnectionSignInService?: Maybe<UserExternalConnectionSignInService>;
+    /**
+     * OPTIONAL: the app's per-provider policies. A missing registry means every provider takes the
+     * default policy, whose `signIn` is false.
+     */
+    readonly userExternalConnectionProviderPolicyRegistry?: Maybe<UserExternalConnectionProviderPolicyRegistry>;
+    /**
+     * OPTIONAL: the rate limiter applied to the unauthenticated sign-in routes.
+     *
+     * When an app provides none, {@link memoryUserExternalConnectionSignInThrottle} is installed
+     * instead — an unthrottled account-creation endpoint is not an acceptable default, even though a
+     * per-process limiter is a weaker guarantee than a shared one.
+     */
+    readonly userExternalConnectionSignInThrottle?: Maybe<UserExternalConnectionSignInThrottle>;
     private readonly _logger;
+    private readonly _fallbackSignInThrottle;
     protected get logger(): Logger;
     get providerType(): UserExternalConnectionProviderType;
     get redirectUri(): WebsiteUrl;
@@ -145,10 +316,26 @@ export declare abstract class AbstractUserExternalConnectionOAuthService {
     /**
      * PROVIDER: builds the provider's consent-screen URL carrying the minted state.
      *
-     * @param state - The signed state to echo back on the callback.
+     * @param input - The signed state to echo back on the callback, plus the PKCE challenge when the
+     *   flow has one.
      * @returns The authorize URL to redirect the user's browser to.
      */
-    protected abstract authorizeUrlForState(state: UserExternalConnectionOAuthState): WebsiteUrl;
+    protected abstract authorizeUrlForState(input: UserExternalConnectionOAuthAuthorizeUrlInput): WebsiteUrl;
+    /**
+     * PROVIDER (optional): reads the identity a SIGN-IN is attributed to.
+     *
+     * Optional because a connect needs no identity to succeed — an unlabeled connection is fully
+     * usable, which is why `credentialsForAuthorizationCode` treats the identity read as best-effort.
+     * A sign-in is the opposite: with no stable external id there is nothing to key the account on, so
+     * the default below fails hard rather than falling back to a mutable username or an email.
+     *
+     * Override it on a provider whose identity carries more than the exchange already captured — an
+     * email and its verified flag, which the account-linking rules depend on.
+     *
+     * @param input - The credentials the exchange produced.
+     * @returns The identity to sign in as.
+     */
+    protected signInIdentityForCredentials(input: UserExternalConnectionOAuthSignInIdentityInput): Promise<UserExternalConnectionSignInIdentity>;
     /**
      * PROVIDER: exchanges the authorization code and maps the token response to credentials.
      *
@@ -179,6 +366,21 @@ export declare abstract class AbstractUserExternalConnectionOAuthService {
      * @returns The refreshed credentials.
      */
     refreshCredentials?(input: UserExternalConnectionOAuthRefreshCredentialsInput): Promise<UserExternalConnectionCredentials>;
+    /**
+     * PROVIDER (optional): revokes the stored credentials at the provider.
+     *
+     * Deleting the stored credentials ends OUR ability to act as the user; it does not end the
+     * provider's grant, so a token captured before the disconnect stays usable until it expires — which
+     * for Discord is seven days. A provider implementing this closes that window.
+     *
+     * Optional and PUBLIC for the same reasons as `refreshCredentials`: not every provider exposes a
+     * revocation endpoint, and the caller reaches it through the registry rather than through a
+     * subclass. Implementations should not throw on an already-invalid token — a disconnect must
+     * succeed regardless of what the provider says about a credential it is about to forget.
+     *
+     * @param input - The acting user and the credentials being discarded.
+     */
+    revokeCredentials?(input: UserExternalConnectionOAuthRevokeCredentialsInput): Promise<void>;
     /**
      * Carries the stored refresh token forward when a provider's exchange returned none.
      *
@@ -203,6 +405,65 @@ export declare abstract class AbstractUserExternalConnectionOAuthService {
      * @returns The authorize URL, or null when the request carried no state.
      */
     authorizeUrlForRequest(request: Request): Maybe<WebsiteUrl>;
+    /**
+     * The provider's resolved policy.
+     *
+     * @returns The policy, with every optional field defaulted.
+     */
+    get policy(): import("..").UserExternalConnectionResolvedProviderPolicy;
+    /**
+     * Whether this provider may be used to sign in.
+     *
+     * Requires BOTH the app's policy opt-in and a registered sign-in service: a policy that says yes
+     * with nothing able to resolve a uid would fail at the callback instead of at the front door.
+     *
+     * @returns True when a sign-in request for this provider may proceed.
+     */
+    get signInEnabled(): boolean;
+    /**
+     * Where a sign-in returns to on success, before the ticket is appended.
+     *
+     * @returns The configured sign-in success url, falling back to the connect success url.
+     */
+    get signInSuccessUrl(): WebsiteUrl;
+    /**
+     * Where a FAILED sign-in returns to, before the reason code is appended.
+     *
+     * Falls back to the connect failure url, which is the pre-existing behavior — but an app that
+     * configures one gets its login page instead of the auth-gated page a signed-out user cannot see.
+     *
+     * @returns The configured sign-in failure url, falling back to the connect failure url.
+     */
+    get signInFailureUrl(): WebsiteUrl;
+    /**
+     * Builds the authorize URL for an unauthenticated SIGN-IN request.
+     *
+     * Unlike the connect direction, the state is minted HERE: there is no prior authenticated call to
+     * mint it, so the browser's PKCE challenge is what binds the flow instead of a uid. A provider PKCE
+     * verifier is generated at the same time and sealed into the same state, which is the only reason
+     * the exchange can answer a challenge without a server-side store.
+     *
+     * @param request - The incoming sign-in request.
+     * @returns The authorize URL, or null when the request must be bounced to the failure URL.
+     */
+    signInUrlForRequest(request: Request): Promise<Maybe<WebsiteUrl>>;
+    /**
+     * Redeems a sign-in ticket for the custom token it carries.
+     *
+     * The token is handed back on a POST rather than in the redirect's query string: a URL-borne
+     * credential lands in browser history, the `Referer` header, and every proxy log on the way.
+     *
+     * @param input - The ticket and the verifier the browser retained.
+     * @returns The custom token, or null when the ticket cannot be redeemed.
+     */
+    exchangeSignInTicket(input: UserExternalConnectionOAuthTicketExchangeInput): Promise<Maybe<UserExternalConnectionOAuthTicketExchangeResult>>;
+    /**
+     * Records a sign-in attempt against the throttle and returns whether it should be rejected.
+     *
+     * @param clientIp - The caller's IP, when one could be resolved.
+     * @returns True when the attempt is throttled.
+     */
+    protected throttleSignInAttempt(clientIp: Maybe<string>): Promise<boolean>;
     /**
      * Verifies the returned state, exchanges the authorization code, and persists the credentials.
      *
@@ -213,4 +474,36 @@ export declare abstract class AbstractUserExternalConnectionOAuthService {
      * @returns Where to redirect the user, and whether the handoff succeeded.
      */
     handleCallback(input: UserExternalConnectionOAuthHandleCallbackInput): Promise<UserExternalConnectionOAuthCallbackResult>;
+    /**
+     * Completes the SIGN-IN half of a callback: identity, uid, connection, custom token, ticket.
+     *
+     * The connection is written with the same paired write a connect uses, so a user who signed in
+     * through a provider is connected to it in exactly the same way — there is no second
+     * representation of "this user's Discord account" to keep in sync.
+     *
+     * @param actor - The verified sign-in state.
+     * @param exchanged - The credentials the code exchange produced.
+     * @returns The success URL, carrying the sign-in ticket.
+     */
+    protected completeSignInCallback(actor: UserExternalConnectionSignInStateActor, exchanged: UserExternalConnectionCredentials): Promise<WebsiteUrl>;
+    /**
+     * Completes the LINK half of a callback: identity, login link, redirect.
+     *
+     * The narrowest of the three branches, and deliberately so. It stores NO credentials: the grant this
+     * round trip obtained carries the identity scopes, which are not the data scopes, so persisting it
+     * as the data connection would silently replace a broad grant with a narrow one.
+     *
+     * It also does NOT revoke anything. Re-authorizing the same OAuth client with narrower scopes may or
+     * may not invalidate the previously issued broad token depending on the provider — and on Discord a
+     * revoke drops the grant for the whole client, which would kill the data connection this link was
+     * meant to be independent of.
+     *
+     * Returns to the CONNECT success url rather than a link-specific one: the link is started from the
+     * settings page, which is where the user should land, and that is already what `successUrl` names.
+     *
+     * @param actor - The verified link state.
+     * @param exchanged - The credentials the code exchange produced.
+     * @returns The success URL.
+     */
+    protected completeLinkCallback(actor: UserExternalConnectionLinkStateActor, exchanged: UserExternalConnectionCredentials): Promise<WebsiteUrl>;
 }