@softwareshaker/auth-client

Shared authentication client for SoftwareShaker applications.

Installation

npm install @softwareshaker/auth-client

Entry points

• @softwareshaker/auth-client provides application-access token helpers and shared types.
• @softwareshaker/auth-client/react provides the Better Auth React client and impersonation banner.
• @softwareshaker/auth-client/server provides the server-side OAuth and application-access flow.

The clientSecret and jwtSecret options belong exclusively in server-side code. Never expose them through browser environment variables or client bundles.

Server-side renewal

The server flow requests offline_access and keeps OAuth credentials in secure, HTTP-only cookies. The auth server and registered OAuth client must allow the refresh_token grant. Existing sessions receive these cookies after their next sign-in.

requireFirstPartyAppAccess renews expired application tokens before returning an authorized result, so the original request body remains available to the application's action. The auth server still checks the underlying session and current application assignment when issuing a replacement token.

Forward every Set-Cookie header from authorized results, as well as redirect and forbidden results, to the browser. Use request-scoped server state or middleware to share the result across loaders and actions. Never serialize these headers into page data. Preserve cookie deletions made by logout or organization switching over earlier renewal cookies.

If issuing an application token fails after OAuth credentials have rotated, AppAccessRequestError.headers carries the replacement cookies. Forward those headers on the error response so the next request can retry with the current credentials.

Concurrent OAuth refreshes are deduplicated within one server process, with successful results retained for 30 seconds to cover overlapping requests. Deployments with multiple processes must serialize refreshes for each session across those processes or use a provider with refresh-token reuse handling before enabling renewal across replicas.