@voltro/plugin-auth-social 0.34.0

package/dist/index.d.ts

@@ -0,0 +1,666 @@
+import { AuthConfig } from '@voltro/plugin-auth';
+import { Effect } from 'effect';
+import { Predicate } from '@voltro/database';
+import { Subject } from '@voltro/protocol';
+import { TableLike } from '@voltro/database';
+import { UserStore } from '@voltro/plugin-auth';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/** Default lifetime we mint. Minutes, not months — see the header. */
+export declare const APPLE_CLIENT_SECRET_DEFAULT_TTL_S = 900;
+
+/** Apple's documented ceiling on a client-secret JWT: six months. */
+export declare const APPLE_CLIENT_SECRET_MAX_TTL_S = 15777000;
+
+/**
+ * Mint (or reuse, within its lifetime) Apple's client-secret JWT for
+ * `clientId`.
+ *
+ * ES256 via `node:crypto` rather than a JWS library: Node's `sign` with
+ * `dsaEncoding: 'ieee-p1363'` emits the raw `r || s` pair JOSE requires, which
+ * is the only fiddly part of ES256, and doing it here keeps this package free
+ * of a signing dependency. (`jose` still verifies the ID token — through
+ * `@voltro/protocol/jwt`, which every IdP plugin here shares.)
+ */
+export declare const appleClientSecret: (clientId: string, key: AppleClientSecretKey, now?: () => number) => string;
+
+/**
+ * The material Apple hands you in the developer portal. All three are
+ * configuration, never literals in source: `privateKey` is the contents of the
+ * downloaded `.p8` (a PKCS#8 PEM) and belongs in an env var.
+ */
+export declare interface AppleClientSecretKey {
+    /** Apple Developer Team ID (10 chars) — becomes the JWT's `iss`. */
+    readonly teamId: string;
+    /** The Key ID of the `.p8` — becomes the JWT header's `kid`. */
+    readonly keyId: string;
+    /** The `.p8` file's contents: a PKCS#8 PEM holding a P-256 private key. */
+    readonly privateKey: string;
+    /** Lifetime of each minted secret, seconds. Default 900 (15 min); anything
+     *  above {@link APPLE_CLIENT_SECRET_MAX_TTL_S} is rejected. */
+    readonly ttlSeconds?: number;
+}
+
+/** The one-time name (and email) Apple posts alongside the FIRST callback. */
+export declare interface AppleUserPayload {
+    readonly firstName: string | null;
+    readonly lastName: string | null;
+    readonly email: string | null;
+}
+
+/**
+ * Resolve a verified social profile into a session, applying the account-link
+ * policy and the subject guards.
+ *
+ * Returns a refusal rather than failing: every branch here is an expected
+ * outcome of a normal login attempt (the account exists unlinked, the address
+ * is unverified, a guard vetoed), and modelling those as defects would push
+ * callers into `catchAll` for the ordinary path.
+ */
+export declare const completeSocialSignIn: (o: SocialSignInOptions) => Effect.Effect<SocialSignInResult>;
+
+/** DataStore-backed store — the production choice. Bind it from the plugin's
+ *  `bindDataStore` hook, or construct it yourself over `ctx.store`. */
+export declare const dataStoreSocialIdentityStore: (store: SocialIdentityDataStore) => SocialIdentityStore;
+
+/**
+ * Decide what a verified social identity means for local accounts.
+ *
+ * Pure and total — no store, no clock, no IO — so every branch is directly
+ * testable, including the ones that must NEVER fire.
+ */
+export declare const decideSocialLink: (input: SocialLinkInput) => SocialLinkDecision;
+
+/**
+ * Resolve the authenticated GitHub user behind an access token.
+ *
+ * The `/user/emails` read is best-effort: a token issued without `user:email`
+ * (or a GitHub App restricted from it) 403s, and that is a configuration
+ * problem for the app to notice — not a reason to fail the login, and above all
+ * not a reason to fall back to the unverified profile email. We return
+ * `email: null, emailVerified: false` and let the link policy decide.
+ */
+export declare const fetchGithubIdentity: (accessToken: string, options: {
+    readonly apiBase: string;
+    readonly fetchImpl?: typeof fetch;
+}) => Promise<GithubIdentity>;
+
+/** What we take from GitHub, before it is folded into a `SocialProfile`. */
+export declare interface GithubIdentity {
+    readonly accountId: string;
+    readonly login: string;
+    readonly name: string | null;
+    readonly avatarUrl: string | null;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+}
+
+/** Is this one of Apple's per-app relay addresses? Used as a fallback when the
+ *  `is_private_email` claim is absent (older tokens omit it). */
+export declare const isApplePrivateRelayEmail: (email: string | null) => boolean;
+
+/** Narrow an arbitrary string to a shipped provider id. */
+export declare const isSocialProviderId: (value: string) => value is SocialProviderId;
+
+/**
+ * Attach a provider account to a user you have ALREADY authenticated.
+ *
+ * This is the linking that is always sound, and the escape hatch every app on
+ * the default `'never'` policy needs: the proof that the person may attach an
+ * identity to this account is that they are holding a session for it. Call it
+ * from an authenticated route after `socialCompleteLogin` returns a profile.
+ *
+ * Idempotent: re-linking the same provider account to the same user returns the
+ * existing row. Linking a provider account that belongs to a DIFFERENT user
+ * fails — one provider account, one local user, or the identity stops being an
+ * identity.
+ */
+export declare const linkSocialIdentity: (store: SocialIdentityStore, userId: string, input: Omit<SocialIdentityInput, "userId">) => Effect.Effect<SocialIdentityRecord, Error>;
+
+/** In-memory store — tests and single-process dev. Restart wipes it, which for
+ *  this table means every user's social login unlinks. Not for production. */
+export declare const memorySocialIdentityStore: (seed?: ReadonlyArray<SocialIdentityRecord>) => SocialIdentityStore;
+
+/**
+ * Parse Apple's `user` form field. Returns `null` for an absent or unparseable
+ * value — which is the NORMAL case on every authorization after the first, not
+ * an error. A caller that treats a missing name as a failure locks out every
+ * returning user.
+ */
+export declare const parseAppleUserPayload: (raw: string | undefined | null) => AppleUserPayload | null;
+
+/** Test seam — drop the parsed-key and minted-secret caches. */
+export declare const _resetAppleSecretCache: () => void;
+
+export declare const SOCIAL_IDENTITY_TABLE = "_voltro_oauth_identities";
+
+/** Every shipped provider id. */
+export declare const SOCIAL_PROVIDER_IDS: ReadonlyArray<SocialProviderId>;
+
+/** Every shipped provider, in a stable order. */
+export declare const SOCIAL_PROVIDERS: ReadonlyArray<SocialProviderDescriptor>;
+
+/**
+ * The provider authenticated someone, and we refused to turn that into a
+ * session for an EXISTING local account.
+ *
+ * Not an authentication failure — the provider's answer was fine. It is the
+ * account-linking policy declining to attach an unproven identity to an account
+ * that already exists. See `linking.ts` for why that is the default.
+ */
+export declare class SocialAccountLinkError extends SocialAuthError {
+    constructor(code: SocialAuthErrorCode, message: string, status?: number);
+}
+
+/**
+ * Base class for every social-login failure. `status` is the HTTP status the
+ * route layer answers with, so a caller wiring the primitives by hand gets the
+ * same status the shipped plugin would produce.
+ */
+export declare class SocialAuthError extends Error {
+    readonly status: number;
+    readonly code: SocialAuthErrorCode;
+    constructor(status: number, code: SocialAuthErrorCode, message: string);
+}
+
+/** Every failure this package produces. `code` is stable across releases. */
+export declare type SocialAuthErrorCode = 
+/** No provider by that id, or the provider is not configured. */
+'unknown_provider'
+/** The plugin/primitive was called with an unusable configuration. */
+| 'config'
+/** No `code` in the callback, or the request was not a callback at all. */
+| 'missing_code'
+/** The callback's `state` did not match the one minted for this browser. */
+| 'state_mismatch'
+/** The PKCE verifier for this login was not presented back. */
+| 'missing_verifier'
+/** The provider refused the authorization-code exchange. */
+| 'exchange_failed'
+/** The provider's response was well-formed HTTP but not a usable token set. */
+| 'malformed_token_response'
+/** The ID token failed signature / iss / aud / exp verification. */
+| 'id_token_invalid'
+/** The ID token verified but its `nonce` was not the one we minted. */
+| 'nonce_mismatch'
+/** The provider identified the user but gave us no email to work with. */
+| 'no_email'
+/** An account with this email exists and the link policy refused to attach. */
+| 'account_exists_unlinked'
+/** Linking requires a provider-VERIFIED email and this one is not. */
+| 'email_not_verified'
+/** Linking refused because the address is a per-app Apple private relay. */
+| 'private_relay_email'
+/** A post-authentication subject guard vetoed the login. */
+| 'guard_rejected';
+
+export declare const socialAuthPlugin: (options: SocialAuthPluginOptions) => VoltroPlugin;
+
+export declare interface SocialAuthPluginOptions {
+    /** Which providers this app offers. A key with an empty object takes every
+     *  credential from the environment. */
+    readonly providers: Partial<Record<SocialProviderId, SocialProviderConfig>>;
+    /** The same user store `authRoutesPlugin` runs on. */
+    readonly users: UserStore;
+    /**
+     * Where identities are recorded. Omit and the plugin builds a
+     * DataStore-backed store over the route's boot store — which needs
+     * `_voltro_oauth_identities`, contributed here via `extendSchema`.
+     */
+    readonly identities?: SocialIdentityStore;
+    /** The same `AuthConfig` the auth routes plugin runs on: session secret,
+     *  cookie flags, default tenant, post-authentication subject guards. */
+    readonly auth: AuthConfig;
+    /**
+     * How a social identity may attach to a PRE-EXISTING local account.
+     * Default `'never'` — read `linking.ts` before changing it. `'verified-email'`
+     * is a deliberate, bounded risk, not a convenience toggle.
+     */
+    readonly linkPolicy?: SocialLinkPolicy;
+    /** Route prefix. Default `/auth/social`. */
+    readonly prefix?: string;
+    /** Absolute origin used to build the default redirect URIs, e.g.
+     *  `https://app.example.com`. Falls back to `auth.appBaseUrl`. */
+    readonly appBaseUrl?: string;
+    /** Where to send the browser after a successful login. Falls back to
+     *  `auth.successRedirect`, then `/`. */
+    readonly successRedirect?: string;
+    /**
+     * Where to send the browser after a REFUSED login. When set, the refusal's
+     * stable `code` is appended as `?social_error=<code>` so the page can explain
+     * itself. Omit to answer with a JSON body instead (the default) — useful
+     * while wiring, unhelpful to an end user.
+     */
+    readonly failureRedirect?: string;
+    /** How long a started login may take to come back. Default 600s (10 min). */
+    readonly stateTtlSeconds?: number;
+    /** Name of the short-lived login-state cookie. Default `voltro:oauth`. */
+    readonly stateCookieName?: string;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/** The tables this package contributes, as an array. */
+export declare const socialAuthTables: readonly [TableLike];
+
+/**
+ * Begin a social login: mint `state`, a PKCE `code_verifier` and an OIDC
+ * `nonce`, and build the authorize URL carrying `state` and the S256
+ * `code_challenge`.
+ *
+ * **`state` is not optional and is not caller-supplied.** In the WorkOS
+ * package it used to be both, and the shape of that defect is the reason this
+ * one has no `state` option at all: an attacker who gets a victim's browser to
+ * hit the callback with an authorization code THEY obtained logs the victim
+ * into the ATTACKER's account, and `state` is the only thing that stops it.
+ * Making it opt-in made "the login works" indistinguishable from "the login is
+ * forgeable". An app that wants to carry a post-login return path puts it in
+ * its own cookie next to these values — mixing an application payload into a
+ * CSRF nonce is precisely what made the nonce guessable.
+ *
+ * **PKCE (S256) rides along on every provider, including the one that ignores
+ * it.** The authorization code travels through the address bar and the referrer
+ * chain; without a verifier anyone who captures it before we redeem it can
+ * redeem it themselves. Google and Apple enforce the verifier; GitHub's OAuth
+ * app flow does not implement RFC 7636 and ignores the parameter. Sending it
+ * anyway costs nothing and removes the branch where a future provider addition
+ * quietly lands on the no-PKCE side.
+ *
+ * **`nonce` is minted for OIDC providers and checked against the ID token.**
+ * It is what makes a replayed ID token from another login fail here.
+ */
+export declare const socialBeginLogin: (o: SocialBeginLoginOptions) => SocialLoginHandoff;
+
+export declare interface SocialBeginLoginOptions {
+    readonly provider: SocialProviderId;
+    /** The OAuth client id issued by the provider. For Apple this is the
+     *  Services ID (`com.example.web`), not the App ID. */
+    readonly clientId: string;
+    /** The callback URL the provider redirects (or POSTs) back to. Must be
+     *  registered with the provider, byte for byte. */
+    readonly redirectUri: string;
+    /** Override the provider's default scopes. The defaults are the minimum
+     *  needed to identify the user; ask for more only when you use more. */
+    readonly scopes?: ReadonlyArray<string>;
+    /** Pre-fill the account chooser (Google `login_hint`, GitHub `login`). */
+    readonly loginHint?: string;
+    /** Google only: `'consent'` / `'select_account'` / … Passed through. */
+    readonly prompt?: string;
+    readonly endpoints?: SocialEndpointOverrides;
+    /**
+     * Inject the random values instead of minting them. TESTS ONLY — a
+     * deterministic `state` is a CSRF token an attacker can also predict, and a
+     * deterministic `codeVerifier` is no PKCE at all.
+     */
+    readonly randomness?: {
+        readonly state: string;
+        readonly codeVerifier: string;
+        readonly nonce: string;
+    };
+}
+
+/**
+ * Exchange an authorization code for a verified identity — AFTER checking the
+ * CSRF `state`, and carrying the PKCE `code_verifier`.
+ *
+ * **The state check lives inside this function rather than beside the caller's
+ * `if (!code)` deliberately.** A generated `state` that nothing verifies is
+ * worse than no state at all: it makes a code review, a screenshot of the
+ * authorize URL and a penetration test all read as "CSRF is handled". Making
+ * the check part of the only function that can redeem a code means an
+ * integration cannot arrive at an identity without having performed it — the
+ * loop is closed by the type signature, not by a note in the docs.
+ *
+ * Both `state` and `nonce` are compared in constant time. Neither is a
+ * high-value secret, but both ARE secrets compared against attacker-supplied
+ * input, and a `===` on that shape is a habit this repo does not keep.
+ */
+export declare const socialCompleteLogin: (o: SocialCompleteLoginOptions) => Promise<SocialProfile>;
+
+export declare interface SocialCompleteLoginOptions {
+    readonly provider: SocialProviderId;
+    readonly clientId: string;
+    /** Google / GitHub: the OAuth client secret. Apple: omit and pass
+     *  {@link SocialCompleteLoginOptions.appleKey} — its secret is a JWT we sign. */
+    readonly clientSecret?: string;
+    /** Apple only: the `.p8` key material a client secret is minted from. */
+    readonly appleKey?: AppleClientSecretKey;
+    /** Must be byte-identical to the one used to begin the login. */
+    readonly redirectUri: string;
+    /** The `code` from the callback. */
+    readonly code: string;
+    /** The `state` the browser presented back. */
+    readonly state: string;
+    /** The `state` `socialBeginLogin` minted, read back out of wherever the app
+     *  stashed it. */
+    readonly expectedState: string;
+    /** The PKCE verifier `socialBeginLogin` minted. */
+    readonly codeVerifier: string;
+    /** The OIDC nonce `socialBeginLogin` minted. Required for Google and Apple;
+     *  meaningless for GitHub, which returns no ID token. */
+    readonly expectedNonce?: string;
+    /** Apple only: the raw `user` form field. Present on the FIRST authorization
+     *  and never again — see `apple.ts`. */
+    readonly appleUserPayload?: string;
+    readonly endpoints?: SocialEndpointOverrides;
+    /** Injectable fetch for tests. */
+    readonly fetchImpl?: typeof fetch;
+    /** Injectable clock (epoch-ms), used when minting Apple's client secret. */
+    readonly now?: () => number;
+}
+
+/** The plugin or a primitive was configured in a way that cannot work. */
+export declare class SocialConfigError extends SocialAuthError {
+    constructor(message: string);
+}
+
+/**
+ * Per-call endpoint overrides. Exists so the test suite can point a provider at
+ * a loopback server that serves a JWKS and a token endpoint — the whole flow is
+ * then exercised end to end without a network or a real client secret.
+ *
+ * NOT an integration seam for pointing production at a different host: an
+ * `issuer` override is an override of the thing the ID token is checked
+ * against, so a wrong value here silently accepts tokens from somewhere else.
+ */
+export declare interface SocialEndpointOverrides {
+    readonly authorizeUrl?: string;
+    readonly tokenUrl?: string;
+    readonly jwksUrl?: string;
+    readonly issuer?: string;
+    readonly apiBase?: string;
+}
+
+/** The provider refused (or mangled) the authorization-code exchange. */
+export declare class SocialExchangeError extends SocialAuthError {
+    constructor(code: SocialAuthErrorCode, message: string, status?: number);
+}
+
+/**
+ * The social-identity table.
+ *
+ * `[provider, providerAccountId]` is a composite UNIQUE — the DB enforces the
+ * one-row-per-provider-account invariant the callback depends on, and the
+ * unique constraint doubles as the index backing the lookup, so no separate
+ * `.index([...])` on the same columns is needed.
+ */
+export declare const socialIdentitiesTable: TableLike;
+
+/** The slice of `DataStore` this store needs — narrow so a caller can pass a
+ *  transactional view, a namespaced view, or a test double. */
+export declare interface SocialIdentityDataStore {
+    query(descriptor: {
+        readonly table: string;
+        readonly predicate?: Predicate;
+        readonly limit?: number;
+        readonly order?: ReadonlyArray<{
+            readonly column: string;
+            readonly direction: 'asc' | 'desc';
+        }>;
+    }): Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+    insert(table: string, row: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>> | null>;
+    delete(table: string, primaryKey: string): Promise<boolean>;
+}
+
+/** What a caller supplies to link an identity; ids + timestamps are ours. */
+export declare interface SocialIdentityInput {
+    readonly userId: string;
+    readonly provider: string;
+    readonly providerAccountId: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+}
+
+export declare interface SocialIdentityRecord {
+    readonly id: string;
+    readonly userId: string;
+    readonly provider: string;
+    readonly providerAccountId: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+    readonly createdAt: Date;
+    readonly lastLoginAt: Date | null;
+}
+
+/**
+ * The identity store contract. Effect-native, mirroring `UserStore` in
+ * `@voltro/plugin-auth` so the two compose without adapters.
+ */
+export declare interface SocialIdentityStore {
+    /** Resolve a provider account to a linked identity, or null. */
+    readonly findByProviderAccount: (provider: string, providerAccountId: string) => Effect.Effect<SocialIdentityRecord | null>;
+    /** Every provider a user has connected — the account-settings list. */
+    readonly listForUser: (userId: string) => Effect.Effect<ReadonlyArray<SocialIdentityRecord>>;
+    /** Create the link. */
+    readonly insert: (input: SocialIdentityInput) => Effect.Effect<SocialIdentityRecord>;
+    /** Stamp `lastLoginAt` on a returning login. */
+    readonly touch: (identityId: string, at: Date) => Effect.Effect<void>;
+    /** Unlink a provider from a user. Returns whether a row was removed. */
+    readonly remove: (userId: string, provider: string) => Effect.Effect<boolean>;
+}
+
+/**
+ * The ID token did not verify, or verified into claims we refuse.
+ *
+ * Signature, `iss`, `aud`, `exp`/`iat` and `nonce` all land here. They are ONE
+ * class on purpose: which of the five failed is useful in a log (the `message`
+ * says) and useless to the caller, who must do the same thing regardless —
+ * refuse the login.
+ */
+export declare class SocialIdTokenError extends SocialAuthError {
+    constructor(code: 'id_token_invalid' | 'nonce_mismatch', message: string);
+}
+
+/** What the caller should do with this login. */
+export declare type SocialLinkDecision = 
+/** The identity is already linked — sign this user in. */
+    {
+    readonly kind: 'sign-in';
+    readonly userId: string;
+}
+/** No identity, no account with this email — provision a new user. */
+| {
+    readonly kind: 'create-user';
+}
+/** No identity, but an account with this email exists and the policy
+*  permits attaching to it. */
+| {
+    readonly kind: 'link';
+    readonly userId: string;
+}
+/** Refuse the login. `error` carries the status + machine-readable code. */
+| {
+    readonly kind: 'refuse';
+    readonly error: SocialAccountLinkError;
+};
+
+export declare interface SocialLinkInput {
+    readonly profile: SocialProfile;
+    /** The user the `(provider, providerAccountId)` identity row points at, or
+     *  null when this provider account has never signed in here. */
+    readonly linkedUserId: string | null;
+    /** The user whose email equals the profile's, or null. Only consulted when
+     *  `linkedUserId` is null. */
+    readonly existingUserIdByEmail: string | null;
+    readonly policy: SocialLinkPolicy;
+}
+
+/** How a social identity may attach to a PRE-EXISTING local account. */
+export declare type SocialLinkPolicy = 'never' | 'verified-email';
+
+/**
+ * What a login handoff produces: the URL to send the browser to, plus the three
+ * secrets the CALLBACK has to be able to present back.
+ *
+ * All three must be stashed somewhere the same browser will return them from —
+ * a short-lived `HttpOnly` cookie is the usual answer, and what `socialAuthPlugin`
+ * does — and handed to `socialCompleteLogin`. There is no server-side store
+ * here on purpose: this layer is transport-thin, and where an app keeps a
+ * ten-minute nonce is the app's decision.
+ */
+export declare interface SocialLoginHandoff {
+    readonly provider: SocialProviderId;
+    /** The provider's authorize URL to redirect the browser to. */
+    readonly url: string;
+    /** The CSRF nonce. Compare against the callback's `state` before exchanging. */
+    readonly state: string;
+    /** The PKCE verifier. Send it with the code exchange. */
+    readonly codeVerifier: string;
+    /** The OIDC replay nonce, bound into the ID token. Empty string for a
+     *  provider with no ID token (GitHub) — there is nothing to bind it to. */
+    readonly nonce: string;
+    /**
+     * How the provider will come back. `'form_post'` (Apple) means a CROSS-SITE
+     * POST, which a `SameSite=Lax` cookie is not sent on — the caller must store
+     * the three values above in a `SameSite=None; Secure` cookie or the callback
+     * will look exactly like a state mismatch.
+     */
+    readonly responseMode: SocialResponseMode;
+}
+
+/**
+ * A verified identity, normalised across the three providers.
+ *
+ * `emailVerified` is the field every security decision downstream reads. It is
+ * the PROVIDER's assertion that it verified ownership of `email` — never our
+ * inference, and never `true` by default. See `linking.ts`.
+ */
+export declare interface SocialProfile {
+    readonly provider: SocialProviderId;
+    /** The provider's stable, opaque id for this account — `sub` on Google and
+     *  Apple, the numeric account id on GitHub. This, not the email, is what an
+     *  identity row is keyed by: an email can change hands, this cannot. */
+    readonly providerAccountId: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+    /** Apple "Hide My Email": the address is real and verified but is a per-app
+     *  alias, not the user's address. */
+    readonly emailIsPrivateRelay: boolean;
+    readonly name: string | null;
+    readonly firstName: string | null;
+    readonly lastName: string | null;
+    readonly avatarUrl: string | null;
+    /**
+     * True when the name in this profile came from a source that will NOT be
+     * present next time — Apple's first-authorization `user` payload. If you want
+     * to display the user's name, this is the only callback that will ever carry
+     * it: persist it now.
+     */
+    readonly nameIsFirstAuthorizationOnly: boolean;
+    /** The verified ID-token claims (OIDC) or the raw API user (GitHub). Useful
+     *  for app-specific fields; never re-verified downstream. */
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/** Resolve a provider descriptor, applying any endpoint overrides. Throws
+ *  `SocialConfigError` for an unknown id. */
+export declare const socialProvider: (id: string, overrides?: SocialEndpointOverrides) => SocialProviderDescriptor;
+
+/** Per-provider credentials + options. Every field may instead come from the
+ *  environment (see {@link socialAuthPlugin}); nothing here has a default
+ *  value, because a default credential is a shipped secret. */
+export declare interface SocialProviderConfig {
+    readonly clientId?: string;
+    /** Google / GitHub. Apple has none — it uses {@link SocialProviderConfig.appleKey}. */
+    readonly clientSecret?: string;
+    /** Apple only: Team ID + Key ID + the `.p8` contents. */
+    readonly appleKey?: AppleClientSecretKey;
+    /** Override the provider's default scopes. */
+    readonly scopes?: ReadonlyArray<string>;
+    /** Override the callback URL. Defaults to
+     *  `<appBaseUrl><prefix>/<provider>/callback`. Must match the provider's
+     *  registered redirect byte for byte. */
+    readonly redirectUri?: string;
+    /** Test seam — point the provider at a loopback server. */
+    readonly endpoints?: SocialEndpointOverrides;
+}
+
+export declare interface SocialProviderDescriptor {
+    readonly id: SocialProviderId;
+    /** Human label — logs, and the "Sign in with X" button an app renders. */
+    readonly label: string;
+    readonly authorizeUrl: string;
+    readonly tokenUrl: string;
+    /** OIDC providers only: where the ID-token signing keys live. */
+    readonly jwksUrl: string | null;
+    /** OIDC providers only: the exact `iss` an ID token must carry. */
+    readonly issuer: string | null;
+    /** Plain-OAuth2 providers only: the API origin identity is read from. */
+    readonly apiBase: string | null;
+    readonly defaultScopes: ReadonlyArray<string>;
+    readonly kind: 'oidc' | 'oauth2';
+    readonly responseMode: SocialResponseMode;
+    /** Can the provider tell us, per address, that it verified ownership? */
+    readonly assertsEmailVerification: boolean;
+    /** Does the provider actually implement RFC 7636? We send the challenge
+     *  either way; this only says whether it is load-bearing there. */
+    readonly pkceEnforced: boolean;
+}
+
+/** The providers this package ships. */
+export declare type SocialProviderId = 'google' | 'github' | 'apple';
+
+/** How the provider hands the callback back to us. Apple POSTs (cross-site,
+ *  `form_post`) whenever `name` / `email` scopes are requested; the other two
+ *  redirect with a query string. This changes the cookie the state must live
+ *  in — see `plugin.ts`. */
+export declare type SocialResponseMode = 'query' | 'form_post';
+
+/** A completed social sign-in. */
+export declare interface SocialSignInOk {
+    readonly kind: 'ok';
+    readonly userId: string;
+    readonly subject: Subject;
+    /** Attach this to the response. */
+    readonly setCookie: string;
+    /** A new local user was provisioned by this login. */
+    readonly created: boolean;
+    /** The identity was attached to a PRE-EXISTING account by policy. */
+    readonly linked: boolean;
+    /** The profile carried a name that will never be sent again (Apple's
+     *  first authorization). Persist it now if you want to display it. */
+    readonly oneTimeName: {
+        readonly firstName: string | null;
+        readonly lastName: string | null;
+    } | null;
+}
+
+export declare interface SocialSignInOptions {
+    /** The verified identity from `socialCompleteLogin`. */
+    readonly profile: SocialProfile;
+    readonly identities: SocialIdentityStore;
+    readonly users: UserStore;
+    /** The same `AuthConfig` the auth routes plugin runs on — session secret,
+     *  cookie flags, default tenant, subject guards. */
+    readonly config: AuthConfig;
+    /** Default `'never'`. Read `linking.ts` before changing it. */
+    readonly policy?: SocialLinkPolicy;
+    /** Recorded on the session row for the device list. */
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+/** The login was refused. `code` is stable; `message` is safe to show a user. */
+export declare interface SocialSignInRefused {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+}
+
+export declare type SocialSignInResult = SocialSignInOk | SocialSignInRefused;
+
+/**
+ * The callback's `state` did not match the value minted for this browser.
+ *
+ * A distinct class because it is a distinct event: every other error means the
+ * provider or the account said no, this one means the request did not come from
+ * a login THIS server started. Worth alerting on separately — it is the shape a
+ * login-CSRF attempt takes.
+ */
+export declare class SocialStateMismatchError extends SocialAuthError {
+    constructor(message: string);
+}
+
+export { }