@xkova/sdk 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -124,6 +124,10 @@ const balance = await xkova.accountHolders.selfBalance({
 });
 ```
 
+`selfBalance` can return a partial answer. A chain not known right now has no
+entries in `balances` and a null `through_block` in `data_freshness`, so check
+that before treating a missing token as zero or adding balances together.
+
 ## Register a Hosted Auth application
 
 Hosted Auth provides an optional XKOVA-hosted sign-in flow. Register an
@@ -216,6 +220,26 @@ proofs, and manages session refresh and logout. Implement its session,
 authorization-transaction, and direct proof-exchange store contracts in your
 own database. It does not include a web framework or database adapter.
 
+`runExclusive` is an exclusivity boundary, not an all-or-nothing SQL
+transaction. Every awaited `put`, `replace` and `delete` must commit before
+returning, and remain committed if later callback work throws. Wrapping the
+whole callback in a rollback transaction can erase a staged proof after its
+one-time provider code was consumed. The same rule protects refresh-attempt
+checkpoints. Reconcile an uncertain write acknowledgement using the exact
+record and attempt identity, rather than starting a new operation.
+
+The package includes [a PostgreSQL checkpoint-store example](examples/postgres-checkpoint-store.mjs)
+and its [application-owned table definition](examples/postgres-checkpoints.sql).
+Install `pg` in your backend and apply the table definition through your own
+migration process. Instantiate separate stores with namespaces such as
+`authorization`, `sessions` and `exchange`, one shared pool and an existing
+32-byte application encryption key. The example uses session advisory locks
+across replicas, independent autocommit checkpoints, authenticated encryption
+bound to namespace/reference, exact replacement without upsert, and connection
+discard when lock release is uncertain. Do not use a transaction-pooling proxy
+for session locks. Own key rotation, pool deadlines and expired-record cleanup
+in your application; do not log records or encryption material.
+
 Authorization, Account Center, and action transactions expire within ten
 minutes of starting the request, or at the server's expiry if sooner. Late,
 expired, or excessively long-lived responses are rejected. Keep your BFF's
@@ -246,6 +270,51 @@ To exchange a proof without a browser callback, call `establishSession` with an
 `exchangeId`. Persist that ID before the first attempt and reuse it on retries.
 The store serializes attempts and preserves the exchange and session references.
 
+### Enroll an external identity-provider member
+
+For a registered OIDC connection, the confidential backend can call
+`memberAuth.enrollExternalMember({ externalSub, applicationConfigVersion,
+idempotencyKey })`. Use the exact opaque subject from a fully verified provider
+proof, the final read-back application configuration version, and one persisted
+operation key. Never link by email. The API derives issuer namespace, tenant,
+workspace and application from the registered connection and its bound
+`member_auth` API principal. The header selector and body selector must match.
+An existing issuer/subject membership is returned without replacing its identity,
+status or wallet bindings. A held or closed member remains held or closed.
+
+Enrollment creates or finds a membership, not an authenticated session or wallet.
+The normal nonce-bound provider-proof exchange remains required. For callback
+flows use `completeAuthorizationCallback`'s optional `ensureMemberEnrollment`
+hook. It runs after the one-time provider proof is durably staged, with a stable
+`idempotencyKey` preserved across retries. Verify the staged proof's signature,
+issuer, audience, algorithm, expiry and nonce, then call `enrollExternalMember`
+with its exact `sub`. Return that result from the hook. The helper checks that
+the resulting authenticated session resolves to the enrolled account holder.
+Do not put a fallible enrollment call inside `exchangeProviderCode`, before
+the provider result has been staged. A version conflict requires reviewing the
+changed registration and starting a new authorization flow, not blind retries.
+
+```ts
+const completion = await memberAuth.completeAuthorizationCallback({
+  ...callbackInput,
+  ensureMemberEnrollment: async ({ proofToken, idempotencyKey }) => {
+    // This application function performs full JOSE and exact nonce validation.
+    const verified = await verifyRegisteredProviderProof(proofToken);
+    return memberAuth.enrollExternalMember({
+      externalSub: verified.sub,
+      applicationConfigVersion: registration.config_version,
+      idempotencyKey,
+    });
+  },
+});
+```
+
+The verifier and `registration` are application prerequisites in this example,
+not SDK-provided provider validation or discovery functions. The public endpoint
+is `POST /v1/member-auth/enrollments`; it accepts no caller-selected account
+holder, tenant, issuer namespace, email or permissions. Enrollment alone never
+qualifies fresh action assurance, signing authority or settlement.
+
 ### Account Center and action callbacks
 
 Account Center accepts a same-origin `applicationReturnUri` and preserves it

package/dist/generated/types.d.ts

@@ -44,7 +44,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Confirm a brand logo upload (magic-byte validated) */
+        /** Confirm this tenant's brand logo upload */
         post: operations["confirmBrandingLogo"];
         /** Remove the brand logo */
         delete: operations["deleteBrandingLogo"];
@@ -3029,6 +3029,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/member-auth/enrollments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Enroll an external member for the registered identity provider */
+        post: operations["enrollExternalMember"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tenant/member-auth/applications": {
         parameters: {
             query?: never;
@@ -3091,7 +3108,7 @@ export interface paths {
             cookie?: never;
         };
         get?: never;
-        /** Register or update the calling backend's BYO OIDC application */
+        /** Register or update the calling backend's member identity provider */
         put: operations["configureMemberAuthOidcApplication"];
         post?: never;
         delete?: never;
@@ -3702,6 +3719,8 @@ export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
         TenantBranding: {
+            logo_upload_limits: components["schemas"]["LogoUploadLimits"];
+            has_logo_override: boolean;
             resolved: {
                 brand_name: string;
                 legal_name: string;
@@ -4038,8 +4057,10 @@ export interface components {
         };
         LedgerList: components["schemas"]["CursorPage"] & {
             data?: components["schemas"]["LedgerEntry"][];
+            data_freshness: components["schemas"]["DataFreshness"][];
         };
         WalletBalanceResult: {
+            data_freshness: components["schemas"]["DataFreshness"][];
             chain_id: number;
             wallet: string;
             token: string;
@@ -4308,6 +4329,7 @@ export interface components {
             has_more: boolean;
         };
         EscrowCreate: {
+            notify_recipient?: boolean;
             recipient_ref: string;
             /** Format: uuid */
             token_deployment_id: string;
@@ -4318,6 +4340,8 @@ export interface components {
             metadata?: Record<string, never>;
         };
         EscrowCreateResponse: {
+            /** @enum {string} */
+            notification_status?: "queued" | "sent" | "failed" | "cancelled";
             escrow: components["schemas"]["Escrow"];
             claim_token: string;
             /** Format: uri */
@@ -4327,6 +4351,8 @@ export interface components {
             signing_expires_at?: components["schemas"]["TimestampUtc"] | null;
         };
         Escrow: {
+            /** @enum {string} */
+            notification_status?: "queued" | "sent" | "failed" | "cancelled";
             id: components["schemas"]["EscrowId"];
             chain: components["schemas"]["ChainDescriptor"];
             fingerprint: string;
@@ -4342,6 +4368,7 @@ export interface components {
             on_chain_payment_id?: string | null;
             create_tx_hash?: string | null;
             release_tx_hash?: string | null;
+            data_freshness?: components["schemas"]["DataFreshness"][];
             fee_accruals?: components["schemas"]["EscrowFeeAccrual"][];
             net_amount?: components["schemas"]["Money"] | null;
             claimed_at?: components["schemas"]["TimestampUtc"] | null;
@@ -4368,6 +4395,10 @@ export interface components {
             has_more: boolean;
         };
         PaymentRequestCreate: {
+            notify_recipient?: boolean;
+            require_member_payer?: boolean;
+            /** Format: uri */
+            notification_return_uri?: string;
             payer: {
                 account_holder_id?: components["schemas"]["AccountHolderId"] | null;
                 /** Format: email */
@@ -4380,6 +4411,8 @@ export interface components {
             memo?: string | null;
         };
         PaymentRequest: {
+            /** @enum {string} */
+            notification_status?: "queued" | "sent" | "failed" | "cancelled";
             id?: components["schemas"]["PaymentRequestId"];
             requester_id?: components["schemas"]["AccountHolderId"];
             payer_id?: components["schemas"]["AccountHolderId"] | null;
@@ -4466,6 +4499,9 @@ export interface components {
                 amount: string;
                 /** Format: uuid */
                 token_deployment_id: string;
+                token_address: string;
+                token_symbol: string;
+                chain: components["schemas"]["ChainDescriptor"];
                 /** @enum {string} */
                 status: "pending" | "submitted" | "settled" | "requires_review";
                 transaction_hash: string | null;
@@ -4497,6 +4533,7 @@ export interface components {
         };
         AccountHolderSelfBalance: {
             balances: components["schemas"]["AccountHolderSelfBalanceEntry"][];
+            data_freshness: components["schemas"]["DataFreshness"][];
         };
         MemberPaymentRecovery: {
             payment: components["schemas"]["Payment"];
@@ -5014,6 +5051,9 @@ export interface components {
             raw_contract: string | null;
             raw_function: string | null;
             raw_args: string[] | null;
+            failure_reason_code: string | null;
+            failure_reason_detail: string | null;
+            failure_retryable: boolean;
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -5230,6 +5270,20 @@ export interface components {
             expires_at: components["schemas"]["TimestampUtc"];
             action_readiness: components["schemas"]["MemberActionReadiness"];
         };
+        ExternalMemberEnrollment: {
+            publishable_key: string;
+            application_config_version: number;
+            external_sub: string;
+        };
+        ExternalMemberEnrollmentResult: {
+            account_holder_id: components["schemas"]["AccountHolderId"];
+            /** Format: uuid */
+            application_id: string;
+            publishable_key: string;
+            application_config_version: number;
+            provider_namespace: string;
+            created: boolean;
+        };
         MemberAuthApplicationSummary: {
             /** Format: uuid */
             id: string;
@@ -5242,6 +5296,15 @@ export interface components {
             name: string;
             /** @enum {string} */
             provider_kind: "xkova_hosted" | "oidc" | "signed_launch";
+            provider_namespace: string;
+            /** Format: uri */
+            issuer: string | null;
+            audience: string | null;
+            /** Format: uri */
+            jwks_uri: string | null;
+            allowed_jwt_algorithms: ("RS256" | "PS256" | "ES256" | "EdDSA")[];
+            /** @enum {string} */
+            proof_binding_mode: "authorization_nonce" | "server_assertion_jti";
             enrollment_mode: components["schemas"]["MemberAuthEnrollmentMode"];
             is_default: boolean;
             /** @enum {string} */
@@ -5460,6 +5523,17 @@ export interface components {
         };
         /** @example cact_1A2b3C4d5E6f7G8h9I0jK1 */
         CorporateActionId: string;
+        LogoUploadLimits: {
+            /** @example 5242880 */
+            max_bytes: number;
+            /** @example 4096 */
+            max_width: number;
+            /** @example 4096 */
+            max_height: number;
+            /** @example 32000000 */
+            max_total_frame_pixels: number;
+            content_types: ("image/png" | "image/jpeg" | "image/webp" | "image/gif")[];
+        };
         TenantBrandingTheme: {
             brand_name: string | null;
             legal_name: string | null;
@@ -5633,6 +5707,10 @@ export interface components {
             user_op_hash?: string | null;
             counterparty?: string | null;
         };
+        DataFreshness: {
+            chain_id: number;
+            through_block: string | null;
+        };
         /** @example cnt_1A2b3C4d5E6f7G8h9I0jK1 */
         ContactId: string;
         /** @example fnd_1A2b3C4d5E6f7G8h9I0jK1 */
@@ -7101,6 +7179,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getWalletBalance: {
@@ -7128,6 +7207,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     listContacts: {
@@ -8584,6 +8664,7 @@ export interface operations {
             };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getMemberPaymentRecovery: {
@@ -9856,6 +9937,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorResponse"];
                 };
             };
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getRwaDocument: {
@@ -10078,6 +10160,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     listRwaTokenHolders: {
@@ -10105,6 +10188,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     listRwaTokenInstances: {
@@ -10133,6 +10217,7 @@ export interface operations {
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
             422: components["responses"]["UnprocessableEntity"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     createRwaTokenDistribution: {
@@ -10164,6 +10249,7 @@ export interface operations {
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
             422: components["responses"]["UnprocessableEntity"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getRwaTokenDistribution: {
@@ -12366,6 +12452,37 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
         };
     };
+    enrollExternalMember: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["idempotencyKey"];
+                "X-XKOVA-Publishable-Key": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExternalMemberEnrollment"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ExternalMemberEnrollmentResult"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     listMemberAuthApplications: {
         parameters: {
             query?: {
@@ -13099,6 +13216,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorResponse"];
                 };
             };
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     listRwaAttesters: {
@@ -13253,6 +13371,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorResponse"];
                 };
             };
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     describeRwaTokenFields: {
@@ -13330,6 +13449,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorResponse"];
                 };
             };
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getRwaSchemaBinding: {
@@ -13625,6 +13745,7 @@ export interface operations {
             404: components["responses"]["NotFound"];
             409: components["responses"]["Conflict"];
             422: components["responses"]["UnprocessableEntity"];
+            503: components["responses"]["ServiceUnavailable"];
         };
     };
     getRwaCorporateAction: {

package/dist/member-bff.d.ts

@@ -34,6 +34,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 +57,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>;
@@ -169,6 +181,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 +215,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>;
@@ -321,6 +342,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>;
@@ -426,6 +459,17 @@ export declare class XKOVAMemberBffClient {
         readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
         readonly sessionStore: XKOVAMemberSessionStore<TApplicationData>;
         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>>;

package/dist/member-bff.js

@@ -79,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');
@@ -759,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');
             }
@@ -821,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,
@@ -828,6 +882,7 @@ export class XKOVAMemberBffClient {
                 sessionStore: input.sessionStore,
                 applicationData,
                 applicationExpiresAt,
+                ...(enrollment !== undefined && { expectedAccountHolderId: enrollment.accountHolderId }),
             });
             await input.transactionStore.replace(stateHash, {
                 status: 'completed',
@@ -1014,6 +1069,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,
@@ -1064,8 +1122,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);
         }

package/dist/member-resources.d.ts

@@ -52,6 +52,9 @@ export declare class XKOVAMemberResources {
             credit: {
                 amount: string;
                 token_deployment_id: string;
+                token_address: string;
+                token_symbol: string;
+                chain: import("./generated/types.js").components["schemas"]["ChainDescriptor"];
                 status: "pending" | "submitted" | "settled" | "requires_review";
                 transaction_hash: string | null;
             } | null;
@@ -64,6 +67,9 @@ export declare class XKOVAMemberResources {
             credit: {
                 amount: string;
                 token_deployment_id: string;
+                token_address: string;
+                token_symbol: string;
+                chain: import("./generated/types.js").components["schemas"]["ChainDescriptor"];
                 status: "pending" | "submitted" | "settled" | "requires_review";
                 transaction_hash: string | null;
             } | null;
@@ -103,6 +109,7 @@ export declare class XKOVAMemberResources {
         }>;
         balance: (control?: XKOVARequestControl) => Promise<{
             balances: import("./generated/types.js").components["schemas"]["AccountHolderSelfBalanceEntry"][];
+            data_freshness: import("./generated/types.js").components["schemas"]["DataFreshness"][];
         }>;
         wallets: (control?: XKOVARequestControl) => Promise<{
             data: import("./generated/types.js").components["schemas"]["Wallet"][];

package/dist/resources/account-holders.d.ts

@@ -152,6 +152,9 @@ export declare class AccountHoldersResource extends Resource {
         credit: {
             amount: string;
             token_deployment_id: string;
+            token_address: string;
+            token_symbol: string;
+            chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
             status: "pending" | "submitted" | "settled" | "requires_review";
             transaction_hash: string | null;
         } | null;
@@ -164,12 +167,16 @@ export declare class AccountHoldersResource extends Resource {
         credit: {
             amount: string;
             token_deployment_id: string;
+            token_address: string;
+            token_symbol: string;
+            chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
             status: "pending" | "submitted" | "settled" | "requires_review";
             transaction_hash: string | null;
         } | null;
     }>;
     selfBalance(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         balances: import("../generated/types.js").components["schemas"]["AccountHolderSelfBalanceEntry"][];
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
     }>;
     listSelfWallets(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         data: import("../generated/types.js").components["schemas"]["Wallet"][];

package/dist/resources/branding.d.ts

@@ -2,6 +2,8 @@ import { Resource, type ReqBody, type Query } from './base.js';
 import type { XKOVAMutationOptions } from '../client.js';
 export declare class BrandingResource extends Resource {
     get(): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -28,6 +30,8 @@ export declare class BrandingResource extends Resource {
         theme: import("../generated/types.js").components["schemas"]["TenantBrandingTheme"];
     }>;
     upsert(body: ReqBody<'upsertBranding'>, opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -94,12 +98,16 @@ export declare class BrandingResource extends Resource {
         last_synced_at: string;
         created_at: string;
     }>;
+    /** Upload bytes to the returned URL, then confirm its opaque key as the same tenant. */
     logoUploadUrl(body: ReqBody<'brandingLogoUploadUrl'>, opts?: XKOVAMutationOptions): Promise<{
         upload_url: string;
         object_key: string;
         expires_at: string;
     }>;
+    /** Publish a newly issued upload. Saved logo URLs or keys are not upload keys. */
     confirmLogo(body: ReqBody<'confirmBrandingLogo'>, opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -126,6 +134,8 @@ export declare class BrandingResource extends Resource {
         theme: import("../generated/types.js").components["schemas"]["TenantBrandingTheme"];
     }>;
     deleteLogo(opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;

package/dist/resources/branding.js

@@ -22,9 +22,11 @@ export class BrandingResource extends Resource {
     verifyEmailDomain(id, opts) {
         return this.postJson(`/branding/email-domains/${this.enc(id)}/verify`, undefined, opts);
     }
+    /** Upload bytes to the returned URL, then confirm its opaque key as the same tenant. */
     logoUploadUrl(body, opts) {
         return this.postJson('/branding/logo/upload-url', body, opts);
     }
+    /** Publish a newly issued upload. Saved logo URLs or keys are not upload keys. */
     confirmLogo(body, opts) {
         return this.postJson('/branding/logo', body, opts);
     }

package/dist/resources/escrows.d.ts

@@ -7,6 +7,7 @@ export declare class EscrowsResource extends Resource {
         has_more: boolean;
     }>;
     create(body: ReqBody<'createEscrow'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         escrow: import("../generated/types.js").components["schemas"]["Escrow"];
         claim_token: string;
         claim_url: string;
@@ -15,6 +16,7 @@ export declare class EscrowsResource extends Resource {
         signing_expires_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;
     }>;
     retrieve(id: string, query?: Query<'getEscrow'>): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id: import("../generated/types.js").components["schemas"]["EscrowId"];
         chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
         fingerprint: string;
@@ -28,6 +30,7 @@ export declare class EscrowsResource extends Resource {
         on_chain_payment_id?: string | null;
         create_tx_hash?: string | null;
         release_tx_hash?: string | null;
+        data_freshness?: import("../generated/types.js").components["schemas"]["DataFreshness"][];
         fee_accruals?: import("../generated/types.js").components["schemas"]["EscrowFeeAccrual"][];
         net_amount?: import("../generated/types.js").components["schemas"]["Money"] | null;
         claimed_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;

package/dist/resources/payment-requests.d.ts

@@ -11,6 +11,7 @@ export declare class PaymentRequestsResource extends Resource {
         has_more: boolean;
     }>;
     create(body: ReqBody<'createPaymentRequest'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -26,6 +27,7 @@ export declare class PaymentRequestsResource extends Resource {
         updated_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     retrieve(id: string): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -82,6 +84,7 @@ export declare class PaymentRequestsResource extends Resource {
         finalized_at: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;
     }>;
     cancel(id: string, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;
@@ -97,6 +100,7 @@ export declare class PaymentRequestsResource extends Resource {
         updated_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     decline(id: string, body?: ReqBody<'declinePaymentRequest'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id?: import("../generated/types.js").components["schemas"]["PaymentRequestId"];
         requester_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"];
         payer_id?: import("../generated/types.js").components["schemas"]["AccountHolderId"] | null;

package/dist/resources/tenant.d.ts

@@ -47,6 +47,12 @@ export declare class TenantResource extends Resource {
         publishable_key: string;
         name: string;
         provider_kind: "xkova_hosted" | "oidc" | "signed_launch";
+        provider_namespace: string;
+        issuer: string | null;
+        audience: string | null;
+        jwks_uri: string | null;
+        allowed_jwt_algorithms: ("RS256" | "PS256" | "ES256" | "EdDSA")[];
+        proof_binding_mode: "authorization_nonce" | "server_assertion_jti";
         enrollment_mode: import("../generated/types.js").components["schemas"]["MemberAuthEnrollmentMode"];
         is_default: boolean;
         status: "active" | "principal_disabled";
@@ -73,6 +79,12 @@ export declare class TenantResource extends Resource {
         publishable_key: string;
         name: string;
         provider_kind: "xkova_hosted" | "oidc" | "signed_launch";
+        provider_namespace: string;
+        issuer: string | null;
+        audience: string | null;
+        jwks_uri: string | null;
+        allowed_jwt_algorithms: ("RS256" | "PS256" | "ES256" | "EdDSA")[];
+        proof_binding_mode: "authorization_nonce" | "server_assertion_jti";
         enrollment_mode: import("../generated/types.js").components["schemas"]["MemberAuthEnrollmentMode"];
         is_default: boolean;
         status: "active" | "principal_disabled";
@@ -90,6 +102,9 @@ export declare class TenantResource extends Resource {
         created_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
         updated_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
+    /** Disables the exact Hosted Auth or OIDC member application. */
+    disableMemberAuthApplication(id: string, opts?: XKOVAMutationOptions): Promise<void>;
+    /** Existing Hosted Auth convenience name. */
     disableHostedApplication(id: string, opts?: XKOVAMutationOptions): Promise<void>;
     configureOidcApplication(body: ReqBody<'configureMemberAuthOidcApplication'>, opts?: XKOVAMutationOptions): Promise<{
         id: string;

package/dist/resources/tenant.js

@@ -15,9 +15,14 @@ export class TenantResource extends Resource {
     updateHostedApplication(id, body, opts) {
         return this.patchJson(`/tenant/member-auth/applications/${this.enc(id)}`, body, opts);
     }
-    disableHostedApplication(id, opts) {
+    /** Disables the exact Hosted Auth or OIDC member application. */
+    disableMemberAuthApplication(id, opts) {
         return this.deleteJson(`/tenant/member-auth/applications/${this.enc(id)}`, opts);
     }
+    /** Existing Hosted Auth convenience name. */
+    disableHostedApplication(id, opts) {
+        return this.disableMemberAuthApplication(id, opts);
+    }
     configureOidcApplication(body, opts) {
         return this.putJson('/tenant/member-auth/application', body, opts);
     }

package/dist/resources/tokenization.d.ts

@@ -186,6 +186,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -222,6 +225,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -261,6 +267,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -292,6 +301,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;
@@ -323,6 +335,9 @@ export declare class TokenizationResource extends Resource {
         raw_contract: string | null;
         raw_function: string | null;
         raw_args: string[] | null;
+        failure_reason_code: string | null;
+        failure_reason_detail: string | null;
+        failure_retryable: boolean;
         created_at: string;
         updated_at: string;
     }>;

package/dist/resources/wallets.d.ts

@@ -16,6 +16,7 @@ export declare class WalletsResource extends Resource {
         updated_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
     }>;
     balance(id: string, query: Query<'getWalletBalance'>): Promise<{
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
         chain_id: number;
         wallet: string;
         token: string;
@@ -34,6 +35,7 @@ export declare class WalletsResource extends Resource {
         has_more: boolean;
     } & {
         data?: import("../generated/types.js").components["schemas"]["LedgerEntry"][];
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
     }>;
     decommission(id: string, opts?: XKOVAMutationOptions): Promise<{
         id: import("../generated/types.js").components["schemas"]["WalletId"];

package/examples/postgres-checkpoint-store.mjs

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+/** Install pg separately. The application owns the pool, schema, retention and key rotation. */
+export class PostgresCheckpointStore {
+  #context = new AsyncLocalStorage();
+  #key;
+
+  constructor(pool, namespace, encryptionKey) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(namespace)) throw new Error('Invalid store namespace');
+    if (!Buffer.isBuffer(encryptionKey) || encryptionKey.length !== 32)
+      throw new Error('A 32-byte application encryption key is required');
+    this.pool = pool;
+    this.namespace = namespace;
+    this.#key = Buffer.from(encryptionKey);
+  }
+
+  #binding(reference) {
+    return JSON.stringify([this.namespace, reference]);
+  }
+
+  #encrypt(reference, record) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
+    cipher.setAAD(Buffer.from(this.#binding(reference)));
+    const bytes = Buffer.concat([cipher.update(JSON.stringify(record), 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), bytes]);
+  }
+
+  #decrypt(reference, bytes) {
+    if (!Buffer.isBuffer(bytes) || bytes.length < 29) throw new Error('Invalid stored envelope');
+    const decipher = createDecipheriv('aes-256-gcm', this.#key, bytes.subarray(0, 12));
+    decipher.setAAD(Buffer.from(this.#binding(reference)));
+    decipher.setAuthTag(bytes.subarray(12, 28));
+    return JSON.parse(
+      Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString('utf8'),
+    );
+  }
+
+  #db() {
+    return this.#context.getStore()?.client ?? this.pool;
+  }
+
+  async put(reference, record) {
+    await this.#db().query(
+      'INSERT INTO xkova_helper_checkpoints(namespace, reference, envelope, expires_at) VALUES ($1,$2,$3,$4)',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+  }
+
+  async get(reference) {
+    const result = await this.#db().query(
+      'SELECT envelope FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2 AND expires_at > now()',
+      [this.namespace, reference],
+    );
+    return result.rowCount ? this.#decrypt(reference, result.rows[0].envelope) : null;
+  }
+
+  async replace(reference, record) {
+    const result = await this.#db().query(
+      'UPDATE xkova_helper_checkpoints SET envelope=$3, expires_at=$4 WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+    if (result.rowCount !== 1) throw new Error('Cannot replace a missing checkpoint');
+  }
+
+  async delete(reference) {
+    await this.#db().query(
+      'DELETE FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference],
+    );
+  }
+
+  #expiry(record) {
+    const value = record.applicationExpiresAt ?? record.expiresAt;
+    if (!Number.isSafeInteger(value)) throw new Error('Invalid checkpoint expiry');
+    return new Date(value);
+  }
+
+  /** A session lock, with separate autocommit checkpoints, never an outer SQL transaction. */
+  async runExclusive(reference, work) {
+    const existing = this.#context.getStore();
+    if (existing) {
+      if (existing.reference !== reference) throw new Error('Nested references are unsupported');
+      return work();
+    }
+    const client = await this.pool.connect();
+    let locked = false;
+    let discard = false;
+    try {
+      await client.query("SET lock_timeout = '5s'");
+      await client.query("SET statement_timeout = '10s'");
+      await client.query('SELECT pg_advisory_lock(hashtextextended($1, 0))', [
+        this.#binding(reference),
+      ]);
+      locked = true;
+      return await this.#context.run({ client, reference }, work);
+    } finally {
+      try {
+        if (locked) {
+          const result = await client.query(
+            'SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS released',
+            [this.#binding(reference)],
+          );
+          if (result.rows[0]?.released !== true) throw new Error('Checkpoint lock was lost');
+        }
+        await client.query('RESET lock_timeout');
+        await client.query('RESET statement_timeout');
+      } catch {
+        // A connection with an uncertain lock must never return to the pool.
+        discard = true;
+      }
+      client.release(discard);
+    }
+  }
+}

package/examples/postgres-checkpoints.sql

@@ -0,0 +1,9 @@
+-- Apply through your application's normal migration process, to its own database.
+CREATE TABLE xkova_helper_checkpoints (
+  namespace text NOT NULL,
+  reference text NOT NULL,
+  envelope bytea NOT NULL,
+  expires_at timestamptz NOT NULL,
+  PRIMARY KEY (namespace, reference)
+);
+CREATE INDEX xkova_helper_checkpoints_expiry ON xkova_helper_checkpoints (expires_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xkova/sdk",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "TypeScript SDK for the XKOVA API.",
   "homepage": "https://docs.xkova.com",
   "repository": {
@@ -46,7 +46,8 @@
   },
   "files": [
     "dist",
-    "llms.txt"
+    "llms.txt",
+    "examples"
   ],
   "dependencies": {
     "viem": "^2.21.0"