@xkova/sdk 0.1.0-alpha.1

package/dist/member-bff.js

@@ -0,0 +1,1594 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { XKOVAApiError } from './errors.js';
+import { XKOVAClient } from './client.js';
+import { XKOVAMemberResources } from './member-resources.js';
+import { XKOVAMemberActionIntents, } from './member-action-intents.js';
+export { XKOVAMemberIntentError } from './member-action-intents.js';
+import { generateIdempotencyKey } from './idempotency.js';
+import { signXKOVARequest, validateXKOVARequestSigner, xkovaContentDigest, } from './request-signing.js';
+const COMPLETED_AUTHORIZATION_RECOVERY_MS = 5 * 60 * 1000;
+const HOSTED_AUTHORIZATION_MAX_TTL_MS = 10 * 60 * 1000;
+const PROVIDER_ASSERTION_AUTHORIZATION_TTL_MS = 5 * 60 * 1000;
+/**
+ * Marks an authorization failure that makes the exact browser transaction
+ * unusable. BFFs may retire their short-lived flow cookie for this error.
+ * Other failures must preserve the cookie so the durable transaction can be
+ * retried with the same state and XKOVA operation attempt.
+ */
+export class XKOVAMemberAuthorizationTerminalError extends Error {
+    reason;
+    /** BFF-stored, validated review destination. Never copied from callback query parameters. */
+    applicationReviewUri;
+    constructor(reason, message, applicationReviewUri) {
+        super(message);
+        this.name = 'XKOVAMemberAuthorizationTerminalError';
+        this.reason = reason;
+        if (applicationReviewUri !== undefined)
+            this.applicationReviewUri = applicationReviewUri;
+    }
+}
+/**
+ * Keep provider proofs and XKOVA sessions on the server. Your application
+ * handles the provider's sign-in UI and passes the resulting proof here.
+ */
+export class XKOVAMemberBffClient {
+    options;
+    apiBaseUrl;
+    clientFingerprint;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        if (!options.apiKey.startsWith('xkv_')) {
+            throw new TypeError('XKOVA member BFF apiKey must be an XKOVA bearer credential');
+        }
+        if (!/^xkova_pk_(sandbox|production)_[A-Za-z0-9_-]{22,64}$/.test(options.publishableKey)) {
+            throw new TypeError('XKOVA member BFF publishableKey has an invalid shape');
+        }
+        if (options.timeoutMs !== undefined &&
+            (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+            throw new TypeError('XKOVA member BFF timeoutMs must be a positive number');
+        }
+        if (options.requestSigner !== undefined) {
+            validateXKOVARequestSigner(options.requestSigner);
+        }
+        this.apiBaseUrl = normalizeApiBaseUrl(options.baseUrl);
+        this.clientFingerprint = memberBffClientFingerprint({
+            apiBaseUrl: this.apiBaseUrl,
+            apiKey: options.apiKey,
+            publishableKey: options.publishableKey,
+        });
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async issueProofChallenge(input) {
+        const value = await this.postJson('/member-auth/proof/challenges', {
+            origin: input.origin,
+            redirect_uri: input.redirectUri,
+        });
+        const object = requireObject(value, 'proof challenge');
+        const nonce = requireString(object, 'nonce', 'proof challenge');
+        const expiresAt = requireIsoDate(object, 'expires_at', 'proof challenge');
+        return { nonce, expiresAt };
+    }
+    async exchangeProof(proofToken, options) {
+        assertProofToken(proofToken);
+        const attemptId = options.attemptId;
+        assertOperationAttemptId(attemptId);
+        return this.readSessionMaterial(await this.recoverablePostJson('/member-auth/proof/exchange', {
+            attempt_id: attemptId,
+            proof_token: proofToken,
+        }), 'proof exchange');
+    }
+    async refresh(refreshToken, options) {
+        if (refreshToken.length < 20) {
+            throw new TypeError('member refresh token is malformed');
+        }
+        const attemptId = options.attemptId;
+        assertOperationAttemptId(attemptId);
+        return this.readSessionMaterial(await this.recoverablePostJson('/member-auth/refresh', {
+            attempt_id: attemptId,
+            refresh_token: refreshToken,
+        }), 'session refresh');
+    }
+    async getSession(sessionId) {
+        assertUuid(sessionId, 'member session id');
+        const value = await this.getJson('/member-auth/session', sessionId);
+        const object = requireObject(value, 'session status');
+        const returnedSessionId = requireString(object, 'session_id', 'session status');
+        if (returnedSessionId !== sessionId) {
+            throw new Error('XKOVA member session status returned a different session id');
+        }
+        return {
+            sessionId: returnedSessionId,
+            accountHolderId: requireString(object, 'account_holder_id', 'session status'),
+            providerSubject: requireString(object, 'provider_subject', 'session status'),
+            expiresAt: Date.parse(requireIsoDate(object, 'expires_at', 'session status')),
+        };
+    }
+    /** Revokes only the exact XKOVA session named by `sessionId`. */
+    async signOutExactSession(sessionId) {
+        assertUuid(sessionId, 'member session id');
+        await this.postJson('/member-auth/sign-out', { scope: 'session' }, sessionId);
+    }
+    async beginAuthorization(input) {
+        const redirectUri = normalizeCallbackUri(input.redirectUri);
+        const browserOrigin = normalizeBrowserOrigin(input.browserOrigin);
+        const proofBindingMode = input.proofBindingMode ?? 'authorization_nonce';
+        const challenge = proofBindingMode === 'authorization_nonce'
+            ? await this.issueProofChallenge({
+                origin: browserOrigin,
+                redirectUri,
+            })
+            : {
+                nonce: randomBytes(32).toString('base64url'),
+                expiresAt: new Date(Date.now() + PROVIDER_ASSERTION_AUTHORIZATION_TTL_MS).toISOString(),
+            };
+        const state = randomBytes(32).toString('base64url');
+        const codeVerifier = randomBytes(32).toString('base64url');
+        const expiresAt = Date.parse(challenge.expiresAt);
+        await input.transactionStore.put(hashOpaque(state), {
+            status: 'pending',
+            completionMode: 'provider_proof',
+            clientFingerprint: this.clientFingerprint,
+            proofKind: input.proofKind,
+            nonce: challenge.nonce,
+            codeVerifier,
+            redirectUri,
+            exchangeAttemptId: generateXKOVAMemberOperationAttemptId(),
+            sessionReference: randomBytes(32).toString('base64url'),
+            expiresAt,
+        });
+        return {
+            state,
+            nonce: challenge.nonce,
+            codeChallenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+            codeChallengeMethod: 'S256',
+            expiresAt: challenge.expiresAt,
+        };
+    }
+    /**
+     * Persist the transaction before redirecting to Hosted Auth so the callback
+     * can validate state and PKCE and recover the same session after a retry.
+     */
+    async beginHostedAuthorization(input) {
+        const redirectUri = normalizeCallbackUri(input.redirectUri);
+        const browserOrigin = normalizeBrowserOrigin(input.browserOrigin);
+        const state = randomBytes(32).toString('base64url');
+        const codeVerifier = randomBytes(32).toString('base64url');
+        const stateHash = hashOpaque(state);
+        const provisionalExpiresAt = Date.now() + HOSTED_AUTHORIZATION_MAX_TTL_MS;
+        const transaction = {
+            status: 'pending',
+            completionMode: 'hosted_result_code',
+            clientFingerprint: this.clientFingerprint,
+            codeVerifier,
+            redirectUri,
+            exchangeAttemptId: generateXKOVAMemberOperationAttemptId(),
+            sessionReference: randomBytes(32).toString('base64url'),
+            expiresAt: provisionalExpiresAt,
+        };
+        await input.transactionStore.put(stateHash, transaction);
+        try {
+            const value = await this.recoverablePostJson('/member-auth/hosted/authorizations', {
+                origin: browserOrigin,
+                redirect_uri: redirectUri,
+                state,
+                code_challenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+                code_challenge_method: 'S256',
+            });
+            const object = requireObject(value, 'Hosted authorization start');
+            const authorizationUrl = normalizeHostedAuthorizationUrl(requireString(object, 'authorization_url', 'Hosted authorization start'));
+            const { expiresAt, expiresAtMillis } = boundedAuthorizationExpiry(object, provisionalExpiresAt, 'Hosted authorization start');
+            await input.transactionStore.replace(stateHash, {
+                ...transaction,
+                authorizationUrl,
+                expiresAt: expiresAtMillis,
+            });
+            return { authorizationUrl, state, expiresAt };
+        }
+        catch (error) {
+            try {
+                await input.transactionStore.delete(stateHash);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'XKOVA Hosted authorization initiation and local transaction cleanup failed');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Available only to sandbox applications enabled for demo sign-in. The stored
+     * Hosted transaction determines the demo account and callback. An uncertain
+     * response preserves the key so a retry recovers the same reservation.
+     * Complete the returned callback using
+     * completeHostedAuthorization and the original browser flow cookie.
+     */
+    async completeSandboxDemoAuthorization(input) {
+        if (!this.options.apiKey.startsWith('xkv_test_') ||
+            !this.options.publishableKey.startsWith('xkova_pk_sandbox_')) {
+            throw new XKOVAMemberAuthorizationTerminalError('provider_rejected', 'Demo admission requires a sandbox application');
+        }
+        const stateHash = hashOpaque(input.state);
+        return input.transactionStore.runExclusive(stateHash, async () => {
+            const transaction = await input.transactionStore.get(stateHash);
+            if (!transaction || transaction.expiresAt <= Date.now()) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission requires an active Hosted transaction');
+            }
+            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            if (transaction.status !== 'pending' ||
+                transaction.completionMode !== 'hosted_result_code' ||
+                !transaction.authorizationUrl) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission requires a completed Hosted start');
+            }
+            const authorization = new URL(normalizeHostedAuthorizationUrl(transaction.authorizationUrl));
+            const capability = authorization.searchParams.get('transaction');
+            if (!/^\/authorize\/?$/.test(authorization.pathname) ||
+                !capability ||
+                !/^[A-Za-z0-9_-]{43}$/.test(capability)) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission capability is invalid');
+            }
+            const value = await this.postJson('/member-auth/hosted/authorizations/sandbox-demo', { transaction: capability }, undefined, `sandbox-demo-${stateHash}`);
+            const body = requireObject(value, 'Sandbox demo admission');
+            const { expiresAt } = boundedAuthorizationExpiry(body, transaction.expiresAt, 'Sandbox demo admission');
+            const callback = new URL(requireString(body, 'redirect_url', 'Sandbox demo admission'));
+            const code = callback.searchParams.get('code');
+            if (!sameCallback(callback, new URL(transaction.redirectUri)) ||
+                callback.searchParams.getAll('state').length !== 1 ||
+                callback.searchParams.get('state') !== input.state ||
+                callback.searchParams.getAll('code').length !== 1 ||
+                !code ||
+                callback.searchParams.has('error')) {
+                throw new Error('Sandbox demo admission returned the wrong callback binding');
+            }
+            assertHostedAuthorizationResultCode(code);
+            return { callbackUrl: callback.toString(), expiresAt };
+        });
+    }
+    /**
+     * Completes the one-time Hosted Auth result-code exchange and persists the
+     * provider-neutral XKOVA member session. The returned projection is safe for
+     * a browser, but `session` and `reference` remain BFF-only material.
+     */
+    async completeHostedAuthorization(input) {
+        const callback = new URL(input.callbackUrl);
+        const state = callback.searchParams.get('state');
+        if (!state)
+            throw new Error('member Hosted authorization callback is missing state');
+        hashOpaque(input.expectedState);
+        if (!constantTimeStringEqual(state, input.expectedState)) {
+            throw new Error('member Hosted authorization callback state does not match the initiating browser');
+        }
+        const stateHash = hashOpaque(state);
+        return input.transactionStore.runExclusive(stateHash, async () => {
+            const transaction = await input.transactionStore.get(stateHash);
+            if (!transaction || transaction.expiresAt <= Date.now()) {
+                if (transaction)
+                    await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member Hosted authorization transaction is missing, expired, or replayed');
+            }
+            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            if (transaction.completionMode !== 'hosted_result_code') {
+                throw new Error('member authorization transaction is not an XKOVA Hosted Auth flow');
+            }
+            if (!sameCallback(callback, new URL(transaction.redirectUri))) {
+                throw new Error('member Hosted authorization callback does not match its redirect URI');
+            }
+            const hostedError = callback.searchParams.get('error');
+            if (hostedError) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('provider_rejected', 'XKOVA Hosted Auth did not complete authorization');
+            }
+            const code = callback.searchParams.get('code');
+            if (!code) {
+                throw new XKOVAMemberAuthorizationTerminalError('callback_missing_code', 'member Hosted authorization callback is missing code');
+            }
+            assertHostedAuthorizationResultCode(code);
+            const providerCodeHash = hashProviderCode(code);
+            if (transaction.status === 'completed') {
+                if (!constantTimeStringEqual(transaction.providerCodeHash, providerCodeHash)) {
+                    throw new Error('member Hosted authorization callback code changed during retry');
+                }
+                const session = await input.sessionStore.get(transaction.sessionReference);
+                if (!session) {
+                    throw new Error('completed member Hosted authorization references missing application-session material');
+                }
+                return {
+                    reference: transaction.sessionReference,
+                    session,
+                    projection: projectXKOVAMemberSession(session),
+                };
+            }
+            let applicationExpiresAt;
+            let applicationData;
+            if (transaction.stagedApplicationSession) {
+                if (!constantTimeStringEqual(transaction.stagedApplicationSession.authorizationCodeHash, providerCodeHash)) {
+                    throw new Error('member Hosted authorization callback code changed during retry');
+                }
+                applicationExpiresAt = transaction.stagedApplicationSession.applicationExpiresAt;
+                applicationData = transaction.stagedApplicationSession.applicationData;
+            }
+            else {
+                const applicationSessionSeconds = input.applicationSessionSeconds ?? 30 * 24 * 60 * 60;
+                assertPositiveInteger(applicationSessionSeconds, 'applicationSessionSeconds');
+                applicationExpiresAt = Date.now() + applicationSessionSeconds * 1000;
+                applicationData = input.applicationData;
+                await input.transactionStore.replace(stateHash, {
+                    ...transaction,
+                    stagedApplicationSession: {
+                        authorizationCodeHash: providerCodeHash,
+                        applicationExpiresAt,
+                        applicationData,
+                    },
+                });
+            }
+            const material = this.readSessionMaterial(await this.recoverablePostJson('/member-auth/hosted/authorizations/exchange', {
+                attempt_id: transaction.exchangeAttemptId,
+                code,
+                code_verifier: transaction.codeVerifier,
+                redirect_uri: transaction.redirectUri,
+            }), 'Hosted authorization exchange');
+            const established = await this.persistSessionMaterial({
+                material,
+                reference: transaction.sessionReference,
+                sessionStore: input.sessionStore,
+                applicationData,
+                applicationExpiresAt,
+            });
+            await input.transactionStore.replace(stateHash, {
+                status: 'completed',
+                completionMode: 'hosted_result_code',
+                clientFingerprint: this.clientFingerprint,
+                redirectUri: transaction.redirectUri,
+                providerCodeHash,
+                sessionReference: established.reference,
+                expiresAt: Date.now() + COMPLETED_AUTHORIZATION_RECOVERY_MS,
+            });
+            return established;
+        });
+    }
+    /**
+     * Launches the narrow, Hosted-only XKOVA Account Center from an existing
+     * customer application session. The browser receives only a one-time
+     * handoff URL and state. The member session, PKCE verifier, and exchange
+     * attempt remain in the customer BFF stores.
+     */
+    async beginAccountCenterHandoff(input) {
+        const browserOrigin = normalizeBrowserOrigin(input.browserOrigin);
+        const returnUri = normalizeCallbackUri(input.returnUri);
+        assertAccountCenterIntent(input.intent);
+        const applicationReturnUri = input.applicationReturnUri === undefined
+            ? undefined
+            : normalizeApplicationReturnUri(input.applicationReturnUri, browserOrigin);
+        assertOpaqueReference(input.sessionReference);
+        return input.sessionStore.runExclusive(input.sessionReference, async () => {
+            const memberSession = await input.sessionStore.get(input.sessionReference);
+            if (!memberSession || memberSession.applicationExpiresAt <= Date.now()) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member application session is unavailable for Account Center');
+            }
+            const state = randomBytes(32).toString('base64url');
+            const codeVerifier = randomBytes(32).toString('base64url');
+            const stateHash = hashOpaque(state);
+            const provisionalExpiresAt = Date.now() + HOSTED_AUTHORIZATION_MAX_TTL_MS;
+            const transaction = {
+                status: 'pending',
+                completionMode: 'account_center_result_code',
+                clientFingerprint: this.clientFingerprint,
+                codeVerifier,
+                redirectUri: returnUri,
+                exchangeAttemptId: randomUUID(),
+                sessionReference: input.sessionReference,
+                intent: input.intent,
+                ...(applicationReturnUri !== undefined && {
+                    applicationReturnUri,
+                    applicationReviewUri: applicationReturnUri,
+                }),
+                expiresAt: provisionalExpiresAt,
+            };
+            await input.transactionStore.put(stateHash, transaction);
+            try {
+                const value = await this.recoverablePostJson('/account-center/handoffs', {
+                    intent: input.intent,
+                    origin: browserOrigin,
+                    return_uri: returnUri,
+                    state,
+                    code_challenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+                    code_challenge_method: 'S256',
+                }, memberSession.sessionId);
+                const object = requireObject(value, 'Account Center handoff start');
+                const handoffUrl = normalizeHostedAuthorizationUrl(requireString(object, 'handoff_url', 'Account Center handoff start'));
+                const { expiresAt, expiresAtMillis } = boundedAuthorizationExpiry(object, provisionalExpiresAt, 'Account Center handoff start');
+                await input.transactionStore.replace(stateHash, {
+                    ...transaction,
+                    expiresAt: expiresAtMillis,
+                });
+                return { handoffUrl, state, expiresAt };
+            }
+            catch (error) {
+                try {
+                    await input.transactionStore.delete(stateHash);
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], 'XKOVA Account Center handoff and local transaction cleanup failed');
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Completes a one-time Account Center return. The same existing application
+     * session must still exist and XKOVA binds the result to its exact member
+     * session, application, tenant, workspace, account holder, state, PKCE, and
+     * durable exchange attempt.
+     */
+    async completeAccountCenterHandoff(input) {
+        const callback = new URL(input.callbackUrl);
+        const state = callback.searchParams.get('state');
+        if (!state)
+            throw new Error('Account Center callback is missing state');
+        hashOpaque(input.expectedState);
+        if (!constantTimeStringEqual(state, input.expectedState)) {
+            throw new Error('Account Center callback state does not match the initiating browser');
+        }
+        const stateHash = hashOpaque(state);
+        return input.transactionStore.runExclusive(stateHash, async () => {
+            const transaction = await input.transactionStore.get(stateHash);
+            if (!transaction) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Account Center transaction is missing, expired, or replayed');
+            }
+            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            if (transaction.completionMode !== 'account_center_result_code') {
+                throw new Error('member authorization transaction is not an Account Center flow');
+            }
+            if (!sameCallback(callback, new URL(transaction.redirectUri))) {
+                throw new Error('Account Center callback does not match its return URI');
+            }
+            if (transaction.expiresAt <= Date.now()) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Account Center transaction expired', transaction.applicationReviewUri);
+            }
+            const callbackError = callback.searchParams.get('error');
+            if (callbackError) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError(callbackError === 'access_denied' ? 'authorization_cancelled' : 'provider_rejected', 'XKOVA Account Center did not complete', transaction.applicationReviewUri);
+            }
+            const code = callback.searchParams.get('code');
+            if (!code) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('callback_missing_code', 'Account Center callback is missing code', transaction.applicationReviewUri);
+            }
+            assertHostedAuthorizationResultCode(code);
+            const providerCodeHash = hashProviderCode(code);
+            if (transaction.status === 'completed') {
+                if (!constantTimeStringEqual(transaction.providerCodeHash, providerCodeHash)) {
+                    throw new Error('Account Center callback code changed during retry');
+                }
+                return {
+                    status: 'completed',
+                    intent: transaction.intent,
+                    ...(transaction.applicationReturnUri !== undefined && {
+                        applicationReturnUri: transaction.applicationReturnUri,
+                    }),
+                    ...(transaction.signingExchangeCode !== undefined && {
+                        signingExchangeCode: transaction.signingExchangeCode,
+                    }),
+                    ...(transaction.signingUrl !== undefined && { signingUrl: transaction.signingUrl }),
+                };
+            }
+            const memberSession = await input.sessionStore.get(transaction.sessionReference);
+            if (!memberSession || memberSession.applicationExpiresAt <= Date.now()) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member application session is unavailable for Account Center completion', transaction.applicationReviewUri);
+            }
+            const value = await this.recoverablePostJson('/account-center/handoffs/exchange', {
+                attempt_id: transaction.exchangeAttemptId,
+                code,
+                code_verifier: transaction.codeVerifier,
+                return_uri: transaction.redirectUri,
+            }, memberSession.sessionId);
+            const object = requireObject(value, 'Account Center handoff completion');
+            if (object['status'] !== 'completed' || object['intent'] !== transaction.intent) {
+                throw new Error('XKOVA Account Center returned a mismatched completion projection');
+            }
+            const signingExchangeCode = transaction.intent === 'action'
+                ? requireString(object, 'signing_exchange_code', 'Account Center action completion')
+                : undefined;
+            const signingUrl = transaction.intent === 'action'
+                ? normalizeHostedAuthorizationUrl(requireString(object, 'signing_url', 'Account Center action completion'))
+                : undefined;
+            await input.transactionStore.replace(stateHash, {
+                status: 'completed',
+                completionMode: 'account_center_result_code',
+                clientFingerprint: this.clientFingerprint,
+                redirectUri: transaction.redirectUri,
+                providerCodeHash,
+                sessionReference: transaction.sessionReference,
+                intent: transaction.intent,
+                ...(signingExchangeCode !== undefined && { signingExchangeCode }),
+                ...(signingUrl !== undefined && { signingUrl }),
+                ...(transaction.applicationReturnUri !== undefined && {
+                    applicationReturnUri: transaction.applicationReturnUri,
+                }),
+                ...(transaction.applicationReviewUri !== undefined && {
+                    applicationReviewUri: transaction.applicationReviewUri,
+                }),
+                ...(transaction.actionResource !== undefined && {
+                    actionResource: transaction.actionResource,
+                }),
+                expiresAt: Date.now() + COMPLETED_AUTHORIZATION_RECOVERY_MS,
+            });
+            return {
+                status: 'completed',
+                intent: transaction.intent,
+                ...(transaction.applicationReturnUri !== undefined && {
+                    applicationReturnUri: transaction.applicationReturnUri,
+                }),
+                ...(signingExchangeCode !== undefined && { signingExchangeCode }),
+                ...(signingUrl !== undefined && { signingUrl }),
+            };
+        });
+    }
+    /**
+     * Binds fresh authorization to one existing resource. Hosted applications
+     * use Account Center passkeys. OIDC applications receive the assurance
+     * requirements their BFF must request from the registered provider.
+     */
+    async beginMemberAction(input) {
+        assertMemberAction(input.resourceType, input.action);
+        if (input.resourceId.length === 0 || input.resourceId.length > 80) {
+            throw new TypeError('member action resourceId must contain from 1 through 80 characters');
+        }
+        const browserOrigin = normalizeBrowserOrigin(input.browserOrigin);
+        const returnUri = normalizeCallbackUri(input.returnUri);
+        const applicationReturnUri = input.applicationReturnUri === undefined
+            ? undefined
+            : normalizeApplicationReturnUri(input.applicationReturnUri, browserOrigin);
+        const applicationReviewUri = input.applicationReviewUri === undefined
+            ? undefined
+            : normalizeApplicationReturnUri(input.applicationReviewUri, browserOrigin);
+        assertOpaqueReference(input.sessionReference);
+        return input.sessionStore.runExclusive(input.sessionReference, async () => {
+            const memberSession = await input.sessionStore.get(input.sessionReference);
+            if (!memberSession || memberSession.applicationExpiresAt <= Date.now()) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member application session is unavailable for action authorization');
+            }
+            const state = randomBytes(32).toString('base64url');
+            const codeVerifier = randomBytes(32).toString('base64url');
+            const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+            const stateHash = hashOpaque(state);
+            const provisionalExpiresAt = Date.now() + HOSTED_AUTHORIZATION_MAX_TTL_MS;
+            const transaction = {
+                status: 'pending',
+                completionMode: 'account_center_result_code',
+                clientFingerprint: this.clientFingerprint,
+                codeVerifier,
+                redirectUri: returnUri,
+                exchangeAttemptId: generateXKOVAMemberOperationAttemptId(),
+                sessionReference: input.sessionReference,
+                intent: 'action',
+                ...(applicationReturnUri !== undefined && { applicationReturnUri }),
+                ...(applicationReviewUri !== undefined && { applicationReviewUri }),
+                actionResource: { type: input.resourceType, id: input.resourceId, action: input.action },
+                expiresAt: provisionalExpiresAt,
+            };
+            await input.transactionStore.put(stateHash, transaction);
+            try {
+                const value = await this.recoverablePostJson('/member-actions', {
+                    resource_type: input.resourceType,
+                    resource_id: input.resourceId,
+                    action: input.action,
+                    origin: browserOrigin,
+                    return_uri: returnUri,
+                    state,
+                    code_challenge: codeChallenge,
+                    code_challenge_method: 'S256',
+                }, memberSession.sessionId);
+                const object = requireObject(value, 'member action authorization start');
+                const method = requireString(object, 'authorization_method', 'member action authorization start');
+                const { expiresAt, expiresAtMillis } = boundedAuthorizationExpiry(object, provisionalExpiresAt, 'member action authorization start');
+                if (method === 'hosted_passkey') {
+                    const authorizationUrl = normalizeHostedAuthorizationUrl(requireString(object, 'authorization_url', 'member action authorization start'));
+                    await input.transactionStore.replace(stateHash, {
+                        ...transaction,
+                        actionAuthorization: { method: 'hosted_passkey' },
+                        expiresAt: expiresAtMillis,
+                    });
+                    return {
+                        authorizationMethod: 'hosted_passkey',
+                        authorizationUrl,
+                        state,
+                        expiresAt,
+                    };
+                }
+                if (method !== 'external_oidc') {
+                    throw new Error('XKOVA member action returned an unsupported authorization method');
+                }
+                const actionToken = requireString(object, 'action_token', 'member action authorization start');
+                const nonce = requireString(object, 'nonce', 'member action authorization start');
+                const issuer = requireString(object, 'issuer', 'member action authorization start');
+                const audience = requireString(object, 'audience', 'member action authorization start');
+                const maxAuthAgeSeconds = requirePositiveInteger(object, 'max_auth_age_seconds', 'member action authorization start');
+                const requiredAcrValues = requireStringArray(object, 'required_acr_values', 'member action authorization start');
+                const requiredAmrValues = requireStringArray(object, 'required_amr_values', 'member action authorization start');
+                await input.transactionStore.replace(stateHash, {
+                    ...transaction,
+                    actionAuthorization: { method: 'external_oidc', actionToken, nonce },
+                    expiresAt: expiresAtMillis,
+                });
+                return {
+                    authorizationMethod: 'external_oidc',
+                    actionToken,
+                    state,
+                    nonce,
+                    codeChallenge,
+                    codeChallengeMethod: 'S256',
+                    issuer,
+                    audience,
+                    maxAuthAgeSeconds,
+                    requiredAcrValues,
+                    requiredAmrValues,
+                    expiresAt,
+                };
+            }
+            catch (error) {
+                try {
+                    await input.transactionStore.delete(stateHash);
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], 'XKOVA member action initiation and local transaction cleanup failed');
+                }
+                throw error;
+            }
+        });
+    }
+    /** Completes the exact Hosted-passkey or FI-OIDC action ceremony. */
+    async completeMemberAction(input) {
+        const callback = new URL(input.callbackUrl);
+        const state = callback.searchParams.get('state');
+        if (!state)
+            throw new Error('member action callback is missing state');
+        hashOpaque(input.expectedState);
+        if (!constantTimeStringEqual(state, input.expectedState)) {
+            throw new Error('member action callback state does not match the initiating browser');
+        }
+        const stateHash = hashOpaque(state);
+        const initial = await input.transactionStore.get(stateHash);
+        if (initial?.completionMode === 'account_center_result_code' &&
+            initial.status === 'pending' &&
+            initial.intent === 'action' &&
+            initial.actionAuthorization?.method === 'hosted_passkey') {
+            const completion = await this.completeAccountCenterHandoff(input);
+            if (!completion.signingExchangeCode || !completion.signingUrl) {
+                throw new Error('XKOVA Hosted action completion omitted its signing projection');
+            }
+            return {
+                signingExchangeCode: completion.signingExchangeCode,
+                signingUrl: completion.signingUrl,
+                ...(initial.applicationReturnUri !== undefined && {
+                    applicationReturnUri: initial.applicationReturnUri,
+                }),
+            };
+        }
+        return input.transactionStore.runExclusive(stateHash, async () => {
+            const transaction = await input.transactionStore.get(stateHash);
+            if (!transaction) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member action transaction is missing, expired, or replayed');
+            }
+            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            if (transaction.completionMode !== 'account_center_result_code' ||
+                transaction.intent !== 'action') {
+                throw new Error('member authorization transaction is not an action flow');
+            }
+            if (!sameCallback(callback, new URL(transaction.redirectUri))) {
+                throw new Error('member action callback does not match its return URI');
+            }
+            if (transaction.expiresAt <= Date.now()) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member action transaction expired', transaction.applicationReviewUri);
+            }
+            const callbackError = callback.searchParams.get('error');
+            if (callbackError) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError(callbackError === 'access_denied' ? 'authorization_cancelled' : 'provider_rejected', 'member action provider did not complete authorization', transaction.applicationReviewUri);
+            }
+            const code = callback.searchParams.get('code');
+            if (!code) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('callback_missing_code', 'member action callback is missing code', transaction.applicationReviewUri);
+            }
+            const providerCodeHash = hashProviderCode(code);
+            if (transaction.status === 'completed') {
+                if (!constantTimeStringEqual(transaction.providerCodeHash, providerCodeHash)) {
+                    throw new Error('member action callback code changed during retry');
+                }
+                if (!transaction.signingExchangeCode || !transaction.signingUrl) {
+                    throw new Error('completed member action is missing its signing projection');
+                }
+                return {
+                    signingExchangeCode: transaction.signingExchangeCode,
+                    signingUrl: transaction.signingUrl,
+                    ...(transaction.applicationReturnUri !== undefined && {
+                        applicationReturnUri: transaction.applicationReturnUri,
+                    }),
+                };
+            }
+            if (transaction.actionAuthorization?.method !== 'external_oidc') {
+                throw new Error('member action transaction does not contain external OIDC authority');
+            }
+            const memberSession = await input.sessionStore.get(transaction.sessionReference);
+            if (!memberSession || memberSession.applicationExpiresAt <= Date.now()) {
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member application session is unavailable for action completion', transaction.applicationReviewUri);
+            }
+            let proofToken;
+            const staged = transaction.actionAuthorization.stagedProviderExchange;
+            if (staged) {
+                if (!constantTimeStringEqual(staged.providerCodeHash, providerCodeHash)) {
+                    throw new Error('member action callback code changed during retry');
+                }
+                proofToken = staged.proofToken;
+            }
+            else {
+                if (!input.exchangeProviderCode) {
+                    throw new TypeError('external member action completion requires exchangeProviderCode');
+                }
+                const provider = await input.exchangeProviderCode({
+                    code,
+                    codeVerifier: transaction.codeVerifier,
+                    nonce: transaction.actionAuthorization.nonce,
+                    redirectUri: transaction.redirectUri,
+                    proofKind: 'oidc',
+                });
+                proofToken = provider.proofToken;
+                assertProofToken(proofToken);
+                assertExactProofNonce(provider.nonceToken ?? proofToken, transaction.actionAuthorization.nonce);
+                await input.transactionStore.replace(stateHash, {
+                    ...transaction,
+                    actionAuthorization: {
+                        ...transaction.actionAuthorization,
+                        stagedProviderExchange: { providerCodeHash, proofToken },
+                    },
+                });
+            }
+            const value = await this.recoverablePostJson('/member-actions/external/complete', {
+                action_token: transaction.actionAuthorization.actionToken,
+                provider_proof: proofToken,
+            }, memberSession.sessionId);
+            const object = requireObject(value, 'member action completion');
+            const signingExchangeCode = requireString(object, 'signing_exchange_code', 'member action completion');
+            const signingUrl = normalizeHostedAuthorizationUrl(requireString(object, 'signing_url', 'member action completion'));
+            const expiresAt = requireIsoDate(object, 'expires_at', 'member action completion');
+            await input.transactionStore.replace(stateHash, {
+                status: 'completed',
+                completionMode: 'account_center_result_code',
+                clientFingerprint: this.clientFingerprint,
+                redirectUri: transaction.redirectUri,
+                providerCodeHash,
+                sessionReference: transaction.sessionReference,
+                intent: 'action',
+                signingExchangeCode,
+                signingUrl,
+                ...(transaction.applicationReturnUri !== undefined && {
+                    applicationReturnUri: transaction.applicationReturnUri,
+                }),
+                ...(transaction.applicationReviewUri !== undefined && {
+                    applicationReviewUri: transaction.applicationReviewUri,
+                }),
+                ...(transaction.actionResource !== undefined && {
+                    actionResource: transaction.actionResource,
+                }),
+                expiresAt: Date.now() + COMPLETED_AUTHORIZATION_RECOVERY_MS,
+            });
+            return {
+                signingExchangeCode,
+                signingUrl,
+                ...(transaction.applicationReturnUri !== undefined && {
+                    applicationReturnUri: transaction.applicationReturnUri,
+                }),
+                expiresAt,
+            };
+        });
+    }
+    async completeAuthorizationCallback(input) {
+        const callback = new URL(input.callbackUrl);
+        const state = callback.searchParams.get('state');
+        if (!state)
+            throw new Error('member authorization callback is missing state');
+        hashOpaque(input.expectedState);
+        if (!constantTimeStringEqual(state, input.expectedState)) {
+            throw new Error('member authorization callback state does not match the initiating browser');
+        }
+        const stateHash = hashOpaque(state);
+        return input.transactionStore.runExclusive(stateHash, async () => {
+            const transaction = await input.transactionStore.get(stateHash);
+            if (!transaction || transaction.expiresAt <= Date.now()) {
+                if (transaction)
+                    await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'member authorization transaction is missing, expired, or replayed');
+            }
+            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            if (transaction.completionMode !== 'provider_proof') {
+                throw new Error('member authorization transaction is not a provider-proof flow');
+            }
+            if (!sameCallback(callback, new URL(transaction.redirectUri))) {
+                throw new Error('member authorization callback does not match its redirect URI');
+            }
+            const providerError = callback.searchParams.get('error');
+            if (providerError) {
+                await input.transactionStore.delete(stateHash);
+                throw new XKOVAMemberAuthorizationTerminalError('provider_rejected', 'member identity provider rejected authorization');
+            }
+            const code = callback.searchParams.get('code');
+            if (!code) {
+                throw new XKOVAMemberAuthorizationTerminalError('callback_missing_code', 'member authorization callback is missing code');
+            }
+            const providerCodeHash = hashProviderCode(code);
+            if (transaction.status === 'completed') {
+                if (!constantTimeStringEqual(transaction.providerCodeHash, providerCodeHash)) {
+                    throw new Error('member authorization callback code changed during retry');
+                }
+                const session = await input.sessionStore.get(transaction.sessionReference);
+                if (!session) {
+                    throw new Error('completed member authorization references missing application-session material');
+                }
+                return {
+                    reference: transaction.sessionReference,
+                    session,
+                    projection: projectXKOVAMemberSession(session),
+                };
+            }
+            let proofToken;
+            let applicationExpiresAt;
+            let applicationData;
+            if (transaction.stagedProviderExchange) {
+                if (!constantTimeStringEqual(transaction.stagedProviderExchange.providerCodeHash, providerCodeHash)) {
+                    throw new Error('member authorization callback code changed during retry');
+                }
+                proofToken = transaction.stagedProviderExchange.proofToken;
+                applicationExpiresAt = transaction.stagedProviderExchange.applicationExpiresAt;
+                applicationData = transaction.stagedProviderExchange.applicationData;
+            }
+            else {
+                const result = await input.exchangeProviderCode({
+                    code,
+                    codeVerifier: transaction.codeVerifier,
+                    nonce: transaction.nonce,
+                    redirectUri: transaction.redirectUri,
+                    proofKind: transaction.proofKind,
+                });
+                assertExactProofNonce(result.nonceToken ?? result.proofToken, transaction.nonce);
+                proofToken = result.proofToken;
+                const applicationSessionSeconds = input.applicationSessionSeconds ?? 30 * 24 * 60 * 60;
+                assertPositiveInteger(applicationSessionSeconds, 'applicationSessionSeconds');
+                applicationExpiresAt = Date.now() + applicationSessionSeconds * 1000;
+                applicationData = input.applicationData;
+                await input.transactionStore.replace(stateHash, {
+                    ...transaction,
+                    stagedProviderExchange: {
+                        providerCodeHash,
+                        proofToken,
+                        applicationExpiresAt,
+                        applicationData,
+                    },
+                });
+            }
+            const established = await this.persistSessionWithAttempt({
+                proofToken,
+                attemptId: transaction.exchangeAttemptId,
+                reference: transaction.sessionReference,
+                sessionStore: input.sessionStore,
+                applicationData,
+                applicationExpiresAt,
+            });
+            await input.transactionStore.replace(stateHash, {
+                status: 'completed',
+                completionMode: 'provider_proof',
+                clientFingerprint: this.clientFingerprint,
+                redirectUri: transaction.redirectUri,
+                providerCodeHash,
+                sessionReference: established.reference,
+                expiresAt: Date.now() + COMPLETED_AUTHORIZATION_RECOVERY_MS,
+            });
+            return established;
+        });
+    }
+    async establishSession(input) {
+        const ttl = input.applicationSessionSeconds ?? 30 * 24 * 60 * 60;
+        assertPositiveInteger(ttl, 'applicationSessionSeconds');
+        const exchangeHash = hashProofExchangeId(input.exchangeId);
+        return input.exchangeStore.runExclusive(exchangeHash, async () => {
+            let transaction = await input.exchangeStore.get(exchangeHash);
+            if (transaction && transaction.expiresAt <= Date.now()) {
+                await input.exchangeStore.delete(exchangeHash);
+                transaction = null;
+            }
+            if (transaction) {
+                assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
+            }
+            if (transaction?.status === 'completed') {
+                const session = await input.sessionStore.get(transaction.sessionReference);
+                if (!session) {
+                    throw new Error('completed member proof exchange references missing application-session material');
+                }
+                return {
+                    reference: transaction.sessionReference,
+                    session,
+                    projection: projectXKOVAMemberSession(session),
+                };
+            }
+            if (transaction?.status === 'pending' && input.proofToken !== undefined) {
+                if (!constantTimeStringEqual(hashProof(input.proofToken), hashProof(transaction.proofToken))) {
+                    throw new Error('member proof changed during exchange recovery');
+                }
+            }
+            if (!transaction) {
+                if (input.proofToken === undefined) {
+                    throw new Error('member proof exchange is not staged');
+                }
+                assertProofToken(input.proofToken);
+                const now = Date.now();
+                transaction = {
+                    status: 'pending',
+                    clientFingerprint: this.clientFingerprint,
+                    attemptId: generateXKOVAMemberOperationAttemptId(),
+                    proofToken: input.proofToken,
+                    sessionReference: randomBytes(32).toString('base64url'),
+                    applicationExpiresAt: now + ttl * 1000,
+                    applicationData: input.applicationData,
+                    expiresAt: Math.min(now + 24 * 60 * 60 * 1000, now + ttl * 1000),
+                };
+                await input.exchangeStore.put(exchangeHash, transaction);
+            }
+            if (transaction.status !== 'pending') {
+                throw new Error('member proof exchange transaction has an invalid state');
+            }
+            const established = await this.persistSessionWithAttempt({
+                proofToken: transaction.proofToken,
+                attemptId: transaction.attemptId,
+                reference: transaction.sessionReference,
+                sessionStore: input.sessionStore,
+                applicationData: transaction.applicationData,
+                applicationExpiresAt: transaction.applicationExpiresAt,
+            });
+            await input.exchangeStore.replace(exchangeHash, {
+                status: 'completed',
+                clientFingerprint: this.clientFingerprint,
+                sessionReference: transaction.sessionReference,
+                expiresAt: transaction.expiresAt,
+            });
+            return established;
+        });
+    }
+    async resolveSession(input) {
+        assertOpaqueReference(input.reference);
+        const skew = input.refreshSkewSeconds ?? 60;
+        assertPositiveInteger(skew, 'refreshSkewSeconds');
+        return input.sessionStore.runExclusive(input.reference, async () => {
+            const current = await input.sessionStore.get(input.reference);
+            if (!current)
+                return null;
+            if (current.applicationExpiresAt <= Date.now()) {
+                await input.sessionStore.delete(input.reference);
+                return null;
+            }
+            try {
+                let active = current;
+                if (current.expiresAt <= Date.now() + skew * 1000) {
+                    const attemptId = current.pendingRefreshAttemptId ?? generateXKOVAMemberOperationAttemptId();
+                    if (current.pendingRefreshAttemptId === undefined) {
+                        active = { ...current, pendingRefreshAttemptId: attemptId };
+                        await input.sessionStore.replace(input.reference, active);
+                    }
+                    const rotated = await this.refresh(current.refreshToken, { attemptId });
+                    const { pendingRefreshAttemptId: _completed, ...withoutPending } = active;
+                    active = {
+                        ...withoutPending,
+                        ...rotated,
+                    };
+                    await input.sessionStore.replace(input.reference, active);
+                }
+                if (input.validateWithXkova !== false) {
+                    const context = await this.getSession(active.sessionId);
+                    if (context.accountHolderId !== active.accountHolderId ||
+                        context.providerSubject !== active.providerSubject) {
+                        throw new Error('XKOVA member context changed for an active session');
+                    }
+                    if (context.expiresAt !== active.expiresAt) {
+                        active = { ...active, expiresAt: context.expiresAt };
+                        await input.sessionStore.replace(input.reference, active);
+                    }
+                }
+                return active;
+            }
+            catch (error) {
+                if (isTerminalSessionError(error)) {
+                    await input.sessionStore.delete(input.reference);
+                    return null;
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Resolve, refresh and validate a confidential session, then bind typed
+     * business operations to it. Call once per incoming BFF request, after the
+     * application has checked its browser Origin and mutation CSRF proof.
+     * Do not cache the returned request-scoped resources across requests.
+     */
+    async resolveResources(input) {
+        const session = await this.resolveSession(input);
+        if (!session)
+            return null;
+        const context = Object.freeze({
+            memberSessionId: session.sessionId,
+            memberAuthPublishableKey: this.options.publishableKey,
+            accountHolderId: session.accountHolderId,
+        });
+        return {
+            session,
+            resources: new XKOVAMemberResources(XKOVAClient.forMemberSession(this.options, context), context, session.accountHolderId),
+        };
+    }
+    /** Bind durable action reviews to the same exact session and public resources as normal reads. */
+    async resolveActionIntents(input) {
+        const resolved = await this.resolveResources(input);
+        if (!resolved)
+            return null;
+        return new XKOVAMemberActionIntents({
+            clientFingerprint: this.clientFingerprint,
+            sessionReference: input.reference,
+            accountHolderId: resolved.session.accountHolderId,
+            applicationExpiresAt: resolved.session.applicationExpiresAt,
+        }, input.intentStore, resolved.resources);
+    }
+    async logoutSession(input) {
+        assertOpaqueReference(input.reference);
+        await input.sessionStore.runExclusive(input.reference, async () => {
+            const session = await input.sessionStore.get(input.reference);
+            if (!session)
+                return;
+            try {
+                await this.signOutExactSession(session.sessionId);
+            }
+            catch (error) {
+                if (!isAlreadyRevokedSessionError(error))
+                    throw error;
+            }
+            await input.sessionStore.delete(input.reference);
+        });
+    }
+    async persistSessionWithAttempt(input) {
+        assertOpaqueReference(input.reference);
+        assertOperationAttemptId(input.attemptId);
+        const applicationExpiresAt = input.applicationExpiresAt ??
+            Date.now() + (input.applicationSessionSeconds ?? 30 * 24 * 60 * 60) * 1000;
+        const material = await this.exchangeProof(input.proofToken, {
+            attemptId: input.attemptId,
+        });
+        return this.persistSessionMaterial({
+            material,
+            reference: input.reference,
+            sessionStore: input.sessionStore,
+            applicationData: input.applicationData,
+            applicationExpiresAt,
+        });
+    }
+    async persistSessionMaterial(input) {
+        assertOpaqueReference(input.reference);
+        if (!Number.isSafeInteger(input.applicationExpiresAt) ||
+            input.applicationExpiresAt <= Date.now()) {
+            throw new TypeError('application session expiry must be in the future');
+        }
+        const session = {
+            ...input.material,
+            applicationExpiresAt: input.applicationExpiresAt,
+            applicationData: input.applicationData,
+        };
+        const existing = await input.sessionStore.get(input.reference);
+        if (existing) {
+            if (existing.sessionId !== session.sessionId ||
+                existing.refreshToken !== session.refreshToken ||
+                existing.accountHolderId !== session.accountHolderId ||
+                existing.providerSubject !== session.providerSubject ||
+                existing.applicationExpiresAt !== session.applicationExpiresAt) {
+                throw new Error('member proof recovery found different material at its stable session reference');
+            }
+            return {
+                reference: input.reference,
+                session: existing,
+                projection: projectXKOVAMemberSession(existing),
+            };
+        }
+        await input.sessionStore.put(input.reference, session);
+        return {
+            reference: input.reference,
+            session,
+            projection: projectXKOVAMemberSession(session),
+        };
+    }
+    postJson(path, body, sessionId, idempotencyKey) {
+        return this.requestJson({
+            method: 'POST',
+            path,
+            ...(body !== undefined && { body }),
+            ...(sessionId !== undefined && { sessionId }),
+            ...(idempotencyKey !== undefined && { idempotencyKey }),
+        });
+    }
+    async recoverablePostJson(path, body, sessionId) {
+        const idempotencyKey = generateIdempotencyKey();
+        try {
+            return await this.postJson(path, body, sessionId, idempotencyKey);
+        }
+        catch (error) {
+            if (!isAmbiguousTransportFailure(error))
+                throw error;
+            return this.postJson(path, body, sessionId, idempotencyKey);
+        }
+    }
+    getJson(path, sessionId) {
+        return this.requestJson({ method: 'GET', path, sessionId });
+    }
+    async requestJson(input) {
+        const url = new URL(`${this.apiBaseUrl}${input.path}`);
+        const serializedBody = input.body === undefined ? undefined : JSON.stringify(input.body);
+        if (input.body !== undefined && serializedBody === undefined) {
+            throw new TypeError('XKOVA member BFF request body is not JSON serializable');
+        }
+        const body = serializedBody === undefined ? new Uint8Array() : new TextEncoder().encode(serializedBody);
+        const headers = new Headers({
+            accept: 'application/json',
+            authorization: `Bearer ${this.options.apiKey}`,
+            'x-xkova-publishable-key': this.options.publishableKey,
+        });
+        if (input.method === 'POST') {
+            headers.set('idempotency-key', input.idempotencyKey ?? generateIdempotencyKey());
+        }
+        if (serializedBody !== undefined) {
+            headers.set('content-type', 'application/json');
+        }
+        if (input.sessionId !== undefined) {
+            headers.set('x-member-session-id', input.sessionId);
+        }
+        const signer = this.options.requestSigner;
+        if (input.method === 'POST' && this.options.apiKey.startsWith('xkv_live_')) {
+            if (!signer) {
+                throw new Error('XKOVA production member-session mutations require a request signer');
+            }
+        }
+        if (input.method === 'POST' && signer !== undefined) {
+            if (serializedBody !== undefined) {
+                headers.set('content-digest', xkovaContentDigest(body));
+            }
+            const signature = await signXKOVARequest({
+                method: input.method,
+                url,
+                headers,
+                body,
+                signer,
+            });
+            headers.set('signature-input', signature.signatureInput);
+            headers.set('signature', signature.signature);
+        }
+        const signal = this.requestSignal();
+        const response = await this.fetchImpl(url, {
+            method: input.method,
+            headers,
+            cache: 'no-store',
+            redirect: 'error',
+            ...(serializedBody !== undefined && { body: serializedBody }),
+            ...(signal !== undefined && { signal }),
+        });
+        if (!response.ok)
+            throw await XKOVAApiError.fromResponse(response);
+        if (response.status === 204)
+            return undefined;
+        const text = await response.text();
+        if (text.length === 0)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`XKOVA member BFF received non-JSON HTTP ${response.status}`);
+        }
+    }
+    readSessionMaterial(value, operation) {
+        const object = requireObject(value, operation);
+        const member = requireObject(object['member'], `${operation} member`);
+        const expiresIn = object['expires_in'];
+        if (typeof expiresIn !== 'number' || !Number.isInteger(expiresIn) || expiresIn <= 0) {
+            throw new Error(`XKOVA member ${operation} returned an invalid expiry`);
+        }
+        return {
+            sessionId: requireString(object, 'session_id', operation),
+            refreshToken: requireString(object, 'refresh_token', operation),
+            accountHolderId: requireString(member, 'account_holder_id', `${operation} member`),
+            providerSubject: requireString(member, 'provider_subject', `${operation} member`),
+            expiresAt: Date.now() + expiresIn * 1000,
+        };
+    }
+    requestSignal() {
+        return this.options.timeoutMs === undefined
+            ? undefined
+            : AbortSignal.timeout(this.options.timeoutMs);
+    }
+}
+/** Only confirmed admission rejections may release a customer's pending demo reservation. */
+export function isDefinitiveXKOVASandboxDemoAdmissionFailure(error) {
+    return (error instanceof XKOVAMemberAuthorizationTerminalError ||
+        (error instanceof XKOVAApiError &&
+            (error.status < 500 ||
+                error.code === 'demo_persona_unavailable' ||
+                error.code === 'demo_login_disabled')));
+}
+export function projectXKOVAMemberSession(session) {
+    return {
+        signedIn: true,
+        accountHolderId: session.accountHolderId,
+        expiresAt: new Date(session.expiresAt).toISOString(),
+    };
+}
+export function serializeXKOVAMemberSessionCookie(input) {
+    assertHostCookieName(input.cookieName);
+    assertOpaqueReference(input.reference);
+    assertPositiveInteger(input.maxAgeSeconds, 'member cookie maxAgeSeconds');
+    return `${input.cookieName}=${encodeURIComponent(input.reference)}; Path=/; Max-Age=${input.maxAgeSeconds}; HttpOnly; Secure; SameSite=Strict`;
+}
+/** Short-lived Lax cookie for cross-site OAuth/OIDC callback state only. */
+export function serializeXKOVAMemberFlowCookie(input) {
+    assertHostCookieName(input.cookieName);
+    assertOpaqueReference(input.reference);
+    const maxAge = input.maxAgeSeconds ?? 300;
+    assertPositiveInteger(maxAge, 'member flow cookie maxAgeSeconds');
+    if (maxAge > 600) {
+        throw new TypeError('member flow cookie maxAgeSeconds must not exceed 600');
+    }
+    return `${input.cookieName}=${encodeURIComponent(input.reference)}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+}
+export function serializeClearedXKOVAMemberCookie(cookieName) {
+    assertHostCookieName(cookieName);
+    return `${cookieName}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Strict`;
+}
+/** One short-lived cookie per ceremony, so another tab cannot replace its browser binding. */
+export function xkovaMemberFlowCookieName(cookiePrefix, state) {
+    assertHostCookieName(cookiePrefix);
+    assertOpaqueReference(state);
+    return `${cookiePrefix}_${hashOpaque(state)}`;
+}
+/** State must match a real HttpOnly cookie. A callback query alone is never authority. */
+export function readXKOVAMemberCallbackFlow(input) {
+    const states = new URL(input.callbackUrl).searchParams.getAll('state');
+    if (states.length !== 1 || !/^[A-Za-z0-9_-]{43,128}$/.test(states[0]))
+        return null;
+    const state = states[0];
+    const cookieName = xkovaMemberFlowCookieName(input.cookiePrefix, state);
+    const cookieState = readXKOVAMemberCookie(input.cookieHeader, cookieName);
+    return cookieState && constantTimeStringEqual(state, cookieState) ? { state, cookieName } : null;
+}
+export function readXKOVAMemberCookie(cookieHeader, cookieName) {
+    assertHostCookieName(cookieName);
+    if (!cookieHeader)
+        return null;
+    for (const segment of cookieHeader.split(';')) {
+        const [name, ...valueParts] = segment.trim().split('=');
+        if (name !== cookieName)
+            continue;
+        let value;
+        try {
+            value = decodeURIComponent(valueParts.join('='));
+        }
+        catch {
+            return null;
+        }
+        return /^[A-Za-z0-9_-]{43,128}$/.test(value) ? value : null;
+    }
+    return null;
+}
+export function createXKOVAMemberCsrfToken(input) {
+    assertOpaqueReference(input.sessionReference);
+    const secret = csrfSecret(input.secret);
+    const ttl = input.ttlSeconds ?? 15 * 60;
+    assertPositiveInteger(ttl, 'CSRF ttlSeconds');
+    if (ttl > 24 * 60 * 60) {
+        throw new TypeError('CSRF ttlSeconds must not exceed 24 hours');
+    }
+    const expiresAt = Math.floor((input.now ?? Date.now()) / 1000) + ttl;
+    const nonce = randomBytes(18).toString('base64url');
+    const payload = `xkv1.${expiresAt}.${nonce}`;
+    const mac = createHmac('sha256', secret)
+        .update(`${payload}.${input.sessionReference}`)
+        .digest('base64url');
+    return `${payload}.${mac}`;
+}
+export function verifyXKOVAMemberCsrfToken(input) {
+    try {
+        assertOpaqueReference(input.sessionReference);
+        const secret = csrfSecret(input.secret);
+        const parts = input.token.split('.');
+        if (parts.length !== 4 ||
+            parts[0] !== 'xkv1' ||
+            !/^\d+$/.test(parts[1] ?? '') ||
+            !/^[A-Za-z0-9_-]{22,}$/.test(parts[2] ?? '') ||
+            !/^[A-Za-z0-9_-]{43}$/.test(parts[3] ?? '')) {
+            return false;
+        }
+        const expiresAt = Number(parts[1]);
+        if (!Number.isSafeInteger(expiresAt))
+            return false;
+        const now = Math.floor((input.now ?? Date.now()) / 1000);
+        if (expiresAt <= now || expiresAt > now + 24 * 60 * 60)
+            return false;
+        const payload = parts.slice(0, 3).join('.');
+        const expected = createHmac('sha256', secret)
+            .update(`${payload}.${input.sessionReference}`)
+            .digest();
+        const presented = Buffer.from(parts[3], 'base64url');
+        return presented.byteLength === expected.byteLength && timingSafeEqual(presented, expected);
+    }
+    catch {
+        return false;
+    }
+}
+export function assertXKOVAMemberRequestOrigin(origin, allowedOrigins) {
+    if (!origin)
+        throw new Error('member BFF request requires an Origin header');
+    const normalized = new URL(origin).origin;
+    if (normalized !== origin || !allowedOrigins.includes(normalized)) {
+        throw new Error('member BFF request Origin is not allowlisted');
+    }
+}
+function normalizeApiBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.username || url.password || url.search || url.hash) {
+        throw new TypeError('XKOVA member BFF baseUrl must be an API origin or /v1 base URL');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
+        throw new TypeError('XKOVA member BFF baseUrl must use HTTPS or localhost HTTP');
+    }
+    const pathname = url.pathname.replace(/\/+$/, '');
+    if (pathname !== '' && pathname !== '/v1') {
+        throw new TypeError('XKOVA member BFF baseUrl must be an API origin or /v1 base URL');
+    }
+    return `${url.origin}/v1`;
+}
+function normalizeCallbackUri(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash) {
+        throw new TypeError('member authorization redirectUri must not contain credentials, query, or fragment');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
+        throw new TypeError('member authorization redirectUri must use HTTPS or localhost HTTP');
+    }
+    return url.toString();
+}
+function normalizeBrowserOrigin(value) {
+    const url = new URL(value);
+    if (url.origin !== value ||
+        (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))) {
+        throw new TypeError('member authorization browserOrigin must be an exact HTTPS or localhost origin');
+    }
+    return value;
+}
+function normalizeApplicationReturnUri(value, browserOrigin) {
+    const url = new URL(value);
+    if (url.origin !== browserOrigin ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))) {
+        throw new TypeError('member action applicationReturnUri must use the exact browser origin');
+    }
+    return url.toString();
+}
+function normalizeHostedAuthorizationUrl(value) {
+    const url = new URL(value);
+    if (url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== 'https:' &&
+            !(url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')))) {
+        throw new Error('XKOVA member Hosted authorization URL must use HTTPS or loopback HTTP without credentials or a fragment');
+    }
+    return url.toString();
+}
+function sameCallback(actual, expected) {
+    return (actual.username === '' &&
+        actual.password === '' &&
+        actual.protocol === expected.protocol &&
+        actual.host === expected.host &&
+        actual.pathname === expected.pathname &&
+        actual.hash === '');
+}
+function requireObject(value, operation) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`XKOVA member ${operation} returned a malformed object`);
+    }
+    return value;
+}
+function requireString(value, key, operation) {
+    const field = value[key];
+    if (typeof field !== 'string' || field.length === 0) {
+        throw new Error(`XKOVA member ${operation} returned an invalid ${key}`);
+    }
+    return field;
+}
+function requireIsoDate(value, key, operation) {
+    const field = requireString(value, key, operation);
+    if (!Number.isFinite(Date.parse(field))) {
+        throw new Error(`XKOVA member ${operation} returned an invalid ${key}`);
+    }
+    return field;
+}
+/**
+ * Server TTL starts after request transit, not at the BFF's request start.
+ * Validate against receipt time, then intersect it with the original local
+ * deadline. Network latency never extends the state/PKCE transaction lifetime.
+ */
+function boundedAuthorizationExpiry(value, localDeadline, operation) {
+    const serverExpiry = Date.parse(requireIsoDate(value, 'expires_at', operation));
+    const receivedAt = Date.now();
+    if (serverExpiry <= receivedAt ||
+        serverExpiry > receivedAt + HOSTED_AUTHORIZATION_MAX_TTL_MS ||
+        localDeadline <= receivedAt) {
+        throw new Error(`XKOVA member ${operation} returned an invalid expiry window`);
+    }
+    const expiresAtMillis = Math.min(serverExpiry, localDeadline);
+    return { expiresAtMillis, expiresAt: new Date(expiresAtMillis).toISOString() };
+}
+function requirePositiveInteger(value, key, operation) {
+    const field = value[key];
+    if (!Number.isSafeInteger(field) || field <= 0) {
+        throw new Error(`XKOVA member ${operation} returned an invalid ${key}`);
+    }
+    return field;
+}
+function requireStringArray(value, key, operation) {
+    const field = value[key];
+    if (!Array.isArray(field) ||
+        field.some((entry) => typeof entry !== 'string' || entry.length === 0)) {
+        throw new Error(`XKOVA member ${operation} returned an invalid ${key}`);
+    }
+    return field;
+}
+function assertUuid(value, label) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+        throw new TypeError(`${label} must be a UUID`);
+    }
+}
+function assertHostCookieName(cookieName) {
+    if (!/^__Host-[A-Za-z0-9_-]+$/.test(cookieName)) {
+        throw new TypeError('member cookie name must use the __Host- prefix');
+    }
+}
+function assertOpaqueReference(reference) {
+    if (!/^[A-Za-z0-9_-]{43,128}$/.test(reference)) {
+        throw new TypeError('member application-session reference is malformed');
+    }
+}
+export function generateXKOVAMemberOperationAttemptId() {
+    return randomBytes(32).toString('base64url');
+}
+function assertOperationAttemptId(value) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(value)) {
+        throw new TypeError('member session operation attemptId is malformed');
+    }
+}
+function assertProofToken(proofToken) {
+    if (proofToken.length < 20 || proofToken.length > 8192) {
+        throw new TypeError('provider proof must contain from 20 through 8192 characters');
+    }
+}
+function hashProof(proofToken) {
+    assertProofToken(proofToken);
+    return createHash('sha256')
+        .update('xkova:member-provider-proof:v1\0')
+        .update(proofToken)
+        .digest('hex');
+}
+function hashProofExchangeId(exchangeId) {
+    assertOpaqueReference(exchangeId);
+    return createHash('sha256')
+        .update('xkova:member-proof-exchange:v1\0')
+        .update(exchangeId)
+        .digest('hex');
+}
+function assertExactProofNonce(proofToken, expectedNonce) {
+    try {
+        const parts = proofToken.split('.');
+        if (parts.length !== 3 || !parts[1])
+            throw new Error('invalid JWT');
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        if (typeof payload.nonce !== 'string')
+            throw new Error('missing nonce');
+        const expected = Buffer.from(expectedNonce, 'utf8');
+        const actual = Buffer.from(payload.nonce, 'utf8');
+        if (actual.byteLength !== expected.byteLength || !timingSafeEqual(actual, expected)) {
+            throw new Error('nonce mismatch');
+        }
+    }
+    catch {
+        throw new XKOVAMemberAuthorizationTerminalError('proof_nonce_mismatch', 'provider proof nonce does not match the exact authorization transaction');
+    }
+}
+function hashProviderCode(value) {
+    if (value.length === 0 || value.length > 4096) {
+        throw new TypeError('member authorization code has an invalid length');
+    }
+    return createHash('sha256').update('xkova:member-provider-code:v1\0').update(value).digest('hex');
+}
+function assertHostedAuthorizationResultCode(value) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(value)) {
+        throw new TypeError('member Hosted authorization result code is malformed');
+    }
+}
+function assertAccountCenterIntent(value) {
+    if (!new Set(['security', 'sessions', 'wallet_readiness', 'action']).has(value)) {
+        throw new TypeError('Account Center intent is unsupported');
+    }
+}
+function assertMemberAction(resourceType, action) {
+    const allowed = {
+        payment: ['sign'],
+        escrow: ['create', 'cancel'],
+        approval_request: ['attest'],
+    };
+    if (!Object.prototype.hasOwnProperty.call(allowed, resourceType) ||
+        !allowed[resourceType].includes(action)) {
+        throw new TypeError('member action resource and action are unsupported');
+    }
+}
+function constantTimeStringEqual(left, right) {
+    const leftBytes = Buffer.from(left, 'utf8');
+    const rightBytes = Buffer.from(right, 'utf8');
+    return leftBytes.byteLength === rightBytes.byteLength && timingSafeEqual(leftBytes, rightBytes);
+}
+function memberBffClientFingerprint(input) {
+    return createHash('sha256')
+        .update('xkova:member-bff-client:v1\0')
+        .update(input.apiBaseUrl)
+        .update('\0')
+        .update(input.apiKey)
+        .update('\0')
+        .update(input.publishableKey)
+        .digest('base64url');
+}
+function assertMemberBffClientFingerprint(stored, expected) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(stored) || !constantTimeStringEqual(stored, expected)) {
+        throw new Error('member BFF transaction belongs to a different client application');
+    }
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(`${label} must be a positive integer`);
+    }
+}
+function hashOpaque(value) {
+    if (!/^[A-Za-z0-9_-]{43,128}$/.test(value)) {
+        throw new TypeError('member authorization state is malformed');
+    }
+    return createHash('sha256')
+        .update('xkova:member-authorization-state:v1\0')
+        .update(value)
+        .digest('hex');
+}
+function csrfSecret(value) {
+    const bytes = typeof value === 'string' ? Buffer.from(value, 'utf8') : value;
+    if (bytes.byteLength < 32)
+        throw new TypeError('member CSRF secret must be at least 32 bytes');
+    return bytes;
+}
+function isTerminalSessionError(error) {
+    return (error instanceof XKOVAApiError &&
+        new Set([
+            'member_auth_session_revoked',
+            'member_auth_refresh_replay_detected',
+            'member_auth_account_holder_inactive',
+            'member_auth_token_invalid',
+            'member_auth_token_expired',
+        ]).has(error.code));
+}
+function isAlreadyRevokedSessionError(error) {
+    return (error instanceof XKOVAApiError &&
+        error.status === 401 &&
+        error.code === 'member_auth_session_revoked');
+}
+function isAmbiguousTransportFailure(error) {
+    return !(error instanceof XKOVAApiError) || error.status >= 500;
+}