@playstack/client-auth

@playstack/client-auth is the runtime-neutral public-client half of Playstack’s authorization-code profile. It never embeds a client secret or owns the application’s login, MFA, SSO, or consent interface.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/client-auth@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose a client

import {
  createClientAuth,
  createFetchTokenTransport,
} from '@playstack/client-auth'

const auth = createClientAuth({
  clientId: 'desktop-app',
  authorizationEndpoint: 'https://app.example.com/oauth/authorize',
  redirectUri,
  scopes: ['profile', 'devices'],
  transport: createFetchTokenTransport({
    tokenEndpoint: 'https://api.example.com/oauth/token',
    revocationEndpoint: 'https://api.example.com/oauth/revoke',
  }),
  storage: platformCredentialStorage,
  launcher: systemBrowserLauncher,
})

await auth.authorize()
const response = await auth.request(request, apiTransport)
await auth.signOut()

Every attempt generates S256 PKCE material and callback state. Completion verifies the returned state before exchanging the code. Access credentials refresh before expiry, concurrent refreshes share one operation inside the configured coordinator, and an authenticated request retries once after an unauthorized response. A failed refresh clears stored credentials; sign-out attempts remote revocation and always clears local state.

Configuration and bridges

@playstack/client-auth/loopback is Node-only. It binds 127.0.0.1 on an ephemeral port, accepts one callback, times out, and closes immediately. Browser extensions should use @playstack/extension for their launcher, credential storage, and cross-context refresh lock.

Boundary

The package does not register clients, authorize a user, host an OAuth route, choose a keychain, or host device authorization endpoints. Those server boundaries live in @playstack/auth and @playstack/nest-auth; the host supplies secure storage and browser-launch behavior.

Device authorization is available

@playstack/client-auth/device exports beginDeviceAuthorization(): supply a reviewed transport, display the returned user code/verification URL, then explicitly call waitForTokens(). Polling observes slow-down, expiry, cancellation and classified connection timeouts. It does not expose the device code/verifier or introduce a second refresh algorithm.

Server grants use @playstack/auth/device; the transport validates token responses and forwards AbortSignal. Successful issuance remains one-time. A lost committed response requires new consent. OS storage and multi-process refresh coordination are yours to verify in the application.

API entry points and requirements

Reference snapshot: @playstack/client-auth@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

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

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.