@rakomi/node 0.0.0 → 0.1.0

package/dist/device.js

@@ -0,0 +1,244 @@
+import { DEVICE_AUTHORIZATION_DENIED, DEVICE_AUTHORIZATION_EXPIRED, DEVICE_AUTHORIZATION_PENDING, DEVICE_AUTHORIZATION_RATE_LIMITED, DEVICE_AUTHORIZATION_SLOW_DOWN, DEVICE_AUTHORIZATION_TIMEOUT, OAUTH_INVALID_CLIENT, OAUTH_INVALID_GRANT, OAUTH_INVALID_REQUEST, OAUTH_MISSING_CLIENT_ID, OAUTH_NETWORK_ERROR, RakomiError, } from './errors.js';
+const DEFAULT_BASE_URL = 'https://api.rakomi.com';
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+const AWAIT_MAX_ITERATIONS = 2000;
+const MAX_POLL_INTERVAL_MS = 60_000;
+/**
+ * POST /oauth/device/code — initiate a device authorization request.
+ */
+export async function startDeviceAuthorization(options) {
+    if (!options.clientId) {
+        return { ok: false, error: OAUTH_MISSING_CLIENT_ID() };
+    }
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const body = new URLSearchParams({ client_id: options.clientId });
+    if (options.clientSecret)
+        body.set('client_secret', options.clientSecret);
+    if (options.scope) {
+        body.set('scope', Array.isArray(options.scope) ? options.scope.join(' ') : options.scope);
+    }
+    if (options.nonce)
+        body.set('nonce', options.nonce);
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/oauth/device/code`, {
+            method: 'POST',
+            redirect: 'error',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : 'Network error';
+        return { ok: false, error: OAUTH_NETWORK_ERROR(detail) };
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        return { ok: false, error: OAUTH_NETWORK_ERROR('Invalid JSON from device-code endpoint') };
+    }
+    if (!response.ok) {
+        return { ok: false, error: mapStartError(json) };
+    }
+    const data = json;
+    if (typeof data.device_code !== 'string' ||
+        typeof data.user_code !== 'string' ||
+        typeof data.verification_uri !== 'string' ||
+        typeof data.verification_uri_complete !== 'string' ||
+        typeof data.expires_in !== 'number' ||
+        typeof data.interval !== 'number') {
+        return { ok: false, error: OAUTH_NETWORK_ERROR('Malformed device authorization response') };
+    }
+    return { ok: true, data: data };
+}
+/**
+ * POST /oauth/token — single poll for a device authorization grant.
+ *
+ * Returns:
+ *   - ok: true → access_token + refresh_token (+ id_token if openid was requested)
+ *   - ok: false, error.code === 'device/authorization_pending' → keep polling
+ *   - ok: false, error.code === 'device/slow_down' → increment interval +5s, keep polling
+ *   - ok: false, error.code === 'device/access_denied' | 'device/expired_token' → stop
+ *   - ok: false, OAuth/network error → stop
+ */
+export async function pollForDeviceToken(options) {
+    if (!options.clientId) {
+        return { ok: false, error: OAUTH_MISSING_CLIENT_ID() };
+    }
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const params = {
+        grant_type: DEVICE_GRANT_TYPE,
+        device_code: options.deviceCode,
+        client_id: options.clientId,
+    };
+    if (options.clientSecret)
+        params.client_secret = options.clientSecret;
+    const body = new URLSearchParams(params);
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/oauth/token`, {
+            method: 'POST',
+            redirect: 'error',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+            signal: options.signal,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : 'Network error';
+        return { ok: false, error: OAUTH_NETWORK_ERROR(detail) };
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        return { ok: false, error: OAUTH_NETWORK_ERROR('Invalid JSON from token endpoint') };
+    }
+    if (!response.ok) {
+        return { ok: false, error: mapPollError(json) };
+    }
+    const data = json;
+    if (typeof data.access_token !== 'string' || typeof data.token_type !== 'string') {
+        return { ok: false, error: OAUTH_NETWORK_ERROR('Invalid token response: missing access_token or token_type') };
+    }
+    return { ok: true, data: json };
+}
+/**
+ * High-level helper: poll the token endpoint at the server-suggested interval
+ * until success, terminal error, timeout, or abort. Honors RFC 8628 §3.5
+ * `slow_down` by incrementing the interval by 5s before the next poll.
+ */
+export async function awaitDeviceTokens(options) {
+    let intervalMs = Math.max(1, options.intervalSeconds) * 1000;
+    const deadline = Date.now() + (options.timeoutMs ?? 30 * 60 * 1000);
+    for (let i = 0; i < AWAIT_MAX_ITERATIONS; i++) {
+        if (options.signal?.aborted) {
+            return { ok: false, error: DEVICE_AUTHORIZATION_TIMEOUT('Polling cancelled by AbortSignal') };
+        }
+        if (Date.now() >= deadline) {
+            return { ok: false, error: DEVICE_AUTHORIZATION_TIMEOUT() };
+        }
+        await sleep(intervalMs, options.signal);
+        if (options.signal?.aborted) {
+            return { ok: false, error: DEVICE_AUTHORIZATION_TIMEOUT('Polling cancelled by AbortSignal') };
+        }
+        const result = await pollForDeviceToken({
+            deviceCode: options.deviceCode,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            baseUrl: options.baseUrl,
+            signal: options.signal,
+        });
+        if (result.ok)
+            return result;
+        if (result.error.code === 'device/authorization_pending')
+            continue;
+        if (result.error.code === 'device/slow_down') {
+            intervalMs = Math.min(intervalMs + 5000, MAX_POLL_INTERVAL_MS);
+            continue;
+        }
+        return result;
+    }
+    return { ok: false, error: DEVICE_AUTHORIZATION_TIMEOUT('Exceeded maximum polling iterations') };
+}
+/**
+ * One-shot device flow: initiate, surface the code via `onCode`, poll until
+ * tokens are issued. Returns the same VerifyResult as awaitDeviceTokens.
+ *
+ * Copy-paste recipe for CLIs and AI agents.
+ */
+export async function run(options) {
+    const issued = await startDeviceAuthorization({
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        scope: options.scope,
+        nonce: options.nonce,
+        baseUrl: options.baseUrl,
+    });
+    if (!issued.ok)
+        return { ok: false, error: issued.error };
+    try {
+        await options.onCode(issued.data);
+    }
+    catch (err) {
+        if (err instanceof RakomiError) {
+            return {
+                ok: false,
+                error: { code: err.code, message: err.message, suggestion: err.suggestion, docs_url: err.docs_url },
+            };
+        }
+        const detail = err instanceof Error ? err.message : 'onCode handler threw';
+        return { ok: false, error: OAUTH_NETWORK_ERROR(detail) };
+    }
+    return awaitDeviceTokens({
+        deviceCode: issued.data.device_code,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        intervalSeconds: issued.data.interval,
+        timeoutMs: options.timeoutMs ?? issued.data.expires_in * 1000,
+        baseUrl: options.baseUrl,
+        signal: options.signal,
+    });
+}
+function mapStartError(json) {
+    const errorBody = json;
+    const errorCode = typeof errorBody.error === 'string' ? errorBody.error : 'unknown';
+    const errorDescription = typeof errorBody.error_description === 'string' ? errorBody.error_description : undefined;
+    switch (errorCode) {
+        case 'invalid_client':
+            return OAUTH_INVALID_CLIENT(errorDescription);
+        case 'unauthorized_client':
+            return OAUTH_INVALID_CLIENT(errorDescription || 'Client is not authorized for the device_code grant');
+        case 'invalid_request':
+            return OAUTH_INVALID_REQUEST(errorDescription);
+        case 'invalid_scope':
+            return OAUTH_INVALID_REQUEST(errorDescription || 'Requested scope is not allowed for this client');
+        case 'slow_down':
+            return DEVICE_AUTHORIZATION_RATE_LIMITED(errorDescription);
+        default:
+            return OAUTH_INVALID_REQUEST(errorDescription || `device-code endpoint error: ${errorCode}`);
+    }
+}
+function mapPollError(json) {
+    const errorBody = json;
+    const errorCode = typeof errorBody.error === 'string' ? errorBody.error : 'unknown';
+    const errorDescription = typeof errorBody.error_description === 'string' ? errorBody.error_description : undefined;
+    switch (errorCode) {
+        case 'authorization_pending':
+            return DEVICE_AUTHORIZATION_PENDING(errorDescription);
+        case 'slow_down':
+            return DEVICE_AUTHORIZATION_SLOW_DOWN(errorDescription);
+        case 'access_denied':
+            return DEVICE_AUTHORIZATION_DENIED(errorDescription);
+        case 'expired_token':
+            return DEVICE_AUTHORIZATION_EXPIRED(errorDescription);
+        case 'invalid_grant':
+            return OAUTH_INVALID_GRANT(errorDescription);
+        case 'invalid_client':
+        case 'unauthorized_client':
+            return OAUTH_INVALID_CLIENT(errorDescription);
+        default:
+            return OAUTH_INVALID_REQUEST(errorDescription || `token endpoint error: ${errorCode}`);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/doctor.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export interface CheckResult {
+    name: string;
+    passed: boolean;
+    detail: string;
+}
+export declare function getSdkVersion(): string;
+export declare function checkApiReachability(baseUrl: string): Promise<CheckResult>;
+export declare function checkJwks(baseUrl: string): Promise<CheckResult>;
+export declare function checkTokenVerification(baseUrl: string, apiKey: string): Promise<CheckResult>;
+export declare function computeExitCode(results: CheckResult[]): number;

package/dist/doctor.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+export function getSdkVersion() {
+    const dir = fileURLToPath(new URL('.', import.meta.url));
+    const pkgPath = resolve(dir, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+}
+export async function checkApiReachability(baseUrl) {
+    const url = `${baseUrl}/v1/health`;
+    const start = Date.now();
+    try {
+        const res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(10_000) });
+        const latency = Date.now() - start;
+        if (res.ok) {
+            return { name: 'API reachable', passed: true, detail: `${url} (${latency}ms)` };
+        }
+        return { name: 'API reachable', passed: false, detail: `HTTP ${String(res.status)} from ${url}` };
+    }
+    catch (err) {
+        return {
+            name: 'API reachable',
+            passed: false,
+            detail: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+export async function checkJwks(baseUrl) {
+    const url = `${baseUrl}/.well-known/jwks.json`;
+    try {
+        const res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(10_000) });
+        if (!res.ok) {
+            return { name: 'JWKS available', passed: false, detail: `HTTP ${String(res.status)} from ${url}` };
+        }
+        const data = (await res.json());
+        if (!Array.isArray(data.keys)) {
+            return { name: 'JWKS available', passed: false, detail: 'Response missing keys array' };
+        }
+        return {
+            name: 'JWKS available',
+            passed: true,
+            detail: `${String(data.keys.length)} key(s) found`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'JWKS available',
+            passed: false,
+            detail: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+const TOKEN_ERROR_PREFIX = 'token/';
+export async function checkTokenVerification(baseUrl, apiKey) {
+    try {
+        const { RakomiClient } = await import('./client.js');
+        const ca = new RakomiClient({ apiKey, baseUrl });
+        const result = await Promise.race([
+            ca.verifyToken('test'),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Token verification timed out after 10s')), 10_000)),
+        ]);
+        if (!result.ok) {
+            if (result.error.code.startsWith(TOKEN_ERROR_PREFIX)) {
+                return {
+                    name: 'Token verification',
+                    passed: true,
+                    detail: `${result.error.code} (expected — no real token provided)`,
+                };
+            }
+            return {
+                name: 'Token verification',
+                passed: false,
+                detail: `${result.error.code}: ${result.error.message}`,
+            };
+        }
+        return { name: 'Token verification', passed: true, detail: 'SDK initialized correctly' };
+    }
+    catch (err) {
+        return {
+            name: 'Token verification',
+            passed: false,
+            detail: err instanceof Error ? err.message : 'SDK initialization failed',
+        };
+    }
+}
+export function computeExitCode(results) {
+    return results.every((r) => r.passed) ? 0 : 1;
+}
+function formatResult(result) {
+    const icon = result.passed ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+    return `  ${icon} ${result.name}: ${result.detail}`;
+}
+function parseArgs(args) {
+    let baseUrl = 'https://api.rakomi.com';
+    let apiKey = 'ca_test_doctor_check';
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--base-url' && args[i + 1]) {
+            baseUrl = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--api-key' && args[i + 1]) {
+            apiKey = args[i + 1];
+            i++;
+        }
+    }
+    return { baseUrl, apiKey };
+}
+async function main() {
+    const { baseUrl, apiKey } = parseArgs(process.argv.slice(2));
+    const version = getSdkVersion();
+    process.stdout.write(`\n${BOLD}@rakomi/node Doctor v${version}${RESET}\n`);
+    process.stdout.write('================================\n\n');
+    const results = [];
+    results.push({ name: 'SDK version', passed: true, detail: version });
+    process.stdout.write(formatResult(results[results.length - 1]) + '\n');
+    results.push(await checkApiReachability(baseUrl));
+    process.stdout.write(formatResult(results[results.length - 1]) + '\n');
+    results.push(await checkJwks(baseUrl));
+    process.stdout.write(formatResult(results[results.length - 1]) + '\n');
+    results.push(await checkTokenVerification(baseUrl, apiKey));
+    process.stdout.write(formatResult(results[results.length - 1]) + '\n');
+    const passedCount = results.filter((r) => r.passed).length;
+    process.stdout.write(`\n${String(passedCount)}/${String(results.length)} checks passed\n\n`);
+    process.exitCode = computeExitCode(results);
+}
+main().catch((err) => {
+    process.stderr.write(`Doctor failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/dpop-session.d.ts

@@ -0,0 +1,90 @@
+import { type DpopProver } from './dpop.js';
+/** Reason a DPoP-requested session was downgraded to Bearer by the server. */
+export interface DpopDowngradeInfo {
+    /** The server returned `token_type: "Bearer"` for a session that presented a DPoP proof. */
+    reason: 'server_returned_bearer';
+}
+/** Options for {@link createDpopSession} / the {@link DpopSession} constructor. */
+export interface CreateDpopSessionOptions {
+    /**
+     * Base URL of the Rakomi API (e.g. `https://api.rakomi.com`). Used to build
+     * the canonical `htu` of the DPoP proof. MUST match the host the refresh call
+     * targets, or the server rejects the proof (`htu` mismatch, RFC 9449 §4.3).
+     */
+    baseUrl: string;
+    /**
+     * Pinned proof algorithm. Defaults to `ES256` — the cross-port baseline
+     * (universally available; Apple Secure-Enclave-eligible). `EdDSA` is
+     * `@rakomi/node`-only. The `alg` is NEVER derived from a key or any input.
+     */
+    alg?: 'ES256' | 'EdDSA';
+    /**
+     * Invoked at most once if the server downgrades a DPoP-requested session to
+     * `Bearer` (security-downgrade detector). The session does NOT become bound.
+     * No secret material (proof / key / jwk / jti) is ever passed to this hook.
+     */
+    onDowngrade?: (info: DpopDowngradeInfo) => void;
+}
+/**
+ * Opaque, session-scoped DPoP binding handle. Create ONE per logged-in session,
+ * pass it to `exchangeCode({..., dpop })` AND every `refreshToken({..., dpop })`
+ * for that session. Never share an instance across distinct sessions or across
+ * a refresh token boundary.
+ *
+ * @public — additive-only after the first public release (a removed/renamed member
+ * is a MAJOR bump). The options-bag shape leaves room for a future rotation hook
+ * to be appended additively.
+ */
+export declare class DpopSession {
+    private prover;
+    private readonly onDowngrade?;
+    private readonly baseUrl;
+    private readonly alg;
+    private _bound;
+    private _downgraded;
+    private _downgradeNotified;
+    private _boundJkt;
+    private _inflightRotation;
+    constructor(options: CreateDpopSessionOptions);
+    /**
+     * `true` once the server has confirmed (`token_type === "DPoP"`) that this
+     * session's key is sender-bound. The SDK attaches a refresh proof IFF this is
+     * `true`. Starts `false`; set by observing issuance/refresh responses.
+     */
+    get isBound(): boolean;
+    /**
+     * `true` if a session that presented a DPoP proof was returned as `Bearer` by
+     * the server (a security downgrade — flag off / server-side downgrade). The
+     * session is NOT bound in this state and attaches no further proofs.
+     */
+    get isDowngraded(): boolean;
+    /**
+     * The committed RFC 7638 thumbprint (`jkt`) of the session keypair, available
+     * once the session is bound. Lets the SDK cross-check that the bound
+     * thumbprint matches the refresh-time key (a `jkt`-continuity self-check).
+     */
+    get boundJkt(): string | undefined;
+    resolveProof(htm: string, path: string, opts?: {
+        nonce?: string;
+    }): Promise<string>;
+    jktHint(): Promise<string>;
+    resolveRotationProofs(htm: string, path: string, opts?: {
+        nonce?: string;
+        incoming?: DpopProver;
+    }): Promise<{
+        oldProof: string;
+        newProof: string;
+        incoming: DpopProver;
+        newJkt: string;
+    }>;
+    commitRotation(incoming: DpopProver): Promise<boolean>;
+    runExclusiveRotation<T>(fn: () => Promise<T>): Promise<T>;
+    observeTokenType(tokenType: string | undefined, attachedProof: boolean): Promise<void>;
+}
+/**
+ * Factory for a {@link DpopSession}. Equivalent to `new DpopSession(options)` —
+ * provided for parity with the functional `createDpopProver` API.
+ *
+ * @public — additive-only after the first public release.
+ */
+export declare function createDpopSession(options: CreateDpopSessionOptions): DpopSession;

package/dist/dpop-session.js

@@ -0,0 +1,127 @@
+import { createDpopProver } from './dpop.js';
+/**
+ * Opaque, session-scoped DPoP binding handle. Create ONE per logged-in session,
+ * pass it to `exchangeCode({..., dpop })` AND every `refreshToken({..., dpop })`
+ * for that session. Never share an instance across distinct sessions or across
+ * a refresh token boundary.
+ *
+ * @public — additive-only after the first public release (a removed/renamed member
+ * is a MAJOR bump). The options-bag shape leaves room for a future rotation hook
+ * to be appended additively.
+ */
+export class DpopSession {
+    prover;
+    onDowngrade;
+    baseUrl;
+    alg;
+    _bound = false;
+    _downgraded = false;
+    _downgradeNotified = false;
+    _boundJkt;
+    _inflightRotation = null;
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.alg = options.alg;
+        this.prover = createDpopProver({
+            baseUrl: options.baseUrl,
+            ...(options.alg !== undefined ? { alg: options.alg } : {}),
+        });
+        this.onDowngrade = options.onDowngrade;
+    }
+    /**
+     * `true` once the server has confirmed (`token_type === "DPoP"`) that this
+     * session's key is sender-bound. The SDK attaches a refresh proof IFF this is
+     * `true`. Starts `false`; set by observing issuance/refresh responses.
+     */
+    get isBound() {
+        return this._bound;
+    }
+    /**
+     * `true` if a session that presented a DPoP proof was returned as `Bearer` by
+     * the server (a security downgrade — flag off / server-side downgrade). The
+     * session is NOT bound in this state and attaches no further proofs.
+     */
+    get isDowngraded() {
+        return this._downgraded;
+    }
+    /**
+     * The committed RFC 7638 thumbprint (`jkt`) of the session keypair, available
+     * once the session is bound. Lets the SDK cross-check that the bound
+     * thumbprint matches the refresh-time key (a `jkt`-continuity self-check).
+     */
+    get boundJkt() {
+        return this._boundJkt;
+    }
+    async resolveProof(htm, path, opts) {
+        return this.prover.proof(htm, path, opts);
+    }
+    async jktHint() {
+        return this.prover.jktHint();
+    }
+    async resolveRotationProofs(htm, path, opts) {
+        const incoming = opts?.incoming ??
+            createDpopProver({
+                baseUrl: this.baseUrl,
+                ...(this.alg !== undefined ? { alg: this.alg } : {}),
+            });
+        const proofOpts = opts?.nonce !== undefined ? { nonce: opts.nonce } : undefined;
+        const [oldProof, newProof, newJkt] = await Promise.all([
+            this.prover.proof(htm, path, proofOpts),
+            incoming.proof(htm, path, proofOpts),
+            incoming.jktHint(),
+        ]);
+        return { oldProof, newProof, incoming, newJkt };
+    }
+    async commitRotation(incoming) {
+        const outgoingJkt = await this.prover.jktHint();
+        if (this._boundJkt !== undefined && this._boundJkt !== outgoingJkt) {
+            return false;
+        }
+        const incomingJkt = await incoming.jktHint();
+        this.prover = incoming;
+        this._bound = true;
+        this._downgraded = false;
+        this._boundJkt = incomingJkt;
+        return true;
+    }
+    async runExclusiveRotation(fn) {
+        if (this._inflightRotation !== null) {
+            return this._inflightRotation;
+        }
+        const promise = fn();
+        this._inflightRotation = promise;
+        try {
+            return await promise;
+        }
+        finally {
+            this._inflightRotation = null;
+        }
+    }
+    async observeTokenType(tokenType, attachedProof) {
+        if (tokenType === 'DPoP') {
+            this._bound = true;
+            this._downgraded = false;
+            if (this._boundJkt === undefined) {
+                this._boundJkt = await this.prover.jktHint();
+            }
+            return;
+        }
+        this._bound = false;
+        if (attachedProof) {
+            this._downgraded = true;
+            if (!this._downgradeNotified) {
+                this._downgradeNotified = true;
+                this.onDowngrade?.({ reason: 'server_returned_bearer' });
+            }
+        }
+    }
+}
+/**
+ * Factory for a {@link DpopSession}. Equivalent to `new DpopSession(options)` —
+ * provided for parity with the functional `createDpopProver` API.
+ *
+ * @public — additive-only after the first public release.
+ */
+export function createDpopSession(options) {
+    return new DpopSession(options);
+}

package/dist/dpop.d.ts

@@ -0,0 +1,24 @@
+declare const DPOP_PROOF_ALLOWED_ALGS: readonly ["ES256", "EdDSA"];
+type DpopProofAlg = (typeof DPOP_PROOF_ALLOWED_ALGS)[number];
+export interface DpopProver {
+    /**
+     * Build a DPoP-proof JWT for `htm` + `path`. Resolves to the compact-
+     * serialized proof string to set on the `DPoP` HTTP header. When
+     * `accessToken` is provided, adds the `ath` claim (RFC 9449 §4.3 — REQUIRED
+     * on resource-server calls). `nonce` is optional (RFC 9449 §8 nonce
+     * challenge response). The proof is signed with the SDK instance's
+     * ephemeral keypair (generated lazily on first call).
+     */
+    proof(htm: string, path: string, options?: {
+        accessToken?: string;
+        nonce?: string;
+    }): Promise<string>;
+    /** SHA-256 thumbprint of the ephemeral public JWK (RFC 7638). */
+    jktHint(): Promise<string>;
+}
+export interface CreateDpopProverOptions {
+    baseUrl: string;
+    alg?: DpopProofAlg;
+}
+export declare function createDpopProver(options: CreateDpopProverOptions): DpopProver;
+export {};

package/dist/dpop.js

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { calculateJwkThumbprint, exportJWK, generateKeyPair, SignJWT, } from 'jose';
+import { canonicalizeUrl } from './internal/canonical-url.js';
+const DPOP_PROOF_ALLOWED_ALGS = ['ES256', 'EdDSA'];
+export function createDpopProver(options) {
+    const alg = options.alg ?? DPOP_PROOF_ALLOWED_ALGS[0];
+    const baseUrl = options.baseUrl.endsWith('/') ? options.baseUrl.slice(0, -1) : options.baseUrl;
+    let statePromise = null;
+    async function getState() {
+        if (!statePromise) {
+            statePromise = (async () => {
+                const { privateKey, publicKey } = await generateKeyPair(alg, {
+                    ...(alg === 'EdDSA' ? { crv: 'Ed25519' } : {}),
+                    extractable: false,
+                });
+                const publicJwk = await exportJWK(publicKey);
+                const jkt = await calculateJwkThumbprint(publicJwk, 'sha256');
+                return { privateKey, publicJwk, alg, jkt };
+            })();
+        }
+        return statePromise;
+    }
+    return {
+        async proof(htm, path, opts) {
+            const state = await getState();
+            const sanitizedPath = path.split('?')[0].split('#')[0];
+            const htu = canonicalizeUrl(`${baseUrl}${sanitizedPath}`);
+            const payload = {
+                htm,
+                htu,
+                iat: Math.floor(Date.now() / 1000),
+                jti: randomUUID(),
+                ...(opts?.accessToken !== undefined && {
+                    ath: createHash('sha256').update(opts.accessToken, 'utf8').digest('base64url'),
+                }),
+                ...(opts?.nonce !== undefined && { nonce: opts.nonce }),
+            };
+            return new SignJWT(payload)
+                .setProtectedHeader({
+                typ: 'dpop+jwt',
+                alg: state.alg,
+                jwk: state.publicJwk,
+            })
+                .sign(state.privateKey);
+        },
+        async jktHint() {
+            const state = await getState();
+            return state.jkt;
+        },
+    };
+}