@playstack/connections

@playstack/connections manages encrypted, refreshable credentials for acting against third-party APIs on behalf of a user, account member, or account.

Install

npm install @playstack/connections @playstack/core @playstack/crypto @playstack/events

Compose providers and storage

import { createConnections } from '@playstack/connections'
import { githubConnectionProvider } from '@playstack/connections/providers/github'

const github = githubConnectionProvider({
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
})

export const connections = createConnections({
  persistence,
  crypto: applicationCrypto,
  events,
  clock,
  ids,
  providers: [github],
  scope: 'account',
  redirectUri: 'https://app.example/api/connections/callback',
  returnUrlOrigins: ['https://app.example'],
})

const { authorizationUrl } = await connections.begin({
  provider: 'github',
  scope: { type: 'account', id: accountId },
  connectedByUserId: userId,
  returnUrl: 'https://app.example/settings/connections',
  scopes: ['repo:read'],
})

OAuth uses PKCE plus a purpose-bound, short-lived, single-use state token. Access and refresh tokens are encrypted before persistence.

Service configuration

The configured scope must match the selected Prisma artifact variant and persistence adapter option.

Provider bridge

interface ConnectionProvider {
  id: string
  capabilities: {
    incrementalScopes: boolean
    refresh: boolean
    revoke: boolean
    rotatingRefreshTokens?: boolean
  }
  authorizationUrl(context: OAuthAuthorizationContext): string
  exchangeCode(code: string, context: OAuthExchangeContext): Promise<TokenSet>
  identify(tokens: TokenSet): Promise<ProviderIdentity>
  refresh?(refreshToken: string): Promise<TokenSet>
  revoke?(tokens: TokenSet): Promise<void>
  validateManual?(credential: string): Promise<ProviderIdentity>
}

Capabilities must describe real provider behavior. The service handles connection state, encryption, scope comparison, refresh concurrency, and lifecycle events; provider drivers own protocol-specific URLs and token exchange.

Provider options

The included driver accepts required clientId and clientSecret, plus optional GitHub Enterprise webBaseUrl and apiBaseUrl, REST apiVersion, userAgent, allowSignup, prompt, injected fetch, and test clock. It supports OAuth App authorization with PKCE and personal access tokens as manual credentials.

@playstack/connections/providers/oauth2 supplies a standards-based authorization-code, PKCE, refresh, client-authentication, and optional RFC 7009 revocation factory. Named drivers configure GitHub, LinkedIn, Mastodon, and X while preserving the native provider instance and injected Fetch boundary.

AT Protocol is intentionally separate. @playstack/atproto retains official discovery, PAR, DPoP, nonce, refresh, and session-store behavior instead of copying its credentials into a conventional OAuth token record.

Crypto and persistence bridges

ConnectionCrypto is structurally compatible with @playstack/crypto. Its sign and verify methods must preserve purpose and single-use semantics. ConnectionsPersistence provides transactional lookup/save and must lock a connection during refresh.

import { prismaConnectionsPersistence } from '@playstack/connections/prisma'

const persistence = prismaConnectionsPersistence(prisma, { scope: 'account' })

Select the matching managed schema variant in playstack.json; it is security-critical and non-ejectable. The CLI composes the matching reverse model extension into a managed owner artifact. When an established schema differs physically, use an application-owned persistence adapter and contract tests rather than importing parallel User or Account models.

Boundary

Connections returns a valid access token; feature code uses the provider’s native SDK directly. The package does not implement login, provider API clients, posting, syndication, or provider-specific UI. Secret sources and provider configuration remain application-owned.

API entry points and requirements

Reference snapshot: @playstack/connections@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.