@voltro/plugin-auth-social 0.85.0 → 0.87.0

package/dist/index.d.ts

@@ -1,10 +1,18 @@
 import { AuthConfig } from '@voltro/plugin-auth';
+import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
+import { GuestAuthOptions } from '@voltro/plugin-auth';
+import { GuestAuthService } from '@voltro/plugin-auth';
+import { HotStoreShape } from '@voltro/kv/hot';
+import { PluginEnvVar } from '@voltro/protocol';
+import { PluginPermission } from '@voltro/protocol';
 import { Predicate } from '@voltro/database';
 import { Subject } from '@voltro/protocol';
 import { TableLike } from '@voltro/database';
 import { UserStore } from '@voltro/plugin-auth';
+import { VoidIfEmpty } from 'effect/Types';
 import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
 
 /** Default lifetime we mint. Minutes, not months — see the header. */
 export declare const APPLE_CLIENT_SECRET_DEFAULT_TTL_S = 900;
@@ -48,6 +56,13 @@ export declare interface AppleUserPayload {
     readonly email: string | null;
 }
 
+/** Preserve the guest subject ID. Conflict with any existing local email or
+ * provider link refuses with merge-required; this function never merges or
+ * moves another account automatically. A provider account without an address
+ * (Steam, Epic, a console) registers the guest without one, never a synthetic
+ * address. */
+export declare const completeGuestSocialUpgrade: (options: GuestSocialUpgradeOptions) => Effect.Effect<GuestSocialUpgradeResult>;
+
 /**
  * Resolve a verified social profile into a session, applying the account-link
  * policy and the subject guards.
@@ -61,7 +76,7 @@ export declare const completeSocialSignIn: (o: SocialSignInOptions) => Effect.Ef
 
 /** 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;
+export declare const dataStoreSocialIdentityStore: (store: SocialIdentityDataStore | Pick<DataStore, "query" | "insert" | "update" | "delete"> | Pick<DataStore, "query" | "insert" | "insertIgnoreWithOutcome" | "update" | "delete">) => SocialIdentityStore;
 
 /**
  * Decide what a verified social identity means for local accounts.
@@ -71,6 +86,68 @@ export declare const dataStoreSocialIdentityStore: (store: SocialIdentityDataSto
  */
 export declare const decideSocialLink: (input: SocialLinkInput) => SocialLinkDecision;
 
+/**
+ * A platform login for a platform Voltro does not ship: a console or store
+ * whose SDK issues a ticket your server can verify (often under NDA). `verify`
+ * receives the ticket exactly as the game sent it and returns the platform's
+ * stable account id, or throws {@link PlatformTicketError} when the platform
+ * refuses it.
+ */
+export declare const definePlatformLogin: (definition: PlatformLoginDefinition) => PlatformLogin;
+
+/** The authenticated Discord user, without an access token or arbitrary API
+ * payload. Discord snowflakes remain strings; number coercion loses bits. */
+export declare interface DiscordIdentity {
+    readonly accountId: string;
+    readonly login: string;
+    readonly name: string | null;
+    readonly avatarUrl: string | null;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+}
+
+/**
+ * Epic Online Services Connect: the game calls `EOS_Connect_CopyIdToken` after
+ * `EOS_Connect_Login` and sends the token; the server checks Epic's signature,
+ * issuer, client and deployment. The account id is the Product User ID, the one
+ * EOS keeps for a player across every account linked to it (Epic, Steam,
+ * consoles), so this login covers every platform EOS covers.
+ */
+export declare const eosPlatformLogin: (options?: EosPlatformLoginOptions) => PlatformLogin;
+
+export declare interface EosPlatformLoginOptions {
+    /** EOS client id the game initializes the SDK with. Default: `VOLTRO_EOS_CLIENT_ID`. */
+    readonly clientId?: string;
+    /** EOS deployment id; tokens from any other deployment are refused. Default: `VOLTRO_EOS_DEPLOYMENT_ID`. */
+    readonly deploymentId?: string;
+    /** Test seam — a loopback JWKS. */
+    readonly jwksUrl?: string;
+}
+
+export declare interface EpicIdentity {
+    readonly accountId: string;
+    readonly login: string;
+    readonly name: null;
+    readonly avatarUrl: null;
+    readonly email: null;
+    readonly emailVerified: false;
+}
+
+export declare const fetchDiscordIdentity: (accessToken: string, options: {
+    readonly apiBase: string;
+    readonly fetchImpl?: typeof fetch;
+}) => Promise<DiscordIdentity>;
+
+/** Authenticate through Epic's documented v2 token introspection endpoint.
+ * Account ids are read only from the server response, never a client payload
+ * or an unverified access-token body. No provider email proof is available. */
+export declare const fetchEpicIdentity: (accessToken: string, options: {
+    readonly apiBase: string;
+    readonly clientId: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => number;
+}) => Promise<EpicIdentity>;
+
 /**
  * Resolve the authenticated GitHub user behind an access token.
  *
@@ -95,6 +172,25 @@ export declare interface GithubIdentity {
     readonly emailVerified: boolean;
 }
 
+export declare interface GuestSocialUpgradeOptions {
+    /** Verified server-side provider result, never a client-submitted profile. */
+    readonly profile: SocialProfile;
+    readonly credential: string;
+    readonly store: DataStore;
+    readonly guest: GuestAuthOptions;
+    /** The same complete lifecycle port installed by the guest plugin. */
+    readonly service?: GuestAuthService;
+    readonly users: UserStore;
+    readonly config: AuthConfig;
+    /** Required when ensureActor is installed: bind its write to this same
+     * transaction. There must be no independent pool/write during promotion. */
+    readonly configForTransaction?: (store: DataStore) => AuthConfig;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+declare type GuestSocialUpgradeResult = SocialSignInOk | SocialSignInRefused;
+
 /** 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;
@@ -121,6 +217,12 @@ export declare const linkSocialIdentity: (store: SocialIdentityStore, userId: st
  *  this table means every user's social login unlinks. Not for production. */
 export declare const memorySocialIdentityStore: (seed?: ReadonlyArray<SocialIdentityRecord>) => SocialIdentityStore;
 
+declare interface NativeGuestUpgradeConfig {
+    /** Exact redirect URIs the app may name — a custom scheme (`acme://auth/upgrade`) or an
+     *  https universal link. No wildcards. */
+    readonly redirectUris: ReadonlyArray<string>;
+}
+
 /**
  * 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
@@ -129,6 +231,42 @@ export declare const memorySocialIdentityStore: (seed?: ReadonlyArray<SocialIden
  */
 export declare const parseAppleUserPayload: (raw: string | undefined | null) => AppleUserPayload | null;
 
+/** The platform account a verified ticket proves. */
+export declare interface PlatformAccount {
+    /** The platform's stable account id: a SteamID64, an EOS Product User ID, a
+     *  console account id. This, never a name, is what the identity row is keyed by. */
+    readonly accountId: string;
+}
+
+/** One platform a game can sign in with. Build one with {@link steamPlatformLogin},
+ *  {@link eosPlatformLogin} or {@link definePlatformLogin}. */
+export declare interface PlatformLogin {
+    /** Route segment and identity namespace: `steam`, `eos`, `xbox`, … */
+    readonly id: string;
+    /** Verify a ticket with the platform. Throws {@link PlatformTicketError} for a
+     *  ticket the platform refuses; any other failure answers 503. */
+    readonly verify: (ticket: string) => Promise<PlatformAccount>;
+    readonly declaredEnv: ReadonlyArray<PluginEnvVar>;
+    readonly permissions: ReadonlyArray<PluginPermission>;
+    /** Resolve every credential once; throws when one is missing. Runs at boot. */
+    readonly check: () => void;
+}
+
+export declare interface PlatformLoginDefinition {
+    readonly id: string;
+    readonly verify: (ticket: string) => Promise<PlatformAccount>;
+    readonly declaredEnv?: ReadonlyArray<PluginEnvVar>;
+    readonly permissions?: ReadonlyArray<PluginPermission>;
+    readonly check?: () => void;
+}
+
+/** The platform refused a game client's sign-in ticket. One class for every
+ *  reason, for the same reason as {@link SocialIdTokenError}: the caller must
+ *  refuse the sign-in either way, and the `message` says which check failed. */
+export declare class PlatformTicketError extends SocialAuthError {
+    constructor(message: string);
+}
+
 /** Test seam — drop the parsed-key and minted-secret caches. */
 export declare const _resetAppleSecretCache: () => void;
 
@@ -183,8 +321,6 @@ export declare type SocialAuthErrorCode =
 | '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. */
@@ -192,14 +328,24 @@ export declare type SocialAuthErrorCode =
 /** 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';
+| 'guard_rejected'
+/** The platform refused a game client's sign-in ticket (forged, expired,
+*  another app or deployment). */
+| 'ticket_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>>;
+    readonly providers?: Partial<Record<SocialProviderId, SocialProviderConfig>>;
+    /**
+     * Platforms a game client signs in with by ticket: `steamPlatformLogin()`,
+     * `eosPlatformLogin()`, or your own `definePlatformLogin(...)` for a console.
+     * Mounts `POST {prefix}/platform/{id}/sign-in`, and with `guestUpgrade` also
+     * `POST {prefix}/platform/{id}/link`. A platform account needs no email.
+     */
+    readonly platforms?: ReadonlyArray<PlatformLogin>;
     /** The same user store `authRoutesPlugin` runs on. */
     readonly users: UserStore;
     /**
@@ -238,6 +384,9 @@ export declare interface SocialAuthPluginOptions {
     readonly stateCookieName?: string;
     /** Disambiguates multiple instances of this plugin in one app. */
     readonly name?: string;
+    /** Opt-in two-step browser promotion. Provider login only prepares a signed
+     * handoff; a CSRF-protected confirmation must prove the durable guest device. */
+    readonly guestUpgrade?: SocialGuestUpgradeConfig;
 }
 
 /** The tables this package contributes, as an array. */
@@ -320,7 +469,7 @@ export declare const socialCompleteLogin: (o: SocialCompleteLoginOptions) => Pro
 export declare interface SocialCompleteLoginOptions {
     readonly provider: SocialProviderId;
     readonly clientId: string;
-    /** Google / GitHub: the OAuth client secret. Apple: omit and pass
+    /** 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. */
@@ -336,8 +485,8 @@ export declare interface SocialCompleteLoginOptions {
     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. */
+    /** The OIDC nonce `socialBeginLogin` minted. Required for every OIDC
+     * provider; meaningless for providers that return no ID token. */
     readonly expectedNonce?: string;
     /** Apple only: the raw `user` form field. Present on the FIRST authorization
      *  and never again — see `apple.ts`. */
@@ -376,6 +525,18 @@ export declare class SocialExchangeError extends SocialAuthError {
     constructor(code: SocialAuthErrorCode, message: string, status?: number);
 }
 
+export declare interface SocialGuestUpgradeConfig {
+    readonly guest: GuestAuthOptions;
+    /** Reuse the port installed by auth.guest; no automatic backend switch. */
+    readonly service?: (store: DataStore) => GuestAuthService;
+    /** Same-origin application page presenting explicit upgrade confirmation. */
+    readonly confirmationRedirect: string;
+    readonly configForTransaction?: (store: DataStore) => AuthConfig;
+    /** Opt-in promotion for cookie-less game clients through the system browser and a sealed,
+     *  PKCE-bound one-time code. Absent mounts no `/upgrade/native/*` route. */
+    readonly native?: NativeGuestUpgradeConfig;
+}
+
 /**
  * The social-identity table.
  *
@@ -386,6 +547,17 @@ export declare class SocialExchangeError extends SocialAuthError {
  */
 export declare const socialIdentitiesTable: TableLike;
 
+/** The provider account already has an identity row: another login created it
+ *  first (two first sign-ins of one Steam player racing). Read it and use it. */
+export declare class SocialIdentityConflict extends SocialIdentityConflict_base<{
+    readonly provider: string;
+}> {
+}
+
+declare const SocialIdentityConflict_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "SocialIdentityConflict";
+} & Readonly<A>;
+
 /** 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 {
@@ -399,6 +571,14 @@ export declare interface SocialIdentityDataStore {
         }>;
     }): Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
     insert(table: string, row: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
+    /** When present, the identity is recorded with it: the store decides atomically
+     *  which of two concurrent first logins won, also where it enforces no unique. */
+    insertIgnoreWithOutcome?(table: string, row: Readonly<Record<string, unknown>>, options: {
+        readonly conflictColumns: ReadonlyArray<string>;
+    }): Promise<{
+        readonly row: Readonly<Record<string, unknown>>;
+        readonly outcome: 'inserted' | 'ignored';
+    }>;
     update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>> | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
 }
@@ -412,6 +592,11 @@ export declare interface SocialIdentityInput {
     readonly emailVerified: boolean;
 }
 
+/** Verified browser and native identities share the same account-link contract.
+ * Steam uses OpenID/tickets rather than an OAuth authorize-code descriptor; EOS
+ * is a platform login (`eosPlatformLogin`), keyed by the Product User ID. */
+export declare type SocialIdentityProviderId = SocialProviderId | 'steam' | 'eos';
+
 export declare interface SocialIdentityRecord {
     readonly id: string;
     readonly userId: string;
@@ -432,8 +617,9 @@ export declare interface SocialIdentityStore {
     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>;
+    /** Create the link. Fails with {@link SocialIdentityConflict} when the provider
+     *  account already has one — the unique `[provider, providerAccountId]`. */
+    readonly insert: (input: SocialIdentityInput) => Effect.Effect<SocialIdentityRecord, SocialIdentityConflict>;
     /** 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. */
@@ -459,7 +645,8 @@ export declare type SocialLinkDecision =
     readonly kind: 'sign-in';
     readonly userId: string;
 }
-/** No identity, no account with this email — provision a new user. */
+/** No identity, and no account with this email (or no email at all) —
+*  provision a new user. */
 | {
     readonly kind: 'create-user';
 }
@@ -520,14 +707,15 @@ export declare interface SocialLoginHandoff {
 }
 
 /**
- * A verified identity, normalised across the three providers.
+ * A verified identity, normalised across the registered 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;
+    /** A registered provider id, or the id of a platform login (`eos`, a console). */
+    readonly provider: SocialIdentityProviderId | (string & {});
     /** 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. */
@@ -562,7 +750,7 @@ export declare const socialProvider: (id: string, overrides?: SocialEndpointOver
  *  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}. */
+    /** OAuth client secret. Apple uses {@link SocialProviderConfig.appleKey}. */
     readonly clientSecret?: string;
     /** Apple only: Team ID + Key ID + the `.p8` contents. */
     readonly appleKey?: AppleClientSecretKey;
@@ -599,10 +787,10 @@ export declare interface SocialProviderDescriptor {
 }
 
 /** The providers this package ships. */
-export declare type SocialProviderId = 'google' | 'github' | 'apple';
+export declare type SocialProviderId = 'google' | 'github' | 'apple' | 'discord' | 'twitch' | 'microsoft' | 'epic';
 
 /** How the provider hands the callback back to us. Apple POSTs (cross-site,
- *  `form_post`) whenever `name` / `email` scopes are requested; the other two
+ *  `form_post`) whenever `name` / `email` scopes are requested; the others
  *  redirect with a query string. This changes the cookie the state must live
  *  in — see `plugin.ts`. */
 export declare type SocialResponseMode = 'query' | 'form_post';
@@ -614,6 +802,12 @@ export declare interface SocialSignInOk {
     readonly subject: Subject;
     /** Attach this to the response. */
     readonly setCookie: string;
+    /** The same session for a client that presents it in the session header
+     *  instead of a cookie (a game). `expiresAt` is in Unix seconds. */
+    readonly session: {
+        readonly value: string;
+        readonly expiresAt: number;
+    };
     /** A new local user was provisioned by this login. */
     readonly created: boolean;
     /** The identity was attached to a PRE-EXISTING account by policy. */
@@ -663,4 +857,86 @@ export declare class SocialStateMismatchError extends SocialAuthError {
     constructor(message: string);
 }
 
+/** Steam OpenID 2.0 does not use OAuth PKCE. State is server minted and bound
+ * into the exact return_to which Steam signs. Persist this handoff securely. */
+export declare const steamBeginOpenId: (options: {
+    readonly returnTo: string;
+    readonly realm?: string;
+}) => SteamOpenIdHandoff;
+
+/** Direct OP verification plus local atomic replay admission. Unavailable hot
+ * state refuses; memory ports are explicitly refused for a multi-node owner. */
+export declare const steamCompleteOpenId: (options: SteamCompleteOpenIdOptions) => Effect.Effect<SocialProfile, SocialAuthError>;
+
+export declare interface SteamCompleteOpenIdOptions {
+    /** Actual browser callback URL, not a client-supplied asserted return URL. */
+    readonly callbackUrl: string;
+    readonly expectedReturnTo: string;
+    readonly expectedState: string;
+    /** Inject the registry-backed HotStore; there is no private Redis client. */
+    readonly hotStore: HotStoreShape;
+    readonly namespace: string;
+    readonly multiNode?: boolean;
+    readonly maxNonceAgeMs?: number;
+    readonly clockSkewMs?: number;
+    readonly now?: () => number;
+    readonly fetchImpl?: typeof fetch;
+    /** How long Steam may take to answer. Default 5000 ms. */
+    readonly timeoutMs?: number;
+    /** Loopback fixture only; the asserted OP remains pinned to Steam. */
+    readonly verificationUrl?: string;
+}
+
+export declare interface SteamOpenIdHandoff {
+    readonly url: string;
+    readonly state: string;
+    readonly returnTo: string;
+    readonly realm: string;
+}
+
+/**
+ * Steam: the game calls `ISteamUser::GetAuthTicketForWebApi(identity)` and sends
+ * the ticket as hex; the server asks Steam's partner API who it belongs to. The
+ * account id is the player's SteamID64 — also for a family-shared copy, whose
+ * owner is a different account.
+ */
+export declare const steamPlatformLogin: (options?: SteamPlatformLoginOptions) => PlatformLogin;
+
+export declare interface SteamPlatformLoginOptions {
+    /** Steam App ID. Default: `VOLTRO_STEAM_APP_ID`. */
+    readonly appId?: number;
+    /** The identity string the game passes to `GetAuthTicketForWebApi`. Default `voltro`. */
+    readonly identity?: string;
+    /** Steamworks Web API publisher key. Default: `VOLTRO_STEAM_PUBLISHER_KEY`. Never ships to clients. */
+    readonly publisherKey?: string;
+    /** How long Steam may take to answer before the sign-in answers 502. Default 5000 ms. */
+    readonly timeoutMs?: number;
+    /** Sign in players the publisher banned from this app. Default false: they are refused with 403. */
+    readonly allowPublisherBanned?: boolean;
+    /** Test seam — a loopback stand-in for the partner API. */
+    readonly verificationUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+
+export declare interface SteamWebApiTicketOptions {
+    readonly ticket: string;
+    readonly appId: number;
+    readonly identity: string;
+    readonly publisherKey: string;
+    readonly fetchImpl?: typeof fetch;
+    /** How long Steam may take to answer. Default 5000 ms. */
+    readonly timeoutMs?: number;
+    /** Accept a player the publisher banned from this app. Default false. */
+    readonly allowPublisherBanned?: boolean;
+    /** Loopback fixture only. The production verifier is the publisher API. */
+    readonly verificationUrl?: string;
+}
+
+/** Run a platform verifier and sort its failure into refused (401) or unavailable (503). */
+export declare const verifyPlatformTicket: (platform: PlatformLogin, ticket: string) => Promise<PlatformAccount>;
+
+/** Steamworks GetAuthTicketForWebApi hex tickets, verified on the secure
+ * server against the configured app and identity. No supplied SteamID wins. */
+export declare const verifySteamWebApiTicket: (options: SteamWebApiTicketOptions) => Promise<SocialProfile>;
+
 export { }