@lastshotlabs/slingshot-oauth

npm install @lastshotlabs/slingshot-oauth

Functions

`buildConnectionClient`

function buildConnectionClient(providerKey: string, config: ConnectionProviderConfig,): ConnectionOAuthClient

Source: packages/slingshot-oauth/src/connections.ts

`createConnectionsRouter`

Builds the connections router. Mounted by createOAuthPlugin only when a connections option is configured.

function createConnectionsRouter(app: object, options: ConnectionsOptions, runtime: AuthRuntimeContext, postRedirect: string,): void

Source: packages/slingshot-oauth/src/connections.ts

`createOAuthPlugin`

Creates the Slingshot social OAuth login plugin.

Automatically mounts OAuth login, callback, and account-link routes for every provider configured in slingshot-auth (auth.oauth.providers). If no providers are configured, the plugin is a no-op and mounts no routes.

Mounted routes (one set per provider, e.g. github):

POST /auth/:provider - redirect to the provider’s auth page
GET /auth/:provider/callback - handle the OAuth callback
POST /auth/oauth/exchange - exchange a one-time code for a session token
POST /auth/:provider/link - initiate provider linking for the signed-in user
DELETE /auth/:provider/link - disconnect a social provider from the account
POST /auth/:provider/reauth - re-authenticate before unlink (if MFA required)
POST /auth/oauth/:provider/reauth/confirm - confirm re-authentication

Public OAuth login initiation, provider linking, and OAuth re-auth initiation all use POST routes so the standard CSRF middleware can protect cookie-authenticated browsers and anonymous login boundaries. Legacy GET /auth/:provider, GET /auth/:provider/link, and GET /auth/:provider/reauth initiators are not mounted.

Remarks: Requires slingshot-auth to be registered first (listed in dependencies).

Remarks: When no OAuth providers are configured in slingshot-auth (auth.oauth.providers is empty or absent), setupRoutes returns immediately without mounting any routes. Any attempt to reach an OAuth route will result in a 404 from the underlying router - the plugin does not mount 501 stubs in this case.

function createOAuthPlugin(options?: OAuthPluginOptions): SlingshotPlugin

Source: packages/slingshot-oauth/src/plugin.ts

`createOAuthRouter`

Creates the Hono router that serves all social OAuth login routes.

Mounts the following routes for each entry in providers:

POST /auth/:provider — redirect to provider auth page
GET /auth/oauth/:provider/callback — handle the OAuth callback
POST /auth/oauth/exchange — exchange one-time code → session token
POST /auth/oauth/:provider/unlink — disconnect social provider from account
POST /auth/oauth/:provider/reauth — initiate re-auth before unlink
POST /auth/oauth/:provider/reauth/confirm — confirm re-auth

Actual mounted provider paths use /auth/:provider for login initiation, callbacks, linking, unlinking, and re-auth initiation. The /auth/oauth/* prefix is only used for the one-time code exchange and re-auth confirmation endpoints.

On successful login the user is redirected to postLoginRedirect with a code query parameter. The client must then POST /auth/oauth/exchange to convert the code into a session token (avoids tokens in redirect URLs).

Session-bound provider linking, unlinking, and OAuth re-auth routes also fail closed with 403 when the account is suspended or when required email verification is no longer satisfied. This keeps stale sessions from mutating linked-identity state or minting new re-auth proofs.

Remarks: This function is called internally by createOAuthPlugin. Call it directly only when composing a custom plugin.

function createOAuthRouter(providers: string[], postLoginRedirect: string, runtime: AuthRuntimeContext, rateLimit?: import('@lastshotlabs/slingshot-auth').AuthRateLimitConfig,): void

Config Fields

Field	Description
`code`	TOTP code, email OTP code, or recovery code.
`method`	Verification method to use.
`password`	Account password.
`reauthToken`	Reauth challenge token (required for emailOtp and webauthn methods).
`webauthnResponse`	WebAuthn assertion response (required for webauthn method).

Source: packages/slingshot-oauth/src/routes/oauth.ts

`getConnectionAccessToken`

Returns a valid access token for the user’s provider connection, transparently refreshing (and persisting the rotation) when expired or inside the refresh window. Returns null when the user has no connection or the refresh fails terminally (revoked consent).

async function getConnectionAccessToken(app: object, userId: string, provider: string,): Promise<ConnectionAccessToken | null>

Source: packages/slingshot-oauth/src/connections.ts

`getProviderConnection`

The user’s stored connection (sanitized — never includes tokens).

async function getProviderConnection(app: object, userId: string, provider: string,): Promise<ProviderConnectionSummary | null>

Source: packages/slingshot-oauth/src/connections.ts

`oauthPluginConfigSchema`

Source: packages/slingshot-oauth/src/plugin.ts

`verifyAppleIdentityToken`

Verify a Sign in with Apple identity token before trusting identity claims.

Arctic’s decodeIdToken() only parses the JWT. Apple requires signature, algorithm, issuer, audience, expiry, issued-at, subject, and nonce validation.

async function verifyAppleIdentityToken(idToken: string, clientId: string, expectedNonce: string, key: AppleVerificationKey = appleJwks,): Promise<AppleIdentityClaims>

Source: packages/slingshot-oauth/src/lib/appleIdentityToken.ts

Interfaces

`AppleIdentityClaims`

Source: packages/slingshot-oauth/src/lib/appleIdentityToken.ts

`ConnectionAccessToken`

Token payload returned by getConnectionAccessToken.

Source: packages/slingshot-oauth/src/connections.ts

`ConnectionOAuthClient`

Normalized OAuth client for a connection provider. Arctic’s per-provider classes differ in PKCE arity; this interface papers over that so the routes and the refresh helper stay provider-agnostic. createClient in the provider config is the escape hatch for providers arctic lacks.

Source: packages/slingshot-oauth/src/connections.ts

`ConnectionProviderConfig`

Source: packages/slingshot-oauth/src/connections.ts

`ConnectionsOptions`

Source: packages/slingshot-oauth/src/connections.ts

`ProviderConnectionSummary`

Sanitized connection projection — safe for HTTP responses (no tokens).

Source: packages/slingshot-oauth/src/connections.ts

Types

`OAuthPluginConfig`

Canonical configuration name for createOAuthPlugin.

Source: packages/slingshot-oauth/src/plugin.ts

`OAuthPluginOptions`

Options for createOAuthPlugin.

All fields are optional - the plugin works out of the box with defaults.

Source: packages/slingshot-oauth/src/plugin.ts