@xkova/sdk 0.1.0-alpha.1

package/dist/member-resources.d.ts

@@ -0,0 +1,203 @@
+import type { XKOVAClient, XKOVAMutationOptions, XKOVARequestControl } from './client.js';
+import type { XKOVAMemberSessionContext } from './resources/account-holders.js';
+import type { Query, ReqBody } from './resources/base.js';
+/**
+ * Resolve these resources for each BFF request. Calls share the principal,
+ * application, and member session; API permission checks still apply.
+ * A resolved session does not grant fresh approval to sign an action.
+ */
+export declare class XKOVAMemberResources {
+    private readonly client;
+    private readonly context;
+    readonly accountHolderId: string;
+    constructor(client: XKOVAClient, context: Readonly<XKOVAMemberSessionContext>, accountHolderId: string);
+    get payments(): import("./resources/index.js").PaymentsResource;
+    get escrows(): import("./resources/index.js").EscrowsResource;
+    get ramps(): import("./resources/index.js").RampsResource;
+    get contacts(): import("./resources/index.js").ContactsResource;
+    get paymentRequests(): import("./resources/index.js").PaymentRequestsResource;
+    get wallets(): import("./resources/index.js").WalletsResource;
+    readonly self: {
+        actionReadiness: (control?: XKOVARequestControl) => Promise<{
+            authorization_method: "hosted_passkey" | "external_oidc";
+            setup_status: "passkey_required" | "recovery_acknowledgement_required" | "recovery_required" | "ready" | "externally_managed";
+            action_authorization_enabled: boolean;
+            requires_fresh_proof: true;
+            provider_status: "not_checked";
+        }>;
+        sandboxBankingContext: (control?: XKOVARequestControl) => Promise<{
+            account_holder_id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            savings_bank_account_id: string;
+            checking_bank_account_id: string;
+            pool_bank_account_id: string;
+            settlement_bank_account_id: string;
+            destination_account: import("./generated/types.js").components["schemas"]["CuPayoutAccountRef"];
+        }>;
+        verification: (control?: XKOVARequestControl) => Promise<{
+            required: boolean;
+            status: string;
+            verified_via: string | null;
+            verified_at: string | null;
+            verification_expires_at: string | null;
+            required_kinds: ("kyc" | "kyb")[];
+            sessions: {
+                kind: "kyc" | "kyb";
+                status: string;
+                vendor: string | null;
+                vendor_detail_url: string | null;
+                initiated_at: string | null;
+                completed_at: string | null;
+                expires_at: string | null;
+            }[];
+            verification_url: string | null;
+        }>;
+        balance: (control?: XKOVARequestControl) => Promise<{
+            balances: import("./generated/types.js").components["schemas"]["AccountHolderSelfBalanceEntry"][];
+        }>;
+        wallets: (control?: XKOVARequestControl) => Promise<{
+            data: import("./generated/types.js").components["schemas"]["Wallet"][];
+        }>;
+        walletReadiness: (control?: XKOVARequestControl) => Promise<{
+            status: "not_registered" | "provisioning" | "ready";
+            wallets: import("./generated/types.js").components["schemas"]["Wallet"][];
+        }>;
+        ensureWalletProvisioning: (opts?: XKOVAMutationOptions) => Promise<{
+            status: "pending" | "processing" | "reconciling" | "retry" | "ready" | "paused" | "manual_review" | "cancelled";
+        }>;
+        bankBalance: (control?: XKOVARequestControl) => Promise<{
+            currency: "USD";
+            available_balance: import("./generated/types.js").components["schemas"]["Money"];
+            current_balance: import("./generated/types.js").components["schemas"]["Money"];
+            as_of: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+        }>;
+        checkingBalance: (control?: XKOVARequestControl) => Promise<{
+            currency: "USD";
+            available_balance: import("./generated/types.js").components["schemas"]["Money"];
+            current_balance: import("./generated/types.js").components["schemas"]["Money"];
+            as_of: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+        }>;
+        bankTransactions: (query?: Query<"listAccountHolderSelfBankTransactions">, control?: XKOVARequestControl) => Promise<{
+            data: {
+                transfer_ref: string;
+                amount: string;
+                currency: string;
+                status: "pending" | "posted" | "reversed" | "rejected";
+                from_account: "savings" | "checking" | "other";
+                to_account: "savings" | "checking" | "other";
+                memo?: string | null;
+                occurred_at: string;
+            }[];
+        }>;
+        createBankTransfer: (body: ReqBody<"createAccountHolderSelfBankTransfer">, opts?: XKOVAMutationOptions) => Promise<{
+            transfer_ref: string;
+            status: "pending" | "posted" | "reversed" | "rejected";
+            as_of: string;
+        }>;
+        consents: (control?: XKOVARequestControl) => Promise<{
+            account_holder_id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            current_policies: import("./generated/types.js").components["schemas"]["CurrentPolicy"][];
+            accepted: import("./generated/types.js").components["schemas"]["Consent"][];
+            missing_consents: import("./generated/types.js").components["schemas"]["MissingConsent"][];
+            consents_current: boolean;
+            first_use_completed: boolean;
+        }>;
+        acceptConsents: (body: ReqBody<"acceptAccountHolderConsents">, opts?: XKOVAMutationOptions) => Promise<{
+            account_holder_id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            current_policies: import("./generated/types.js").components["schemas"]["CurrentPolicy"][];
+            accepted: import("./generated/types.js").components["schemas"]["Consent"][];
+            missing_consents: import("./generated/types.js").components["schemas"]["MissingConsent"][];
+            consents_current: boolean;
+            first_use_completed: boolean;
+        }>;
+        requestDataExport: (opts?: XKOVAMutationOptions) => Promise<{
+            id: import("./generated/types.js").components["schemas"]["DataExportId"];
+            account_holder_id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            state: "queued" | "processing" | "ready" | "expired" | "failed";
+            signed_url: string | null;
+            url_expires_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            requested_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            started_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            completed_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            failure_reason: string | null;
+        }>;
+        dataExport: (id: string, control?: XKOVARequestControl) => Promise<{
+            id: import("./generated/types.js").components["schemas"]["DataExportId"];
+            account_holder_id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            state: "queued" | "processing" | "ready" | "expired" | "failed";
+            signed_url: string | null;
+            url_expires_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            requested_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            started_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            completed_at: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            failure_reason: string | null;
+        }>;
+        transactions: (query?: Query<"listAccountHolderSelfTransactions">, control?: XKOVARequestControl) => Promise<{
+            data: import("./generated/types.js").components["schemas"]["AccountHolderSelfTransaction"][];
+            next_cursor: string | null;
+            has_more: boolean;
+        }>;
+        avatar: () => Promise<{
+            url: string | null;
+        }>;
+        uploadAvatar: (image: Blob, control?: XKOVARequestControl) => Promise<{
+            url: string | null;
+        }>;
+        deleteAvatar: (opts?: XKOVAMutationOptions) => Promise<{
+            id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            tenant_id?: string;
+            state: "active" | "held" | "closed" | "closed_uncooperative" | "provisioning_failed";
+            state_reason?: string | null;
+            state_changed_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            tier: "tier_1" | "tier_2";
+            tier_2_uplift_status?: "not_requested" | "pending" | "passed" | "failed";
+            first_use_completed: boolean;
+            cip_payload?: {
+                name_hash?: string;
+                dob_hash?: string;
+                id_hash?: string;
+                address_hash?: string;
+            } | null;
+            cip_accepted_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            merchant_role_state?: "none" | "pending_review" | "approved" | "rejected" | "revoked";
+            auto_save_contacts?: boolean;
+            created_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            updated_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            email?: string | null;
+            first_name?: string | null;
+            last_name?: string | null;
+            phone?: string | null;
+            avatar_url?: string | null;
+        }>;
+        confirmAvatar: (body: ReqBody<"confirmAccountHolderAvatar">, opts?: XKOVAMutationOptions) => Promise<{
+            id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            tenant_id?: string;
+            state: "active" | "held" | "closed" | "closed_uncooperative" | "provisioning_failed";
+            state_reason?: string | null;
+            state_changed_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            tier: "tier_1" | "tier_2";
+            tier_2_uplift_status?: "not_requested" | "pending" | "passed" | "failed";
+            first_use_completed: boolean;
+            cip_payload?: {
+                name_hash?: string;
+                dob_hash?: string;
+                id_hash?: string;
+                address_hash?: string;
+            } | null;
+            cip_accepted_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            merchant_role_state?: "none" | "pending_review" | "approved" | "rejected" | "revoked";
+            auto_save_contacts?: boolean;
+            created_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            updated_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            email?: string | null;
+            first_name?: string | null;
+            last_name?: string | null;
+            phone?: string | null;
+            avatar_url?: string | null;
+        }>;
+        presignAvatarUpload: (body: ReqBody<"presignAccountHolderAvatarUpload">, opts?: XKOVAMutationOptions) => Promise<{
+            upload_url: string;
+            object_key: string;
+            expires_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+        }>;
+    };
+}

package/dist/member-resources.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve these resources for each BFF request. Calls share the principal,
+ * application, and member session; API permission checks still apply.
+ * A resolved session does not grant fresh approval to sign an action.
+ */
+export class XKOVAMemberResources {
+    client;
+    context;
+    accountHolderId;
+    constructor(client, context, accountHolderId) {
+        this.client = client;
+        this.context = context;
+        this.accountHolderId = accountHolderId;
+    }
+    get payments() {
+        return this.client.payments;
+    }
+    get escrows() {
+        return this.client.escrows;
+    }
+    get ramps() {
+        return this.client.ramps;
+    }
+    get contacts() {
+        return this.client.contacts;
+    }
+    get paymentRequests() {
+        return this.client.paymentRequests;
+    }
+    get wallets() {
+        return this.client.wallets;
+    }
+    self = {
+        actionReadiness: (control) => this.client.accountHolders.selfActionReadiness({ ...this.context, accountHolderId: this.accountHolderId }, control),
+        sandboxBankingContext: (control) => this.client.accountHolders.selfSandboxBankingContext(this.context, control),
+        verification: (control) => this.client.accountHolders.selfVerification(this.context, control),
+        balance: (control) => this.client.accountHolders.selfBalance(this.context, control),
+        wallets: (control) => this.client.accountHolders.listSelfWallets(this.context, control),
+        walletReadiness: (control) => this.client.accountHolders.selfWalletReadiness(this.context, control),
+        ensureWalletProvisioning: (opts) => this.client.accountHolders.ensureSelfWalletProvisioning(this.context, opts),
+        bankBalance: (control) => this.client.accountHolders.selfBankBalance(this.context, control),
+        checkingBalance: (control) => this.client.accountHolders.selfCheckingBalance(this.context, control),
+        bankTransactions: (query, control) => this.client.accountHolders.listSelfBankTransactions(this.context, query, control),
+        createBankTransfer: (body, opts) => this.client.accountHolders.createSelfBankTransfer(this.context, body, opts),
+        consents: (control) => this.client.accountHolders.selfConsentState(this.context, control),
+        acceptConsents: (body, opts) => this.client.accountHolders.acceptSelfConsents(this.context, body, opts),
+        requestDataExport: (opts) => this.client.accountHolders.requestSelfDataExport(this.context, opts),
+        dataExport: (id, control) => this.client.accountHolders.selfDataExport(this.context, id, control),
+        transactions: (query, control) => this.client.accountHolders.listSelfTransactions(this.context, query, control),
+        avatar: () => this.client.accountHolders.avatarUrl(this.accountHolderId),
+        uploadAvatar: (image, control) => this.client.accountHolders.uploadAvatar(this.accountHolderId, image, control),
+        deleteAvatar: (opts) => this.client.accountHolders.deleteAvatar(this.accountHolderId, opts),
+        confirmAvatar: (body, opts) => this.client.accountHolders.confirmAvatar(this.accountHolderId, body, opts),
+        presignAvatarUpload: (body, opts) => this.client.accountHolders.presignAvatarUpload(this.accountHolderId, body, opts),
+    };
+}

package/dist/request-signing.d.ts

@@ -0,0 +1,23 @@
+export type XKOVARequestSigningAlgorithm = 'ecdsa-p256-sha256' | 'ed25519' | 'rsa-pss-sha256';
+export interface XKOVARequestSignInput {
+    /** Exact RFC 9421 signature base bytes. */
+    readonly data: Uint8Array;
+    /** Algorithm registered for this credential. */
+    readonly algorithm: XKOVARequestSigningAlgorithm;
+    /** XKOVA signing-credential UUID serialized as the RFC 9421 keyid. */
+    readonly credentialId: string;
+}
+/**
+ * Asymmetric signer owned by the customer server.
+ *
+ * The callback may delegate to a KMS, HSM, or local key provider. It must
+ * return the signature format registered with XKOVA: 64-byte IEEE P1363 for
+ * P-256, 64-byte Ed25519, or RSA-PSS-SHA256 with a 32-byte salt.
+ */
+export interface XKOVARequestSigner {
+    credentialId: string;
+    algorithm: XKOVARequestSigningAlgorithm;
+    sign(input: XKOVARequestSignInput): Uint8Array | Promise<Uint8Array>;
+    /** Signature lifetime from 30 through 60 seconds. Defaults to 45. */
+    lifetimeSeconds?: number;
+}

package/dist/request-signing.js

@@ -0,0 +1,112 @@
+import { createHash, randomBytes } from 'node:crypto';
+const SIGNATURE_LABEL = 'xkova';
+const SIGNATURE_TAG = 'xkova-production-mutation-v1';
+const DEFAULT_LIFETIME_SECONDS = 45;
+const MIN_LIFETIME_SECONDS = 30;
+const MAX_LIFETIME_SECONDS = 60;
+const BASE_COMPONENTS = ['@method', '@authority', '@path', '@query', 'authorization'];
+const CONDITIONAL_HEADERS = [
+    'content-digest',
+    'content-type',
+    'idempotency-key',
+    'x-member-session-id',
+    'x-xkova-publishable-key',
+    'x-account-holder-id',
+    'x-sender-wallet-id',
+    'x-sandbox-scenario',
+];
+/** @internal */
+export function xkovaContentDigest(body) {
+    return `sha-256=:${createHash('sha256').update(body).digest('base64')}:`;
+}
+/** @internal */
+export function validateXKOVARequestSigner(signer) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(signer.credentialId)) {
+        throw new Error('XKOVA request signer credentialId must be a UUID');
+    }
+    if (signer.algorithm !== 'ecdsa-p256-sha256' &&
+        signer.algorithm !== 'ed25519' &&
+        signer.algorithm !== 'rsa-pss-sha256') {
+        throw new Error(`Unsupported XKOVA request-signing algorithm: ${String(signer.algorithm)}`);
+    }
+    if (typeof signer.sign !== 'function') {
+        throw new Error('XKOVA request signer requires a sign callback');
+    }
+    const lifetime = signer.lifetimeSeconds ?? DEFAULT_LIFETIME_SECONDS;
+    if (!Number.isInteger(lifetime) ||
+        lifetime < MIN_LIFETIME_SECONDS ||
+        lifetime > MAX_LIFETIME_SECONDS) {
+        throw new Error('XKOVA request signer lifetimeSeconds must be an integer from 30 through 60');
+    }
+}
+/** @internal */
+export async function signXKOVARequest(input) {
+    validateXKOVARequestSigner(input.signer);
+    const components = requiredComponents(input.headers, input.body.byteLength > 0);
+    const created = Math.floor(Date.now() / 1000);
+    const expires = created + (input.signer.lifetimeSeconds ?? DEFAULT_LIFETIME_SECONDS);
+    const nonce = randomBytes(18).toString('base64url');
+    const serializedParams = `(${components.map((component) => `"${component}"`).join(' ')})` +
+        `;created=${created};expires=${expires};nonce="${nonce}"` +
+        `;keyid="${input.signer.credentialId}"` +
+        `;tag="${SIGNATURE_TAG}"`;
+    const signatureInput = `${SIGNATURE_LABEL}=${serializedParams}`;
+    const lines = components.map((component) => {
+        const value = componentValue(component, input);
+        if (value === undefined) {
+            throw new Error(`XKOVA request-signing component is missing: ${component}`);
+        }
+        return `"${component}": ${value}`;
+    });
+    lines.push(`"@signature-params": ${serializedParams}`);
+    const data = new TextEncoder().encode(lines.join('\n'));
+    const returned = await input.signer.sign({
+        data,
+        algorithm: input.signer.algorithm,
+        credentialId: input.signer.credentialId,
+    });
+    if (!(returned instanceof Uint8Array)) {
+        throw new Error('XKOVA request signer must return Uint8Array signature bytes');
+    }
+    const signature = Uint8Array.from(returned);
+    assertSignatureEncoding(input.signer.algorithm, signature);
+    return {
+        signatureInput,
+        signature: `${SIGNATURE_LABEL}=:${Buffer.from(signature).toString('base64')}:`,
+    };
+}
+function requiredComponents(headers, bodyPresent) {
+    const components = [...BASE_COMPONENTS];
+    for (const header of CONDITIONAL_HEADERS) {
+        if (headers.has(header) ||
+            (bodyPresent && (header === 'content-digest' || header === 'content-type'))) {
+            components.push(header);
+        }
+    }
+    return components;
+}
+function componentValue(component, input) {
+    switch (component) {
+        case '@method':
+            return input.method.toUpperCase();
+        case '@authority':
+            return input.url.host;
+        case '@path':
+            return input.url.pathname;
+        case '@query':
+            return input.url.search || '?';
+        default:
+            return input.headers.get(component) ?? undefined;
+    }
+}
+function assertSignatureEncoding(algorithm, signature) {
+    if (signature.byteLength === 0) {
+        throw new Error('XKOVA request signer returned an empty signature');
+    }
+    if (algorithm === 'ecdsa-p256-sha256' && signature.byteLength !== 64) {
+        throw new Error('P-256 request signatures must use 64-byte IEEE P1363 encoding');
+    }
+    if (algorithm === 'ed25519' && signature.byteLength !== 64) {
+        throw new Error('Ed25519 request signatures must be 64 bytes');
+    }
+}