@xkova/sdk 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/held-approval.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Narrow a governance hold before reading a mutation's entity result.
+ *
+ * On a workspace with a seeded/configured governance requirement, a
+ * create-shaped mutation (for example, `createTreasuryCounterparty` or
+ * treasury signer changes) may not execute: it returns a `HeldApproval`
+ * (`{ status: 'pending_approval', pending_approval_request_id }`) instead of
+ * the entity. No entity is created. Independently eligible approvers complete
+ * the required approval, then the same call is reissued through normal policy.
+ *
+ * Narrow BEFORE reading entity fields:
+ *
+ *   const res = await client.treasury.createCounterparty(body, opts);
+ *   if (isHeldApproval(res)) {
+ *     await waitForApproval(res.pending_approval_request_id); // your flow
+ *     return client.treasury.createCounterparty(body, opts); // same request
+ *   }
+ *   res.id; // safely the entity now
+ *
+ * This helper grants no approval, signer authority or permission to retry a
+ * changed request. Existing entity-shaped responses are not governance holds.
+ */
+import type { components } from './generated/types.js';
+export type HeldApproval = components['schemas']['HeldApproval'];
+/** True when a mutation response is a governance hold rather than the entity. */
+export declare function isHeldApproval(res: unknown): res is HeldApproval;
+/**
+ * Thrown by `assertNotHeld` when a mutation was governance-held. Carries the
+ * approval request id so a script that does not implement the attest flow
+ * fails loudly with the pointer a human needs.
+ */
+export declare class XKOVAHeldApprovalError extends Error {
+    readonly pendingApprovalRequestId: string;
+    constructor(held: HeldApproval, action?: string);
+}
+/**
+ * Unwrap a `entity | HeldApproval` union for callers that treat a hold as
+ * exceptional (scripts, one-shot provisioning). Returns the entity, or throws
+ * `XKOVAHeldApprovalError` carrying the approval request id.
+ */
+export declare function assertNotHeld<T>(res: T | HeldApproval, action?: string): T;

package/dist/held-approval.js

@@ -0,0 +1,33 @@
+/** True when a mutation response is a governance hold rather than the entity. */
+export function isHeldApproval(res) {
+    return (typeof res === 'object' &&
+        res !== null &&
+        res.status === 'pending_approval' &&
+        typeof res
+            .pending_approval_request_id === 'string');
+}
+/**
+ * Thrown by `assertNotHeld` when a mutation was governance-held. Carries the
+ * approval request id so a script that does not implement the attest flow
+ * fails loudly with the pointer a human needs.
+ */
+export class XKOVAHeldApprovalError extends Error {
+    pendingApprovalRequestId;
+    constructor(held, action) {
+        super(`${action ?? 'The mutation'} was held for governance approval ` +
+            `(approval request ${held.pending_approval_request_id}). Attest the ` +
+            `request, then re-issue the same call.`);
+        this.name = 'XKOVAHeldApprovalError';
+        this.pendingApprovalRequestId = held.pending_approval_request_id;
+    }
+}
+/**
+ * Unwrap a `entity | HeldApproval` union for callers that treat a hold as
+ * exceptional (scripts, one-shot provisioning). Returns the entity, or throws
+ * `XKOVAHeldApprovalError` carrying the approval request id.
+ */
+export function assertNotHeld(res, action) {
+    if (isHeldApproval(res))
+        throw new XKOVAHeldApprovalError(res, action);
+    return res;
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { generateIdempotencyKey, withIdempotency } from './idempotency.js';
 export { withRetry, type RetryPolicy } from './retry.js';
 export { collectCursor, paginateCursor, type CursorPage, type PaginateCursorOptions, } from './cursor.js';
 export { XKOVAApiError, XKOVAUploadError } from './errors.js';
+export { isHeldApproval, assertNotHeld, XKOVAHeldApprovalError, type HeldApproval, } from './held-approval.js';
 export { type PollOptions } from './resources/workflows.js';
 export { type XKOVAMemberSessionContext } from './resources/account-holders.js';
 export { verifyWebhookSignature, type VerifyWebhookSignatureResult } from './webhook.js';

package/dist/index.js

@@ -4,5 +4,6 @@ export { generateIdempotencyKey, withIdempotency } from './idempotency.js';
 export { withRetry } from './retry.js';
 export { collectCursor, paginateCursor, } from './cursor.js';
 export { XKOVAApiError, XKOVAUploadError } from './errors.js';
+export { isHeldApproval, assertNotHeld, XKOVAHeldApprovalError, } from './held-approval.js';
 export { verifyWebhookSignature } from './webhook.js';
 export { verifyInclusion, verifyConsistency, verifySth, } from './rwa-verify.js';

package/dist/member-action-intents.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { isAllowedProtocol } from './url.js';
 export class XKOVAMemberIntentError extends Error {
     code;
     status;
@@ -33,8 +34,7 @@ export class XKOVAMemberActionIntents {
             location.username ||
             location.password ||
             location.hash ||
-            (location.protocol !== 'https:' &&
-                !(location.protocol === 'http:' && location.hostname === 'localhost')))
+            !isAllowedProtocol(location))
             throw new TypeError('Action review requires the exact application origin');
         const snapshot = JSON.parse(canonicalJson({
             request: input.request,

package/dist/member-bff.d.ts

@@ -8,6 +8,8 @@ type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Respo
 export type XKOVAMemberProofKind = 'xkova_hosted' | 'oidc' | 'signed_launch';
 export type XKOVAMemberProofBindingMode = 'authorization_nonce' | 'server_assertion_jti';
 export type XKOVAAccountCenterIntent = 'security' | 'sessions' | 'wallet_readiness' | 'action';
+/** Direct Account Center starts do not create resource-bound signing authority. */
+export type XKOVAAccountCenterStartIntent = Exclude<XKOVAAccountCenterIntent, 'action'>;
 export type XKOVAMemberActionResourceType = 'payment' | 'escrow' | 'approval_request';
 export type XKOVAMemberActionName = 'sign' | 'create' | 'cancel' | 'attest';
 export interface XKOVAMemberBffClientOptions {
@@ -34,6 +36,14 @@ export interface XKOVAMemberSessionMaterial extends XKOVAMemberContext {
     /** Confidential refresh credential, BFF storage only. */
     readonly refreshToken: string;
 }
+export interface XKOVAExternalMemberEnrollment {
+    readonly accountHolderId: string;
+    readonly applicationId: string;
+    readonly publishableKey: string;
+    readonly applicationConfigVersion: number;
+    readonly providerNamespace: string;
+    readonly created: boolean;
+}
 export interface XKOVABrowserMemberProjection {
     readonly signedIn: true;
     readonly accountHolderId: string;
@@ -49,8 +59,12 @@ export interface StoredXKOVAMemberSession<TApplicationData = unknown> extends XK
 }
 /**
  * `runExclusive` must serialize refresh and logout for the same reference
- * across all BFF instances. Use a database transaction or distributed lock;
- * a process-local mutex cannot coordinate multiple instances.
+ * across all BFF instances. Use a distributed or session-level database lock;
+ * a process-local mutex cannot coordinate multiple instances. This lock is not
+ * a surrounding rollback transaction: every awaited put/replace/delete must be
+ * durable before resolving and must survive a later error from work(). In
+ * particular, a pending refresh-attempt checkpoint cannot roll back after the
+ * provider/API has acted. replace is exact-existing-only, never an upsert.
  */
 export interface XKOVAMemberSessionStore<TApplicationData = unknown> {
     put(reference: string, session: StoredXKOVAMemberSession<TApplicationData>): Promise<void>;
@@ -116,7 +130,7 @@ export type XKOVAMemberAuthorizationTransaction<TApplicationData = unknown> = {
     readonly sessionReference: string;
     readonly intent: XKOVAAccountCenterIntent;
     readonly actionAuthorization?: {
-        readonly method: 'hosted_passkey';
+        readonly method: 'hosted_passkey' | 'xkova_webauthn';
     } | {
         readonly method: 'external_oidc';
         readonly actionToken: string;
@@ -169,6 +183,11 @@ export type XKOVAMemberAuthorizationTransaction<TApplicationData = unknown> = {
  * every BFF instance. `replace` and `delete` must target that exact state. A
  * production store must encrypt the transaction because it can briefly hold a
  * confidential provider proof while XKOVA session exchange is retried.
+ * Every awaited write must commit independently of a later work() exception.
+ * Never wrap the entire callback in a rollback transaction: that can erase the
+ * staged proof after its one-time provider code has already been consumed.
+ * On uncertain write acknowledgement, reconcile the same exact record; never
+ * re-exchange the provider code or invent a replacement operation identity.
  */
 export interface XKOVAMemberAuthorizationTransactionStore<TApplicationData = unknown> {
     put(stateHash: string, transaction: XKOVAMemberAuthorizationTransaction<TApplicationData>): Promise<void>;
@@ -198,6 +217,10 @@ export type XKOVAMemberProofExchangeTransaction<TApplicationData = unknown> = {
  * Durable transaction store for a confidential proof exchange that does not
  * use the browser callback helper. Pending records contain a provider proof
  * and customer application data, so production adapters must encrypt them.
+ * Serialize the exact reference across replicas without a surrounding rollback
+ * transaction. Awaited put/replace/delete checkpoints must remain committed if
+ * the later exchange fails. Reconcile an uncertain acknowledgement against the
+ * same reference and attempt identity before retrying.
  */
 export interface XKOVAMemberProofExchangeTransactionStore<TApplicationData = unknown> {
     put(exchangeHash: string, transaction: XKOVAMemberProofExchangeTransaction<TApplicationData>): Promise<void>;
@@ -239,7 +262,7 @@ export interface XKOVAAccountCenterHandoffCompletion {
     readonly applicationReturnUri?: string;
 }
 export type XKOVAMemberActionAuthorizationStart = {
-    readonly authorizationMethod: 'hosted_passkey';
+    readonly authorizationMethod: 'hosted_passkey' | 'xkova_webauthn';
     readonly authorizationUrl: string;
     readonly state: string;
     readonly expiresAt: string;
@@ -321,6 +344,18 @@ export declare class XKOVAMemberBffClient {
     exchangeProof(proofToken: string, options: {
         readonly attemptId: string;
     }): Promise<XKOVAMemberSessionMaterial>;
+    /**
+     * BFF-only membership provisioning after validating the provider identity or
+     * resolving it from a trusted directory. This creates no login session or
+     * wallet and does not substitute for genuine provider-proof verification.
+     * Save one idempotencyKey before the first attempt and retain the same subject,
+     * selector and observed configuration version during response-loss recovery.
+     */
+    enrollExternalMember(input: {
+        readonly externalSub: string;
+        readonly applicationConfigVersion: number;
+        readonly idempotencyKey: string;
+    }): Promise<XKOVAExternalMemberEnrollment>;
     refresh(refreshToken: string, options: {
         readonly attemptId: string;
     }): Promise<XKOVAMemberSessionMaterial>;
@@ -350,20 +385,6 @@ export declare class XKOVAMemberBffClient {
         readonly redirectUri: string;
         readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
     }): Promise<XKOVAHostedMemberAuthorizationStart>;
-    /**
-     * 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.
-     */
-    completeSandboxDemoAuthorization<TApplicationData>(input: {
-        readonly state: string;
-        readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
-    }): Promise<{
-        readonly callbackUrl: string;
-        readonly expiresAt: string;
-    }>;
     /**
      * Completes the one-time Hosted Auth result-code exchange and persists the
      * provider-neutral XKOVA member session. The returned projection is safe for
@@ -385,7 +406,7 @@ export declare class XKOVAMemberBffClient {
      * attempt remain in the customer BFF stores.
      */
     beginAccountCenterHandoff<TApplicationData>(input: {
-        readonly intent: XKOVAAccountCenterIntent;
+        readonly intent: XKOVAAccountCenterStartIntent;
         readonly browserOrigin: string;
         readonly returnUri: string;
         /** Exact-origin application screen to restore, persisted only by the BFF. */
@@ -439,7 +460,22 @@ export declare class XKOVAMemberBffClient {
         readonly expectedState: string;
         readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
         readonly sessionStore: XKOVAMemberSessionStore<TApplicationData>;
+        /**
+         * Recover an already consumed provider code durably if this process stops or staging fails.
+         * XKOVA stages the returned proof before its own exchange, but cannot atomically commit a provider result.
+         */
         readonly exchangeProviderCode: (input: XKOVAMemberProviderCodeExchangeInput) => XKOVAMemberProviderCodeExchangeResult | Promise<XKOVAMemberProviderCodeExchangeResult>;
+        /**
+         * Optional OIDC enrollment, invoked only after the validated provider proof
+         * is durably staged. Validate/extract its exact subject on your backend and
+         * call enrollExternalMember with this stable idempotency key. Do not perform
+         * enrollment RPC inside exchangeProviderCode: failure there can otherwise
+         * require reusing an already-consumed provider authorization code.
+         */
+        readonly ensureMemberEnrollment?: (input: {
+            readonly proofToken: string;
+            readonly idempotencyKey: string;
+        }) => Promise<XKOVAExternalMemberEnrollment>;
         readonly applicationData: TApplicationData;
         readonly applicationSessionSeconds?: number;
     }): Promise<EstablishedXKOVAMemberSession<TApplicationData>>;
@@ -469,6 +505,11 @@ export declare class XKOVAMemberBffClient {
     resolveResources<TApplicationData>(input: {
         readonly reference: string;
         readonly sessionStore: XKOVAMemberSessionStore<TApplicationData>;
+        /**
+         * Defaults true. Set false only when the bound resource request executes
+         * immediately and therefore performs the same exact-session validation.
+         */
+        readonly validateWithXkova?: boolean;
     }): Promise<{
         readonly session: StoredXKOVAMemberSession<TApplicationData>;
         readonly resources: XKOVAMemberResources;
@@ -492,8 +533,6 @@ export declare class XKOVAMemberBffClient {
     private readSessionMaterial;
     private requestSignal;
 }
-/** Only confirmed admission rejections may release a customer's pending demo reservation. */
-export declare function isDefinitiveXKOVASandboxDemoAdmissionFailure(error: unknown): boolean;
 export declare function projectXKOVAMemberSession(session: XKOVAMemberContext): XKOVABrowserMemberProjection;
 export declare function serializeXKOVAMemberSessionCookie(input: {
     readonly cookieName: string;

package/dist/member-bff.js

@@ -1,5 +1,6 @@
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { XKOVAApiError } from './errors.js';
+import { isAllowedProtocol } from './url.js';
 import { XKOVAClient } from './client.js';
 import { XKOVAMemberResources } from './member-resources.js';
 import { XKOVAMemberActionIntents, } from './member-action-intents.js';
@@ -78,6 +79,48 @@ export class XKOVAMemberBffClient {
             proof_token: proofToken,
         }), 'proof exchange');
     }
+    /**
+     * BFF-only membership provisioning after validating the provider identity or
+     * resolving it from a trusted directory. This creates no login session or
+     * wallet and does not substitute for genuine provider-proof verification.
+     * Save one idempotencyKey before the first attempt and retain the same subject,
+     * selector and observed configuration version during response-loss recovery.
+     */
+    async enrollExternalMember(input) {
+        if (typeof input.externalSub !== 'string' ||
+            input.externalSub.length === 0 ||
+            input.externalSub.length > 512 ||
+            /\u0000/u.test(input.externalSub) ||
+            !/\S/u.test(input.externalSub))
+            throw new TypeError('externalSub must be an exact nonempty provider subject of at most 512 characters');
+        assertPositiveInteger(input.applicationConfigVersion, 'applicationConfigVersion');
+        if (!/^[A-Za-z0-9._:-]{1,255}$/u.test(input.idempotencyKey))
+            throw new TypeError('idempotencyKey must be a retained opaque operation key of at most 255 characters');
+        const value = await this.recoverablePostJson('/member-auth/enrollments', {
+            publishable_key: this.options.publishableKey,
+            application_config_version: input.applicationConfigVersion,
+            external_sub: input.externalSub,
+        }, undefined, input.idempotencyKey);
+        const result = requireObject(value, 'external member enrollment');
+        const applicationId = requireString(result, 'application_id', 'external member enrollment');
+        assertUuid(applicationId, 'enrollment application id');
+        const publishableKey = requireString(result, 'publishable_key', 'external member enrollment');
+        const applicationConfigVersion = requirePositiveInteger(result, 'application_config_version', 'external member enrollment');
+        const providerNamespace = requireString(result, 'provider_namespace', 'external member enrollment');
+        if (publishableKey !== this.options.publishableKey ||
+            applicationConfigVersion !== input.applicationConfigVersion ||
+            !providerNamespace.startsWith('oidc:') ||
+            typeof result.created !== 'boolean')
+            throw new Error('XKOVA external member enrollment returned a different application or configuration');
+        return {
+            accountHolderId: requireString(result, 'account_holder_id', 'external member enrollment'),
+            applicationId,
+            publishableKey,
+            applicationConfigVersion,
+            providerNamespace,
+            created: result.created,
+        };
+    }
     async refresh(refreshToken, options) {
         if (refreshToken.length < 20) {
             throw new TypeError('member refresh token is malformed');
@@ -195,54 +238,6 @@ export class XKOVAMemberBffClient {
             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
@@ -354,7 +349,7 @@ export class XKOVAMemberBffClient {
     async beginAccountCenterHandoff(input) {
         const browserOrigin = normalizeBrowserOrigin(input.browserOrigin);
         const returnUri = normalizeCallbackUri(input.returnUri);
-        assertAccountCenterIntent(input.intent);
+        assertAccountCenterStartIntent(input.intent);
         const applicationReturnUri = input.applicationReturnUri === undefined
             ? undefined
             : normalizeApplicationReturnUri(input.applicationReturnUri, browserOrigin);
@@ -560,7 +555,7 @@ export class XKOVAMemberBffClient {
                 clientFingerprint: this.clientFingerprint,
                 codeVerifier,
                 redirectUri: returnUri,
-                exchangeAttemptId: generateXKOVAMemberOperationAttemptId(),
+                exchangeAttemptId: randomUUID(),
                 sessionReference: input.sessionReference,
                 intent: 'action',
                 ...(applicationReturnUri !== undefined && { applicationReturnUri }),
@@ -583,15 +578,15 @@ export class XKOVAMemberBffClient {
                 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') {
+                if (method === 'hosted_passkey' || method === 'xkova_webauthn') {
                     const authorizationUrl = normalizeHostedAuthorizationUrl(requireString(object, 'authorization_url', 'member action authorization start'));
                     await input.transactionStore.replace(stateHash, {
                         ...transaction,
-                        actionAuthorization: { method: 'hosted_passkey' },
+                        actionAuthorization: { method },
                         expiresAt: expiresAtMillis,
                     });
                     return {
-                        authorizationMethod: 'hosted_passkey',
+                        authorizationMethod: method,
                         authorizationUrl,
                         state,
                         expiresAt,
@@ -653,7 +648,7 @@ export class XKOVAMemberBffClient {
         if (initial?.completionMode === 'account_center_result_code' &&
             initial.status === 'pending' &&
             initial.intent === 'action' &&
-            initial.actionAuthorization?.method === 'hosted_passkey') {
+            ['hosted_passkey', 'xkova_webauthn'].includes(initial.actionAuthorization?.method ?? '')) {
             const completion = await this.completeAccountCenterHandoff(input);
             if (!completion.signingExchangeCode || !completion.signingUrl) {
                 throw new Error('XKOVA Hosted action completion omitted its signing projection');
@@ -806,6 +801,10 @@ export class XKOVAMemberBffClient {
             if (transaction.completionMode !== 'provider_proof') {
                 throw new Error('member authorization transaction is not a provider-proof flow');
             }
+            if (input.ensureMemberEnrollment &&
+                transaction.status === 'pending' &&
+                transaction.proofKind !== 'oidc')
+                throw new Error('external member enrollment is available only for an OIDC proof flow');
             if (!sameCallback(callback, new URL(transaction.redirectUri))) {
                 throw new Error('member authorization callback does not match its redirect URI');
             }
@@ -868,6 +867,14 @@ export class XKOVAMemberBffClient {
                     },
                 });
             }
+            const enrollment = input.ensureMemberEnrollment
+                ? await input.ensureMemberEnrollment({
+                    proofToken,
+                    idempotencyKey: `enroll:${transaction.exchangeAttemptId}`,
+                })
+                : undefined;
+            if (enrollment && enrollment.publishableKey !== this.options.publishableKey)
+                throw new Error('member enrollment does not belong to this application');
             const established = await this.persistSessionWithAttempt({
                 proofToken,
                 attemptId: transaction.exchangeAttemptId,
@@ -875,6 +882,7 @@ export class XKOVAMemberBffClient {
                 sessionStore: input.sessionStore,
                 applicationData,
                 applicationExpiresAt,
+                ...(enrollment !== undefined && { expectedAccountHolderId: enrollment.accountHolderId }),
             });
             await input.transactionStore.replace(stateHash, {
                 status: 'completed',
@@ -976,6 +984,11 @@ export class XKOVAMemberBffClient {
                         await input.sessionStore.replace(input.reference, active);
                     }
                     const rotated = await this.refresh(current.refreshToken, { attemptId });
+                    if (rotated.sessionId !== current.sessionId ||
+                        rotated.accountHolderId !== current.accountHolderId ||
+                        rotated.providerSubject !== current.providerSubject) {
+                        throw new Error('XKOVA member context changed during refresh');
+                    }
                     const { pendingRefreshAttemptId: _completed, ...withoutPending } = active;
                     active = {
                         ...withoutPending,
@@ -1061,6 +1074,9 @@ export class XKOVAMemberBffClient {
         const material = await this.exchangeProof(input.proofToken, {
             attemptId: input.attemptId,
         });
+        if (input.expectedAccountHolderId !== undefined &&
+            material.accountHolderId !== input.expectedAccountHolderId)
+            throw new Error('XKOVA proof exchange returned a different member from the enrolled identity');
         return this.persistSessionMaterial({
             material,
             reference: input.reference,
@@ -1111,8 +1127,7 @@ export class XKOVAMemberBffClient {
             ...(idempotencyKey !== undefined && { idempotencyKey }),
         });
     }
-    async recoverablePostJson(path, body, sessionId) {
-        const idempotencyKey = generateIdempotencyKey();
+    async recoverablePostJson(path, body, sessionId, idempotencyKey = generateIdempotencyKey()) {
         try {
             return await this.postJson(path, body, sessionId, idempotencyKey);
         }
@@ -1210,14 +1225,6 @@ export class XKOVAMemberBffClient {
             : 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,
@@ -1339,8 +1346,8 @@ function normalizeApiBaseUrl(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');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('XKOVA member BFF baseUrl must use HTTPS or loopback HTTP');
     }
     const pathname = url.pathname.replace(/\/+$/, '');
     if (pathname !== '' && pathname !== '/v1') {
@@ -1353,16 +1360,15 @@ function normalizeCallbackUri(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');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('member authorization redirectUri must use HTTPS or loopback 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');
+    if (url.origin !== value || !isAllowedProtocol(url)) {
+        throw new TypeError('member authorization browserOrigin must be an exact HTTPS or loopback origin');
     }
     return value;
 }
@@ -1372,18 +1378,14 @@ function normalizeApplicationReturnUri(value, browserOrigin) {
         url.username ||
         url.password ||
         url.hash ||
-        (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))) {
+        !isAllowedProtocol(url)) {
         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')))) {
+    if (url.username || url.password || url.hash || !isAllowedProtocol(url)) {
         throw new Error('XKOVA member Hosted authorization URL must use HTTPS or loopback HTTP without credentials or a fragment');
     }
     return url.toString();
@@ -1518,8 +1520,8 @@ function assertHostedAuthorizationResultCode(value) {
         throw new TypeError('member Hosted authorization result code is malformed');
     }
 }
-function assertAccountCenterIntent(value) {
-    if (!new Set(['security', 'sessions', 'wallet_readiness', 'action']).has(value)) {
+function assertAccountCenterStartIntent(value) {
+    if (!new Set(['security', 'sessions', 'wallet_readiness']).has(value)) {
         throw new TypeError('Account Center intent is unsupported');
     }
 }