@vouchington/utils 0.7.4 → 0.8.0

package/README.md

@@ -36,6 +36,10 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   request/acknowledge round trip with an injected message type and acceptance check, and a named
   Web Lock wrapper. Request actions, expected state transitions, and the bind/clear/reconcile
   sequence stay in the application.
+- `service-worker-activation`: `waitForActiveServiceWorker(registration, options)` resolves when
+  the registration has an active worker. An installing or waiting worker is preferred over
+  `serviceWorker.ready`. `timeoutMs` bounds the wait; omit it to wait without a deadline. The
+  caller supplies the timeout and may inject `serviceWorker` (default `navigator.serviceWorker`).
 - `json-ld`: schema.org JSON-LD builders (organization, website, navigation, collection, thing,
   comparison, item list, breadcrumb, profile) and script-safe serialization. Callers inject the
   absolute-URL resolver and site name; product schemas such as posts stay in the application.
@@ -74,6 +78,21 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 - `http-signatures`: Node-only (`node:crypto`) Cavage-12 HTTP Signatures. Callers pass signed
   headers, allowed algorithms, and `maxAgeSeconds` on both sign and verify. The package has no
   default header set or product keyId policy.
+- `oauth-pkce`: WebCrypto `generateCodeVerifier`, `generateState`, and S256 `generateCodeChallenge`.
+- `oauth-popup` (browser): `openOAuthPopup`, `buildAuthorizationUrl`, `runPopupOAuthLogin`, and
+  `OAuthCancelledError`. The flow takes an injectable `window`; callers keep their own in-flight
+  guard and map the code, PKCE verifier, and redirect URI to their token shape.
+- `oidc-id-token`: Node-only (`node:crypto`) RS256 ID-token verifier with an injected `fetch`, JWKS
+  URI, issuers, and audiences. It caches the JWKS with a TTL, refreshes once on a `kid` miss, checks
+  `iat` skew and an optional (hashed) nonce, and throws `OidcVerificationError` with a `code`.
+  `googleProfileFromClaims` and `appleProfileFromClaims` map claims to a profile; account policy
+  and HTTP error mapping stay in the application.
+- `oauth-providers`: authorization-code redemption for GitHub, X, LinkedIn, Microsoft, Google, and Facebook. Each
+  provider's `redeem(input, { fetch, signal, now })` returns `{ tokens, profile }`; `verifiedEmail`
+  follows each provider's own rule. Microsoft Graph `mail` is not proof of ownership, so it is
+  only reported as verified with `trustMailAsVerified: true`. Credentials, tenant, and the egress-guarded `fetch` are
+  injected; failures throw `OAuthProviderError` (`provider`, `kind`, `status`). Persistence and
+  HTTP error mapping stay in the application.
 - `collections`, `async`, and `stable-json`: collection deduplication/merging, bounded async mapping,
   and deterministic JSON serialization.
 - `feature-flags`: base64 JSON feature-flag cookie parsing and serialization with caller-injected
@@ -126,6 +145,15 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   URL-only and credential-only passes are exported separately, and `composeBeforeSend` accepts
   either `ScrubOptions` or a final scrubber function. This package has no product defaults.
 
+- `error-tree`: `formatErrorTree(error, { maxDepth?, maxNested? })` renders an error with its
+  `errors[]` and `cause` chain, marks circular references, and reports how many nested errors the
+  depth and count limits omitted (defaults 5 and 20).
+- `job-data-scrub`: `scrubJobData(data, options?)`, a safe-scalar allowlist scrubber for queue job
+  payloads. Only booleans, numbers, UUID/ULID ids, and short slug-like strings survive; sensitive
+  keys redact regardless of value. The redaction marker (default `'[Filtered]'`), key substring and
+  exact-name lists, and depth/array/key limits are options, and the defaults list only generic keys.
+  It complements the key-based `observability` scrubbers.
+
 ```ts
 const money = createMoneyCatalog([{ code: 'credit', minorUnitExponent: 2 }] as const, 6)
 money.parseMajorUnitsToMoney('12.34', 'credit')

package/dist/error-tree.d.mts

@@ -0,0 +1,8 @@
+export interface FormatErrorTreeOptions {
+    /** Deepest nesting level rendered; deeper errors are counted as omitted. Default 5. */
+    maxDepth?: number;
+    /** Total nested errors rendered across the tree. Default 20. */
+    maxNested?: number;
+}
+/** Formats an error and its nested `errors[]` and `cause` chain without util.format's shallow output. */
+export declare function formatErrorTree(error: unknown, options?: FormatErrorTreeOptions): string;

package/dist/error-tree.mjs

@@ -0,0 +1,94 @@
+import { inspect } from 'node:util';
+/** Formats an error and its nested `errors[]` and `cause` chain without util.format's shallow output. */
+export function formatErrorTree(error, options = {}) {
+    const maxDepth = options.maxDepth ?? 5;
+    const maxNested = options.maxNested ?? 20;
+    const seen = new Set();
+    // Nodes visited only while counting omitted subtrees; kept apart from `seen` so a hidden
+    // occurrence never turns a later visible occurrence into `[circular]`.
+    const omittedSeen = new Set();
+    let nestedCount = 0;
+    let omittedCount = 0;
+    const render = (value, depth, label) => {
+        if (isObject(value)) {
+            if (seen.has(value))
+                return indentLines('[circular]', depth, label);
+            seen.add(value);
+        }
+        const lines = indentLines(formatValue(value), depth, label);
+        for (const child of getChildren(value)) {
+            if (depth >= maxDepth || nestedCount >= maxNested) {
+                omittedCount += countOmitted(child.value, seen, omittedSeen);
+            }
+            else {
+                nestedCount += 1;
+                lines.push(...render(child.value, depth + 1, child.label));
+            }
+        }
+        return lines;
+    };
+    const lines = render(error, 0);
+    if (omittedCount > 0)
+        lines.push(`… ${omittedCount} more nested errors omitted`);
+    return lines.join('\n');
+}
+function formatValue(value) {
+    if (!(value instanceof Error))
+        return inspect(withoutChildren(value), { depth: 2 });
+    if (typeof value.stack === 'string' && value.stack.length > 0)
+        return value.stack;
+    return `${value.name || 'Error'}: ${value.message}`;
+}
+// Child errors are traversed separately under the limits, so inspect must not print them too.
+function withoutChildren(value) {
+    if (!isObject(value) || Array.isArray(value) || getChildren(value).length === 0)
+        return value;
+    const copy = { ...value };
+    if (Array.isArray(copy.errors))
+        delete copy.errors;
+    if (copy.cause !== undefined)
+        delete copy.cause;
+    return copy;
+}
+function getChildren(value) {
+    if (!isObject(value))
+        return [];
+    const children = [];
+    const properties = value;
+    const errors = properties.errors;
+    if (Array.isArray(errors)) {
+        errors.forEach((nested, index) => children.push({ label: `errors[${index}]:`, value: nested }));
+    }
+    if (properties.cause !== undefined)
+        children.push({ label: 'cause:', value: properties.cause });
+    return children;
+}
+function countOmitted(value, seen, omittedSeen) {
+    const pending = [value];
+    let count = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (isObject(current)) {
+            if (seen.has(current) || omittedSeen.has(current)) {
+                count += 1;
+                continue;
+            }
+            omittedSeen.add(current);
+        }
+        count += 1;
+        const children = getChildren(current);
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            pending.push(children[index].value);
+        }
+    }
+    return count;
+}
+function indentLines(value, depth, label) {
+    const indentation = '  '.repeat(depth);
+    return value
+        .split(/\r?\n/)
+        .map((line, index) => `${indentation}${index === 0 && label ? `${label} ` : ''}${line}`);
+}
+function isObject(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}

package/dist/job-data-scrub.d.mts

@@ -0,0 +1,21 @@
+export interface JobDataScrubOptions {
+    /** Replacement for redacted values. Default `'[Filtered]'`. */
+    redacted?: string;
+    /** Normalized (lowercase alphanumeric) key substrings that always redact. Default: generic PII/secret terms. */
+    sensitiveSubstrings?: readonly string[];
+    /** Normalized key names that redact only on an exact match. Default: none. */
+    sensitiveNames?: readonly string[];
+    /** Nesting depth at which containers are redacted. Default 4. */
+    maxDepth?: number;
+    /** Array items kept before a `...N more` marker. Default 10. */
+    maxArrayItems?: number;
+    /** Sorted object keys kept. Default 32. */
+    maxKeys?: number;
+}
+export declare const DEFAULT_SENSITIVE_SUBSTRINGS: readonly string[];
+/**
+ * Safe-scalar allowlist scrubber for queue job payloads. Values default to redacted: only booleans,
+ * numbers, UUID/ULID ids, and short slug-like strings survive, and sensitive key names redact
+ * regardless of value. Plain non-empty objects produce output; anything else yields undefined.
+ */
+export declare function scrubJobData(data: unknown, options?: JobDataScrubOptions): Record<string, unknown> | undefined;

package/dist/job-data-scrub.mjs

@@ -0,0 +1,83 @@
+export const DEFAULT_SENSITIVE_SUBSTRINGS = [
+    'email',
+    'phone',
+    'address',
+    'token',
+    'secret',
+    'password',
+    'passwd',
+    'credential',
+    'sessionid',
+    'ssn',
+    'creditcard',
+    'cardnumber',
+    'cvv',
+    'dob',
+    'birthdate',
+];
+const SAFE_SCALAR_STRING = /^[a-z][a-z0-9_-]{0,63}$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * Safe-scalar allowlist scrubber for queue job payloads. Values default to redacted: only booleans,
+ * numbers, UUID/ULID ids, and short slug-like strings survive, and sensitive key names redact
+ * regardless of value. Plain non-empty objects produce output; anything else yields undefined.
+ */
+export function scrubJobData(data, options = {}) {
+    if (data == null || typeof data !== 'object' || Array.isArray(data))
+        return undefined;
+    if (Object.keys(data).length === 0)
+        return undefined;
+    const resolved = {
+        redacted: options.redacted ?? '[Filtered]',
+        sensitiveSubstrings: options.sensitiveSubstrings ?? DEFAULT_SENSITIVE_SUBSTRINGS,
+        sensitiveNames: options.sensitiveNames ?? [],
+        maxDepth: options.maxDepth ?? 4,
+        maxArrayItems: options.maxArrayItems ?? 10,
+        maxKeys: options.maxKeys ?? 32,
+    };
+    return scrubObject(data, 0, resolved);
+}
+function scrubValue(value, depth, o) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return value;
+    if (typeof value === 'string')
+        return scrubString(value, o);
+    if (Array.isArray(value))
+        return scrubArray(value, depth, o);
+    if (typeof value === 'object')
+        return scrubObject(value, depth, o);
+    return o.redacted;
+}
+function scrubString(value, o) {
+    if (UUID_PATTERN.test(value) || ULID_PATTERN.test(value))
+        return value;
+    return SAFE_SCALAR_STRING.test(value) ? value : o.redacted;
+}
+function scrubArray(value, depth, o) {
+    if (depth >= o.maxDepth)
+        return o.redacted;
+    const items = value.slice(0, o.maxArrayItems).map((item) => scrubValue(item, depth + 1, o));
+    if (value.length > o.maxArrayItems)
+        items.push(`...${value.length - o.maxArrayItems} more`);
+    return items;
+}
+function scrubObject(value, depth, o) {
+    if (depth >= o.maxDepth)
+        return o.redacted;
+    // fromEntries defines own properties, so a JSON `__proto__` key cannot hit the prototype setter.
+    return Object.fromEntries(Object.keys(value)
+        .toSorted()
+        .slice(0, o.maxKeys)
+        .map((key) => [
+        key,
+        isSensitiveKey(key, o) ? o.redacted : scrubValue(value[key], depth + 1, o),
+    ]));
+}
+function isSensitiveKey(key, o) {
+    const normalized = key.toLowerCase().replaceAll(/[^a-z0-9]/g, '');
+    return (o.sensitiveNames.includes(normalized) ||
+        o.sensitiveSubstrings.some((substring) => normalized.includes(substring)));
+}

package/dist/oauth-pkce.d.mts

@@ -0,0 +1,6 @@
+/** 32 random bytes, base64url without padding (43 characters). */
+export declare function generateCodeVerifier(): string;
+/** 16 random bytes as 32 lowercase hex characters. */
+export declare function generateState(): string;
+/** RFC 7636 S256 code challenge for a verifier. */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;

package/dist/oauth-pkce.mjs

@@ -0,0 +1,19 @@
+function base64Url(bytes) {
+    return btoa(String.fromCodePoint(...bytes))
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replaceAll('=', '');
+}
+/** 32 random bytes, base64url without padding (43 characters). */
+export function generateCodeVerifier() {
+    return base64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/** 16 random bytes as 32 lowercase hex characters. */
+export function generateState() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** RFC 7636 S256 code challenge for a verifier. */
+export async function generateCodeChallenge(verifier) {
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64Url(new Uint8Array(hash));
+}

package/dist/oauth-popup.d.mts

@@ -0,0 +1,80 @@
+export declare class OAuthCancelledError extends Error {
+    constructor(providerLabel: string, reason?: string);
+}
+export interface OAuthPopupHandle {
+    readonly closed: boolean;
+    location: {
+        href: string;
+    };
+    close(): void;
+}
+export interface OAuthPopupMessageEvent {
+    readonly origin: string;
+    readonly source: unknown;
+    readonly data?: {
+        provider?: string;
+        code?: string;
+        state?: string;
+    } | null;
+}
+/** The slice of `window` the popup flow uses; injectable for tests and non-DOM hosts. */
+export interface OAuthPopupWindow {
+    readonly location: {
+        readonly origin: string;
+    };
+    open(url: string, name: string, features: string): OAuthPopupHandle | null;
+    addEventListener(type: 'message', listener: (event: OAuthPopupMessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: OAuthPopupMessageEvent) => void): void;
+    setInterval(callback: () => void, ms: number): number;
+    clearInterval(id: number): void;
+}
+export interface OpenOAuthPopupOptions {
+    authUrl: URL | string;
+    popupName: string;
+    provider: string;
+    providerLabel: string;
+    state: string;
+    /** Defaults to `width=600,height=700`. */
+    features?: string;
+    /** Popup-closed poll interval; defaults to 500. */
+    pollMs?: number;
+    /** Defaults to `globalThis.window`. */
+    window?: OAuthPopupWindow;
+}
+/** Resolves with the authorization code posted back by the same-origin popup. */
+export declare function openOAuthPopup(options: OpenOAuthPopupOptions): Promise<{
+    code: string;
+}>;
+export interface BuildAuthorizationUrlOptions {
+    authUrl: string | URL;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    responseType?: string;
+    responseMode?: string;
+    /** Adds `code_challenge` and `code_challenge_method=S256` when set. */
+    codeChallenge?: string;
+}
+export declare function buildAuthorizationUrl(options: BuildAuthorizationUrlOptions): URL;
+export interface PopupOAuthLoginConfig<T> {
+    clientId: string;
+    authUrl: string | (() => string);
+    callbackPath: string;
+    popupName: string;
+    provider: string;
+    providerLabel: string;
+    scope: string;
+    responseType?: string;
+    responseMode?: string;
+    pkce?: boolean;
+    mapResult(result: {
+        code: string;
+        codeVerifier?: string;
+        redirectUri: string;
+    }): T;
+    /** Defaults to `globalThis.window`. */
+    window?: OAuthPopupWindow;
+}
+/** Generates state (and PKCE), opens the popup, and maps the redeemed code. No in-flight guard. */
+export declare function runPopupOAuthLogin<T>(config: PopupOAuthLoginConfig<T>): Promise<T>;

package/dist/oauth-popup.mjs

@@ -0,0 +1,106 @@
+import { generateCodeChallenge, generateCodeVerifier, generateState } from './oauth-pkce.mjs';
+export class OAuthCancelledError extends Error {
+    constructor(providerLabel, reason) {
+        super(reason ?? `${providerLabel} login cancelled`);
+        this.name = 'OAuthCancelledError';
+    }
+}
+function defaultWindow() {
+    return globalThis.window;
+}
+const DEFAULT_FEATURES = 'width=600,height=700';
+function openPopup(win, url, name, features, providerLabel) {
+    const popup = win.open(url, name, features);
+    if (!popup)
+        throw new OAuthCancelledError(providerLabel, 'Popup blocked');
+    return popup;
+}
+/** Resolves with the authorization code posted back by the same-origin popup. */
+export function openOAuthPopup(options) {
+    const win = options.window ?? defaultWindow();
+    try {
+        const popup = openPopup(win, options.authUrl.toString(), options.popupName, options.features ?? DEFAULT_FEATURES, options.providerLabel);
+        return awaitPopupCode(win, popup, options);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+function awaitPopupCode(win, popup, options) {
+    const { provider, providerLabel, state } = options;
+    return new Promise((resolve, reject) => {
+        const finish = (callback) => {
+            win.clearInterval(checkClosed);
+            win.removeEventListener('message', handleMessage);
+            callback();
+        };
+        const handleMessage = (event) => {
+            if (event.origin !== win.location.origin)
+                return;
+            if (event.source !== popup)
+                return;
+            if (event.data?.provider !== provider)
+                return;
+            const { code } = event.data;
+            if (code && event.data.state === state) {
+                finish(() => resolve({ code }));
+                return;
+            }
+            finish(() => reject(new OAuthCancelledError(providerLabel)));
+        };
+        win.addEventListener('message', handleMessage);
+        const checkClosed = win.setInterval(() => {
+            if (popup.closed)
+                finish(() => reject(new OAuthCancelledError(providerLabel)));
+        }, options.pollMs ?? 500);
+    });
+}
+export function buildAuthorizationUrl(options) {
+    const url = new URL(options.authUrl);
+    const params = url.searchParams;
+    if (options.responseType)
+        params.set('response_type', options.responseType);
+    params.set('client_id', options.clientId);
+    params.set('redirect_uri', options.redirectUri);
+    params.set('scope', options.scope);
+    params.set('state', options.state);
+    if (options.responseMode)
+        params.set('response_mode', options.responseMode);
+    if (options.codeChallenge) {
+        params.set('code_challenge', options.codeChallenge);
+        params.set('code_challenge_method', 'S256');
+    }
+    return url;
+}
+/** Generates state (and PKCE), opens the popup, and maps the redeemed code. No in-flight guard. */
+export async function runPopupOAuthLogin(config) {
+    const win = config.window ?? defaultWindow();
+    // Open before any await: browsers only allow window.open inside the user-gesture call stack.
+    const popup = openPopup(win, 'about:blank', config.popupName, DEFAULT_FEATURES, config.providerLabel);
+    const state = generateState();
+    const redirectUri = `${win.location.origin}${config.callbackPath}`;
+    const codeVerifier = config.pkce ? generateCodeVerifier() : undefined;
+    try {
+        const codeChallenge = codeVerifier ? await generateCodeChallenge(codeVerifier) : undefined;
+        popup.location.href = buildAuthorizationUrl({
+            authUrl: typeof config.authUrl === 'function' ? config.authUrl() : config.authUrl,
+            clientId: config.clientId,
+            redirectUri,
+            scope: config.scope,
+            state,
+            ...(config.responseType ? { responseType: config.responseType } : {}),
+            ...(config.responseMode ? { responseMode: config.responseMode } : {}),
+            ...(codeChallenge ? { codeChallenge } : {}),
+        }).toString();
+    }
+    catch (error) {
+        popup.close();
+        throw error;
+    }
+    const { code } = await awaitPopupCode(win, popup, {
+        provider: config.provider,
+        providerLabel: config.providerLabel,
+        state,
+    });
+    return config.mapResult({ code, ...(codeVerifier ? { codeVerifier } : {}), redirectUri });
+}

package/dist/oauth-providers-core.d.mts

@@ -0,0 +1,44 @@
+import type { OAuthFetch, OAuthProfile } from './oauth-types.mts';
+export interface OAuthCallContext {
+    fetch: OAuthFetch;
+    signal?: AbortSignal;
+    /** Epoch milliseconds; defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    accessTokenExpiresAt?: Date;
+}
+export interface AuthorizationCodeInput {
+    code: string;
+    redirectUri: string;
+    codeVerifier?: string;
+}
+export type OAuthProviderErrorKind = 'http' | 'provider_error' | 'malformed';
+export declare class OAuthProviderError extends Error {
+    readonly provider: string;
+    readonly kind: OAuthProviderErrorKind;
+    readonly status?: number;
+    constructor(provider: string, kind: OAuthProviderErrorKind, message: string, status?: number);
+}
+export interface OAuthProvider {
+    id: string;
+    redeem(input: AuthorizationCodeInput, ctx: OAuthCallContext): Promise<{
+        tokens: OAuthTokens;
+        profile: OAuthProfile;
+    }>;
+}
+export declare function nowOf(ctx: OAuthCallContext): () => number;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** A non-empty string, otherwise undefined. */
+export declare function str(value: unknown): string | undefined;
+/** Drops undefined values so profile data only holds what the provider returned. */
+export declare function compact(values: Record<string, unknown>): Record<string, unknown>;
+export declare function asRecord(provider: string, value: unknown, label: string): Record<string, unknown>;
+export declare function requireCodeVerifier(provider: string, input: AuthorizationCodeInput): string;
+export declare function formBody(values: Record<string, string | undefined>): string;
+/** Fetches JSON through the injected transport; non-2xx and unparsable bodies throw. */
+export declare function requestJson(provider: string, label: string, ctx: OAuthCallContext, url: string, init?: RequestInit): Promise<unknown>;
+/** Validates a token endpoint payload: `error` bodies and a missing access token throw. */
+export declare function parseTokens(provider: string, payload: unknown, now: () => number): OAuthTokens;

package/dist/oauth-providers-core.mjs

@@ -0,0 +1,88 @@
+export class OAuthProviderError extends Error {
+    provider;
+    kind;
+    status;
+    constructor(provider, kind, message, status) {
+        super(message);
+        this.name = 'OAuthProviderError';
+        this.provider = provider;
+        this.kind = kind;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+export function nowOf(ctx) {
+    return ctx.now ?? Date.now;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A non-empty string, otherwise undefined. */
+export function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Drops undefined values so profile data only holds what the provider returned. */
+export function compact(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}
+export function asRecord(provider, value, label) {
+    if (isRecord(value))
+        return value;
+    throw new OAuthProviderError(provider, 'malformed', `${label} is not an object`);
+}
+export function requireCodeVerifier(provider, input) {
+    if (input.codeVerifier)
+        return input.codeVerifier;
+    throw new OAuthProviderError(provider, 'malformed', 'A PKCE code verifier is required');
+}
+export function formBody(values) {
+    return new URLSearchParams(compact(values)).toString();
+}
+/** Fetches JSON through the injected transport; non-2xx and unparsable bodies throw. */
+export async function requestJson(provider, label, ctx, url, init = {}) {
+    // Token and profile requests carry credentials; never follow a redirect with them.
+    const response = await ctx.fetch(url, {
+        ...init,
+        redirect: 'error',
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+    });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new OAuthProviderError(provider, 'http', `${label} failed: ${response.status}`, response.status);
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new OAuthProviderError(provider, 'malformed', `${label} returned invalid JSON`);
+    }
+}
+function tokenErrorMessage(body) {
+    const { error } = body;
+    if (!error)
+        return undefined;
+    if (typeof error === 'string')
+        return str(body.error_description) ?? error;
+    return isRecord(error) ? (str(error.message) ?? 'Unknown error') : 'Unknown error';
+}
+/** Validates a token endpoint payload: `error` bodies and a missing access token throw. */
+export function parseTokens(provider, payload, now) {
+    const body = asRecord(provider, payload, 'Token response');
+    const message = tokenErrorMessage(body);
+    if (message) {
+        throw new OAuthProviderError(provider, 'provider_error', `Token exchange failed: ${message}`);
+    }
+    const accessToken = str(body.access_token);
+    if (!accessToken) {
+        throw new OAuthProviderError(provider, 'malformed', 'Token response is missing access_token');
+    }
+    const refreshToken = str(body.refresh_token);
+    const expiresIn = body.expires_in;
+    return {
+        accessToken,
+        ...(refreshToken ? { refreshToken } : {}),
+        ...(typeof expiresIn === 'number' && expiresIn > 0
+            ? { accessTokenExpiresAt: new Date(now() + expiresIn * 1000) }
+            : {}),
+    };
+}

package/dist/oauth-providers-facebook.d.mts

@@ -0,0 +1,9 @@
+import { type OAuthProvider } from './oauth-providers-core.mts';
+export interface FacebookProviderConfig {
+    appId: string;
+    appSecret: string;
+    /** Graph API version path segment, for example `v1.0`. */
+    graphVersion: string;
+}
+/** Code exchange, then `fb_exchange_token` for a long-lived token, then `/me`. */
+export declare function facebookProvider(config: FacebookProviderConfig): OAuthProvider;

package/dist/oauth-providers-facebook.mjs

@@ -0,0 +1,27 @@
+import { OAuthProviderError, asRecord, formBody, nowOf, parseTokens, requestJson, str, } from './oauth-providers-core.mjs';
+/** Code exchange, then `fb_exchange_token` for a long-lived token, then `/me`. */
+export function facebookProvider(config) {
+    const graph = `https://graph.facebook.com/${config.graphVersion}`;
+    const form = (values) => ({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: formBody({ client_id: config.appId, client_secret: config.appSecret, ...values }),
+    });
+    return {
+        id: 'facebook',
+        async redeem(input, ctx) {
+            const now = nowOf(ctx);
+            const shortLived = parseTokens('facebook', await requestJson('facebook', 'Facebook authorization code exchange', ctx, `${graph}/oauth/access_token`, form({ redirect_uri: input.redirectUri, code: input.code })), now);
+            const tokens = parseTokens('facebook', await requestJson('facebook', 'Facebook token exchange', ctx, `${graph}/oauth/access_token`, form({ grant_type: 'fb_exchange_token', fb_exchange_token: shortLived.accessToken })), now);
+            const mePayload = await requestJson('facebook', 'Facebook /me request', ctx, `${graph}/me?fields=name,email`, { headers: { Authorization: `Bearer ${tokens.accessToken}` } });
+            const me = asRecord('facebook', mePayload, 'Facebook /me response');
+            const id = str(me.id);
+            if (!id)
+                throw new OAuthProviderError('facebook', 'malformed', 'Facebook user is missing id');
+            return {
+                tokens,
+                profile: { providerUserId: id, verifiedEmail: str(me.email) ?? null, data: me },
+            };
+        },
+    };
+}

package/dist/oauth-providers-github.d.mts

@@ -0,0 +1,7 @@
+import { type OAuthProvider } from './oauth-providers-core.mts';
+export interface GithubProviderConfig {
+    clientId: string;
+    clientSecret: string;
+}
+/** JSON token exchange; the verified email is the primary verified address from `/user/emails`. */
+export declare function githubProvider(config: GithubProviderConfig): OAuthProvider;