@hameddk/oauth-toolkit

Provider-agnostic OAuth 2.0 client toolkit for Node.js.

• Authorization Code flow — both PKCE-only public clients and confidential clients with client_secret
• Token refresh with proactive, promise-coalesced background refresh
• Pluggable storage adapter — caller controls persistence and encryption
• State store with TTL + auto-cleanup to prevent leaks from abandoned flows
• Refresh failures expose requiresReauth — toolkit never auto-deletes your storage
• No DB, no filesystem, no provider knowledge baked in
• Zero dependencies, ESM, Node ≥ 18

Status: 0.1.0 — early. Public API is stable for the documented surface.

Install

npm install @hameddk/oauth-toolkit

Quick start

Below are two parallel examples wiring up an imaginary acme-oauth provider: one PKCE-only (no secret), one confidential (with secret, no PKCE). Real providers (your IdP, GitHub, Google, ...) follow the same shape.

Flow A — Authorization Code + PKCE (no client secret)

import { createOAuthClient } from '@hameddk/oauth-toolkit';

const client = createOAuthClient({
  provider: {
    name: 'acme',
    authorizationUrl: 'https://auth.acme.example/oauth/authorize',
    tokenUrl: 'https://auth.acme.example/oauth/token',
    scopes: ['read:profile', 'write:items'],
    pkce: true,                       // S256 code_challenge + code_verifier
    tokenEndpointAuth: 'none',        // public client — no secret
    tokenEndpointFormat: 'form',
  },
  clientId: process.env.ACME_CLIENT_ID,
  redirectUri: 'http://localhost:3000/auth/acme/callback',
  storage,                            // see "Storage adapter" below
});

const { url, state } = await client.getAuthorizationUrl();
// → open `url` in browser; user is redirected back to redirectUri with ?code=...&state=...

await client.exchangeCodeForTokens(code, state);

const accessToken = await client.getValidAccessToken();

Flow B — Authorization Code + client_secret (no PKCE)

import { createOAuthClient } from '@hameddk/oauth-toolkit';

const client = createOAuthClient({
  provider: {
    name: 'acme',
    authorizationUrl: 'https://auth.acme.example/oauth/authorize',
    tokenUrl: 'https://auth.acme.example/oauth/token',
    scopes: ['read:profile', 'write:items'],
    pkce: false,
    tokenEndpointAuth: 'basic',       // Authorization: Basic base64(id:secret)
    tokenEndpointFormat: 'form',
  },
  clientId: process.env.ACME_CLIENT_ID,
  clientSecret: process.env.ACME_CLIENT_SECRET,
  redirectUri: 'http://localhost:3000/auth/acme/callback',
  storage,
});

const { url, state } = await client.getAuthorizationUrl();
await client.exchangeCodeForTokens(code, state);
const accessToken = await client.getValidAccessToken();

PKCE and client_secret are not mutually exclusive — some providers require both. Set pkce: true and tokenEndpointAuth: 'body' (or 'basic') together.

Public API

const client = createOAuthClient(options);

await client.getAuthorizationUrl();              // → { url, state }
await client.exchangeCodeForTokens(code, state); // → { access_token, expires_at, raw }
await client.getValidAccessToken();              // → string | null   (refreshes if needed)
await client.refreshAccessToken();               // → string          (force; throws on fail)
await client.ensureTokenFresh();                 // → void            (proactive, coalesced)
await client.getConnectionStatus();              // → { status, expires_at, updated_at }
await client.disconnect();                       // → void

Provider configuration

| Field | Type | Default | Notes | |---|---|---|---| | name | string | — | Storage key. Must be unique per provider. | | authorizationUrl | string | — | OAuth authorize endpoint. | | tokenUrl | string \| { exchange, refresh } | — | OAuth token endpoint(s). See tokenUrl forms below. | | scopes | string \| string[] | — | Joined with scopeSeparator if array. | | scopeSeparator | string | ' ' | Some providers use ','. | | pkce | boolean | false | Enable S256 PKCE. | | tokenEndpointAuth | 'body' \| 'basic' \| 'none' | 'body' | See below. | | tokenEndpointFormat | 'form' \| 'json' | 'form' | Body encoding. | | extraAuthParams | Record<string,string> | — | Extra query params on the authorize URL (e.g. audience, prompt). | | parseTokenResponse | (data) => { access_token, refresh_token?, expires_in? } | — | Override for non-standard responses (e.g. tokens nested under authed_user). |

tokenUrl forms

Most providers use a single token endpoint for both authorization-code exchange and refresh-token grants. Pass it as a string:

provider: {
  tokenUrl: 'https://auth.acme.example/oauth/token',
  // ...
}

A few providers split the two operations across distinct URLs (for example, when the user-token exchange has different scope semantics than the standard refresh endpoint). Pass an object with both URLs in that case:

provider: {
  tokenUrl: {
    exchange: 'https://auth.acme.example/oauth/user.access',  // code → tokens
    refresh:  'https://auth.acme.example/oauth/access',       // refresh_token grant
  },
  // ...
}

Both URLs are validated at client construction. Use the string form when in doubt — the object form exists specifically for providers with split token endpoints.

tokenEndpointAuth

| Mode | What's sent | |---|---| | 'body' | client_id (+ client_secret if supplied) in the body. | | 'basic' | Authorization: Basic base64(client_id:client_secret) header. | | 'none' | No client auth — typically PKCE-only public clients. |

Storage adapter

interface StorageAdapter {
  load(provider: string): Promise<StoredTokens | null>;
  save(provider: string, tokens: StoredTokens): Promise<void>;
  delete(provider: string): Promise<void>;
}

interface StoredTokens {
  access_token: string;       // plain — adapter encrypts at rest
  refresh_token?: string;     // plain
  expires_at: number;         // Unix seconds (UTC)
  updated_at?: number;        // Unix seconds, set by adapter on save
}

The toolkit hands you plaintext tokens. Encrypt them in your adapter. For example, wrap @hameddk/secret-storage to get AES-256-GCM at rest, then persist to whatever you like (SQLite, Postgres, file, KV).

In-memory example:

const map = new Map();
const storage = {
  async load(provider) {
    return map.get(provider) ?? null;
  },
  async save(provider, tokens) {
    map.set(provider, { ...tokens, updated_at: Math.floor(Date.now() / 1000) });
  },
  async delete(provider) {
    map.delete(provider);
  },
};

Lazy credentials

clientId and clientSecret accept a function (sync or async). The resolver is called every time the toolkit needs the value — no internal caching. Cache on your side if the lookup is expensive.

const client = createOAuthClient({
  ...,
  clientId: () => credentialsStore.get('acme_client_id'),
  clientSecret: async () => secretsManager.get('acme_client_secret'),
});

If a resolver throws, the toolkit wraps the error in OAuthConfigError and preserves the original cause via the standard cause property.

Dynamic redirect URIs

redirectUri accepts a function — re-evaluated on each getAuthorizationUrl() call. Useful with tunnels (ngrok, cloudflared) where the public URL changes:

redirectUri: () => `${getActiveTunnelUrl() ?? 'http://localhost:3000'}/auth/acme/callback`,

Refresh policy

| Method | When it refreshes | Coalescing | |---|---|---| | getValidAccessToken() | If expiring within refreshLeadTimeSec (default 5 min). | Shared with refreshAccessToken() and ensureTokenFresh(). | | ensureTokenFresh() | If expiring within proactiveRefreshThresholdSec (default 35 min). Errors go to onRefreshError. | Shared. | | refreshAccessToken() | Always. Throws on failure. | Shared. |

Concurrent calls to any of these methods all observe the same in-flight refresh — only one network request per refresh window per provider.

requiresReauth semantics

When a refresh fails with HTTP 400 or 401, the toolkit throws an OAuthRefreshError with requiresReauth: true. This is your signal to surface a reconnect UX to the user.

The toolkit never auto-deletes your storage. The decision to clear stored tokens belongs to the caller — log first, prompt the user, or keep the row for audit. Call disconnect() when you're ready.

try {
  await client.refreshAccessToken();
} catch (err) {
  if (err.requiresReauth) {
    // 400/401 — refresh_token revoked or expired
    showReconnectBanner();
  } else {
    // 5xx, network — likely transient
    scheduleRetry();
  }
}

If the provider rotates the refresh token, the toolkit saves the new value via storage.save(). If the response omits refresh_token, the previous one is preserved.

State TTL

Pending OAuth flows (PKCE code_verifier + redirectUri, keyed by state) are held in an in-memory map with a TTL of 10 minutes by default (configurable via options.stateTtlMs). Expired entries are pruned on every read/write — no timers, no memory leak from abandoned redirects.

After a successful or failed exchangeCodeForTokens(), the state entry is always cleared — it cannot be reused.

Errors

import {
  OAuthError,                  // base
  OAuthConfigError,            // missing/invalid config, resolver threw
  OAuthStateError,             // unknown or expired state on callback
  OAuthTokenExchangeError,     // code → token failed (status, body)
  OAuthRefreshError,           // refresh_token grant failed (status, body, requiresReauth)
} from '@hameddk/oauth-toolkit';

Errors carry the provider's response body (when available) but never echo your client_secret, code_verifier, or refresh_token — those are sent in the request, not the response.

Testing hooks

For testing only:

options: {
  fetch: customFetch,   // override fetch implementation
  now: () => 1234567890_000,  // override clock (returns Unix ms)
}

These exist so you can write deterministic tests without monkey-patching globals or installing fake-timers. Do not use them in production code.

Security considerations

Read these before deploying.

1. Plaintext tokens cross the storage-adapter boundary

The toolkit hands your StorageAdapter.save() plaintext access_token and refresh_token strings. Encryption at rest is the adapter's responsibility. A common pattern is to wrap @hameddk/secret-storage (AES-256-GCM, zero deps) inside save/load so plaintext only exists in memory at the moment of use:

import { encrypt, decrypt } from '@hameddk/secret-storage';

const storage = {
  async load(name) {
    const row = await db.get('SELECT * FROM oauth_tokens WHERE provider = ?', name);
    if (!row) return null;
    return {
      access_token: decrypt(row.access_token),
      refresh_token: row.refresh_token ? decrypt(row.refresh_token) : null,
      expires_at: row.expires_at,
    };
  },
  async save(name, t) {
    await db.run(
      'INSERT OR REPLACE INTO oauth_tokens (provider, access_token, refresh_token, expires_at) VALUES (?, ?, ?, ?)',
      name,
      encrypt(t.access_token),
      t.refresh_token ? encrypt(t.refresh_token) : null,
      t.expires_at,
    );
  },
  async delete(name) {
    await db.run('DELETE FROM oauth_tokens WHERE provider = ?', name);
  },
};

2. Pending-flow state is in-memory (single-instance only in v0.1)

Between getAuthorizationUrl() and exchangeCodeForTokens(), the toolkit holds the PKCE code_verifier and the resolved redirectUri in an in-memory Map, keyed by state, with a 10-minute TTL.

This means multi-instance deployments are not supported in v0.1. If the authorize call hits one server and the callback hits another, the second server has no code_verifier and the exchange will throw OAuthStateError. Single-instance use cases (Electron desktop apps, single-process backends, sticky-session deployments) are fine.

A future version may add a pluggable stateStore adapter for multi-instance deployments. Open an issue if you need this.

3. requiresReauth is a signal, not an action

When a refresh fails with HTTP 400 or 401, OAuthRefreshError.requiresReauth is true. This indicates the refresh_token has been revoked, expired, or otherwise invalidated by the provider. The toolkit does not auto-delete your storage — that decision belongs to the caller, who knows whether to log first, retain rows for audit, or prompt the user immediately.

Typical handling:

try {
  const token = await client.getValidAccessToken();
  // ...
} catch (err) {
  if (err instanceof OAuthRefreshError && err.requiresReauth) {
    // Surface a "Reconnect" UX to the user.
    // Optionally call client.disconnect() once you've recorded the event.
  }
}

getValidAccessToken() returns null (rather than throwing) on refresh failure so application code can branch on a single null check; check getConnectionStatus() for the detailed state.

What this library does not do

• Doesn't know about specific providers (no Atlassian, GitHub, etc.). You bring URLs and scopes.
• Doesn't render callback HTML or own your HTTP routing — your framework does.
• Doesn't fetch user profile / "account summary" data — provider-specific.
• Doesn't encrypt tokens — your storage adapter does.
• Doesn't auto-delete storage on auth failures — caller decides cleanup.

License

MIT © 2026 Hamed Sattari