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

package/dist/resources/workflows.js

@@ -1,33 +1,56 @@
 const DEFAULT_POLL = { attempts: 30, intervalMs: 2000 };
-const SUCCESS = new Set(['confirmed', 'completed', 'settled', 'succeeded', 'deployed', 'active']);
-const FAILURE = new Set(['failed', 'reverted', 'cancelled', 'canceled', 'expired', 'rejected']);
+const PENDING_OPERATION = new Set(['pending_sign', 'submission_pending', 'relayed']);
+const PENDING_TOKEN = new Set(['pending_deploy', 'awaiting_admin_setup']);
 export class WorkflowClient {
     client;
     constructor(client) {
         this.client = client;
     }
     async tokenDeploy(standard, body, opts = {}) {
+        const poll = pollOptions(opts.poll, opts.signal);
+        validatePoll(poll);
+        if (!['erc20', 'erc721', 'erc1155'].includes(standard)) {
+            throw new TypeError('Unsupported token standard');
+        }
+        poll.signal?.throwIfAborted();
+        const mutation = { ...opts, ...(poll.signal !== undefined && { signal: poll.signal }) };
         const t = this.client.tokenization;
         const deployed = standard === 'erc20'
-            ? await t.deployErc20(body, opts)
+            ? await t.deployErc20(body, mutation)
             : standard === 'erc721'
-                ? await t.deployErc721(body, opts)
-                : await t.deployErc1155(body, opts);
+                ? await t.deployErc721(body, mutation)
+                : await t.deployErc1155(body, mutation);
         const tokenId = readString(deployed, 'customer_token_id');
-        return pollEntity(() => t.retrieve(tokenId), pollOptions(opts.poll, opts.signal), 'token');
+        const operationId = readString(deployed, 'operation_id');
+        return pollEntity(() => t.retrieve(tokenId, poll), poll, tokenId, operationId);
     }
-    /** Mint to a holder and wait for confirmation. */
+    /** Submit once and observe the exact mint operation. Required human signing remains separate. */
     async tokenMint(tokenId, body, opts = {}) {
-        await this.client.tokenization.mint(tokenId, body, opts);
-        return pollEntity(() => this.client.tokenization.retrieve(tokenId), pollOptions(opts.poll, opts.signal), 'token');
+        const poll = pollOptions(opts.poll, opts.signal);
+        validatePoll(poll);
+        poll.signal?.throwIfAborted();
+        const minted = await this.client.tokenization.mint(tokenId, body, {
+            ...opts,
+            ...(poll.signal !== undefined && { signal: poll.signal }),
+        });
+        const operationId = readString(minted, 'operation_id');
+        await pollOperation(this.client, tokenId, operationId, 'mint', poll);
+        poll.signal?.throwIfAborted();
+        const token = await this.client.tokenization.retrieve(tokenId, poll);
+        poll.signal?.throwIfAborted();
+        if (readString(token, 'id') !== tokenId)
+            throw new Error('API returned a different customer token');
+        return token;
     }
     /**
-     * Off-ramp: resolve the burn address and create the request. The member then
-     * burns stablecoin to the returned address out-of-band; poll
-     * `client.ramps.getOffRamp(id)` for settlement.
+     * Resolve the registered burn address and create the caller's burn-backed
+     * request. This helper does not submit a transaction or establish settlement;
+     * poll `client.ramps.getOffRamp(id)` for the resulting request's state.
      */
     async offRampInitiate(chainRef, body, opts = {}) {
-        const burnAddress = await this.client.ramps.offRampBurnAddress({ chain_ref: chainRef });
+        opts.signal?.throwIfAborted();
+        const burnAddress = await this.client.ramps.offRampBurnAddress({ chain_ref: chainRef }, opts);
+        opts.signal?.throwIfAborted();
         const request = await this.client.ramps.createOffRamp(body, opts);
         return { request, burnAddress };
     }
@@ -42,29 +65,69 @@ function readString(obj, key) {
     }
     return v;
 }
-async function pollEntity(fetchOne, poll, label) {
+function validatePoll(poll) {
+    const { attempts, intervalMs } = { ...DEFAULT_POLL, ...poll };
+    if (!Number.isSafeInteger(attempts) ||
+        attempts < 1 ||
+        !Number.isFinite(intervalMs) ||
+        intervalMs < 0 ||
+        intervalMs > 2_147_483_647) {
+        throw new TypeError('Polling requires positive attempts and a nonnegative interval');
+    }
+}
+async function pollOperation(client, tokenId, operationId, kind, poll) {
+    const { attempts, intervalMs, signal } = { ...DEFAULT_POLL, ...poll };
+    for (let i = 0; i < attempts; i++) {
+        signal?.throwIfAborted();
+        const operation = await client.tokenization.getOperation(tokenId, operationId, poll);
+        signal?.throwIfAborted();
+        if (readString(operation, 'id') !== operationId ||
+            readString(operation, 'customer_token_id') !== tokenId ||
+            readString(operation, 'kind') !== kind) {
+            throw new Error('API returned a different tokenization operation');
+        }
+        const status = readString(operation, 'status');
+        if (status === 'confirmed')
+            return;
+        if (!PENDING_OPERATION.has(status)) {
+            throw new Error(`operation ${operationId} reached a failed or unsupported status: ${status}`);
+        }
+        if (i + 1 < attempts)
+            await sleep(intervalMs, signal);
+    }
+    throw new Error(`operation ${operationId} remains pending after ${attempts} attempts; observe it before submitting another mutation`);
+}
+async function pollEntity(fetchOne, poll, tokenId, operationId) {
     const { attempts, intervalMs, signal } = { ...DEFAULT_POLL, ...poll };
     let last;
     for (let i = 0; i < attempts; i++) {
         signal?.throwIfAborted();
         last = await fetchOne();
-        const status = String(last?.['status'] ?? '');
-        if (SUCCESS.has(status))
+        signal?.throwIfAborted();
+        if (readString(last, 'id') !== tokenId)
+            throw new Error(`API returned a different customer token for deployment operation ${operationId}`);
+        const status = readString(last, 'status');
+        if (status === 'active')
             return last;
-        if (FAILURE.has(status)) {
-            throw new Error(`${label} reached terminal failure status: ${status}`);
+        if (!PENDING_TOKEN.has(status)) {
+            throw new Error(`token ${tokenId} for deployment operation ${operationId} reached a failed or unsupported status: ${status}`);
         }
-        await sleep(intervalMs, signal);
+        if (i + 1 < attempts)
+            await sleep(intervalMs, signal);
     }
-    throw new Error(`${label} did not reach a terminal status after ${attempts} attempts`);
+    throw new Error(`token ${tokenId} for deployment operation ${operationId} remains pending after ${attempts} attempts; observe that customer token before submitting another mutation`);
 }
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
         signal?.throwIfAborted();
-        const timer = setTimeout(resolve, ms);
-        signal?.addEventListener('abort', () => {
+        const aborted = () => {
             clearTimeout(timer);
-            reject(signal.reason);
-        }, { once: true });
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', aborted, { once: true });
     });
 }

package/dist/resources/workforce-wallets.d.ts

@@ -0,0 +1,34 @@
+import { Resource, type ReqBody } from './base.js';
+import type { XKOVAMutationOptions } from '../client.js';
+/** Current workforce human's canonical wallet, never selected by browser identity. */
+export declare class WorkforceWalletsResource extends Resource {
+    list(): Promise<{
+        data?: import("../generated/types.js").components["schemas"]["StaffMpcWallet"][];
+    }>;
+    /** Fresh exact human proof is required before a provider admission can be issued. */
+    provision(options?: XKOVAMutationOptions): Promise<{
+        mpc_wallet: import("../generated/types.js").components["schemas"]["StaffMpcWallet"];
+        wallet_auth: import("../generated/types.js").components["schemas"]["WalletAdmissionBootstrap"];
+        challenge: {
+            challenge_id: string;
+            nonce: string;
+            typed_data: import("../generated/types.js").components["schemas"]["StaffMpcEnrollmentTypedData"];
+            expires_at: string;
+        };
+    }>;
+    /** Activate only after signing the API's exact one-time enrollment typed data. */
+    register(body: ReqBody<'workforceWalletRegister'>, options?: XKOVAMutationOptions): Promise<{
+        id: import("../generated/types.js").components["schemas"]["StaffMpcWalletId"];
+        staff_id: import("../generated/types.js").components["schemas"]["StaffId"];
+        address: string | null;
+        state: "pending_provisioning" | "active" | "decommissioned";
+        provider_resolution: "pending" | "resolved" | "review_required";
+        created_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
+        updated_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
+    }>;
+    /** Binds one ceremony to the current resource's frozen Safe digest and nonce. */
+    signingBootstrap(body: ReqBody<'workforceWalletSigningBootstrap'>, options?: XKOVAMutationOptions): Promise<{
+        mpc_wallet: import("../generated/types.js").components["schemas"]["StaffMpcWallet"];
+        wallet_auth: import("../generated/types.js").components["schemas"]["WalletAdmissionBootstrap"];
+    }>;
+}

package/dist/resources/workforce-wallets.js

@@ -0,0 +1,19 @@
+import { Resource } from './base.js';
+/** Current workforce human's canonical wallet, never selected by browser identity. */
+export class WorkforceWalletsResource extends Resource {
+    list() {
+        return this.getJson('/workforce-auth/me/wallets');
+    }
+    /** Fresh exact human proof is required before a provider admission can be issued. */
+    provision(options) {
+        return this.postJson('/workforce-auth/me/wallets/provision', undefined, options);
+    }
+    /** Activate only after signing the API's exact one-time enrollment typed data. */
+    register(body, options) {
+        return this.postJson('/workforce-auth/me/wallets/register', body, options);
+    }
+    /** Binds one ceremony to the current resource's frozen Safe digest and nonce. */
+    signingBootstrap(body, options) {
+        return this.postJson('/workforce-auth/me/wallets/signing-bootstrap', body, options);
+    }
+}

package/dist/url.d.ts

@@ -0,0 +1 @@
+export declare function isAllowedProtocol(url: URL): boolean;

package/dist/url.js

@@ -0,0 +1,4 @@
+export function isAllowedProtocol(url) {
+    return (url.protocol === 'https:' ||
+        (url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')));
+}

package/dist/webhook.js

@@ -45,7 +45,7 @@ function parseHeader(header) {
             t = n;
         }
         else if (key === 'v1') {
-            if (!/^[0-9a-f]+$/.test(val))
+            if (!/^[0-9a-f]{64}$/.test(val))
                 return null;
             v1s.push(val);
         }

package/dist/workforce-bff.d.ts

@@ -0,0 +1,202 @@
+import { type XKOVAClientOptions } from './client.js';
+import { WorkforceWalletsResource } from './resources/workforce-wallets.js';
+export { serializeXKOVAMemberSessionCookie as serializeXKOVAWorkforceSessionCookie, serializeXKOVAMemberFlowCookie as serializeXKOVAWorkforceFlowCookie, serializeClearedXKOVAMemberCookie as serializeClearedXKOVAWorkforceCookie, readXKOVAMemberCookie as readXKOVAWorkforceCookie, readXKOVAMemberCallbackFlow as readXKOVAWorkforceCallbackFlow, xkovaMemberFlowCookieName as xkovaWorkforceFlowCookieName, createXKOVAMemberCsrfToken as createXKOVAWorkforceCsrfToken, verifyXKOVAMemberCsrfToken as verifyXKOVAWorkforceCsrfToken, assertXKOVAMemberRequestOrigin as assertXKOVAWorkforceRequestOrigin, } from './member-bff.js';
+export interface XKOVAWorkforceBffClientOptions extends XKOVAClientOptions {
+    /** Exact nonsecret workforce registration selector. This is not a member selector. */
+    readonly workforceKey: string;
+}
+export interface XKOVAWorkforceSession {
+    readonly session_id: string;
+    readonly application_id: string;
+    readonly staff_id: string;
+    readonly person_id: string;
+    readonly tenant_id: string;
+    readonly workspace_id: string;
+    readonly provider_namespace: string;
+    readonly provider_subject: string;
+    readonly roles: readonly string[];
+    readonly scopes: readonly string[];
+    readonly resource_grants: {
+        readonly treasury_wallet_ids: readonly string[];
+        readonly customer_token_ids: readonly string[];
+    };
+    readonly action_authorization_enabled: boolean;
+    readonly expires_at: string;
+    readonly absolute_expires_at: string;
+}
+export interface XKOVAWorkforceSessionMaterial {
+    readonly session_token: string;
+    readonly refresh_token: string;
+    readonly refresh_attempt_token: string;
+    readonly session: XKOVAWorkforceSession;
+}
+export interface XKOVAWorkforceActionReview {
+    readonly operation: string;
+    readonly proof_method: string;
+    readonly review: Readonly<Record<string, unknown>>;
+    readonly review_digest: string;
+    readonly expires_at: string;
+}
+export interface XKOVAWorkforceActionChallenge {
+    readonly nonce: string;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly authorization_endpoint: string;
+    readonly max_auth_age_seconds: number;
+    readonly required_acr_values: readonly string[];
+    readonly required_amr_values: readonly string[];
+    readonly expires_at: string;
+    readonly review: Readonly<Record<string, unknown>>;
+    readonly review_digest: string;
+}
+/** Confidential, one-use authority for the unchanged reviewed request only. */
+export interface XKOVAWorkforceActionGrant {
+    readonly grant_token: string;
+    readonly expires_at: string;
+}
+export interface StoredXKOVAWorkforceSession<T = unknown> {
+    readonly clientFingerprint: string;
+    readonly authorizationCodeHash: string;
+    readonly material: XKOVAWorkforceSessionMaterial;
+    readonly applicationExpiresAt: number;
+    readonly applicationData: T;
+    /** Persist before remote logout. It permanently blocks refresh and resource resolution. */
+    readonly logoutPending?: boolean;
+}
+/**
+ * Encrypt credentials and proofs at rest. All writes commit before resolving,
+ * independently of later callback errors. replace is exact-existing-only.
+ * runExclusive serializes the same record across every BFF replica. It is not
+ * a surrounding rollback transaction. Use separate transaction/session stores.
+ */
+export interface XKOVAWorkforceStore<T> {
+    put(reference: string, value: T): Promise<void>;
+    get(reference: string): Promise<T | null>;
+    replace(reference: string, value: T): Promise<void>;
+    delete(reference: string): Promise<void>;
+    runExclusive<R>(reference: string, work: () => Promise<R>): Promise<R>;
+}
+export interface XKOVAWorkforceAuthorizationTransaction<T = unknown> {
+    readonly clientFingerprint: string;
+    readonly status: 'pending' | 'completed';
+    readonly redirectUri: string;
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+    readonly exchangeAttemptId: string;
+    readonly sessionReference: string;
+    readonly expiresAt: number;
+    readonly transactionId?: string;
+    readonly nonce?: string;
+    readonly issuer?: string;
+    readonly audience?: string;
+    /** Written before the one-use provider call. An unknown result is never redeemed again. */
+    readonly providerExchangeStarted?: {
+        readonly codeHash: string;
+        readonly applicationData: T;
+    };
+    readonly stagedProofToken?: string;
+}
+export declare class XKOVAWorkforceBffError extends Error {
+    readonly code: 'transaction_unavailable' | 'binding_mismatch' | 'provider_exchange_outcome_unknown' | 'session_unavailable';
+    constructor(code: 'transaction_unavailable' | 'binding_mismatch' | 'provider_exchange_outcome_unknown' | 'session_unavailable');
+}
+/** Confidential workforce protocol. It neither enrolls a subject nor creates local staff authority. */
+export declare class XKOVAWorkforceBffClient {
+    private readonly options;
+    private readonly client;
+    private readonly fingerprint;
+    constructor(options: XKOVAWorkforceBffClientOptions);
+    beginAuthorization<T>(input: {
+        browserOrigin: string;
+        redirectUri: string;
+        transactionStore: XKOVAWorkforceStore<XKOVAWorkforceAuthorizationTransaction<T>>;
+    }): Promise<{
+        state: string;
+        nonce: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeChallengeMethod: "S256";
+        issuer: string;
+        audience: string;
+        authorizationEndpoint: string;
+        maxAuthAgeSeconds: number;
+        requiredAcrValues: string[];
+        expiresAt: string;
+    }>;
+    completeAuthorizationCallback<T>(input: {
+        callbackUrl: string;
+        /** Read from the genuine initiating browser's HttpOnly flow cookie. */
+        expectedState: string;
+        transactionStore: XKOVAWorkforceStore<XKOVAWorkforceAuthorizationTransaction<T>>;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+        applicationData: T;
+        /** Perform the provider's real code exchange and signature/nonce checks server-side. */
+        exchangeProviderCode: (input: {
+            code: string;
+            codeVerifier: string;
+            redirectUri: string;
+            expectedNonce: string;
+            issuer: string;
+            audience: string;
+        }) => Promise<{
+            proofToken: string;
+        }>;
+    }): Promise<{
+        reference: string;
+        session: StoredXKOVAWorkforceSession<T>;
+    }>;
+    getSession(sessionToken: string): Promise<XKOVAWorkforceSession>;
+    resolveSession<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+    }): Promise<StoredXKOVAWorkforceSession<T> | null>;
+    /** Request-scoped resources only. Check the browser's Origin/CSRF before invoking writes. */
+    resolveResources<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+        browserOrigin: string;
+        /** Keep the API-issued grant on the server and repeat only its frozen request. */
+        actionGrant?: XKOVAWorkforceActionGrant;
+    }): Promise<{
+        session: StoredXKOVAWorkforceSession<T>;
+        resources: {
+            treasury: import("./resources/treasury.js").TreasuryResource;
+            tokenization: import("./resources/index.js").TokenizationResource;
+            wallets: WorkforceWalletsResource;
+        };
+    } | null>;
+    /** Review the locator returned by human_authorization_required. Never send it to a third-party host. */
+    inspectAction(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+    }): Promise<XKOVAWorkforceActionReview>;
+    /** Starts a real provider ceremony after the user reviews the exact request. No action is executed. */
+    beginActionProof(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+    }): Promise<XKOVAWorkforceActionChallenge>;
+    /** Submit the real, freshly verified provider token. A lost response is never automatically retried. */
+    completeActionProof(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+        nonce: string;
+        proofToken: string;
+    }): Promise<XKOVAWorkforceActionGrant>;
+    logoutSession<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+    }): Promise<void>;
+    private assertSession;
+    private postJson;
+    private getJson;
+}
+/** Advisory browser UI data only; provider identity, credentials and grants stay confidential. */
+export declare function projectXKOVAWorkforceSession(value: StoredXKOVAWorkforceSession): {
+    signedIn: true;
+    staffId: string;
+    roles: string[];
+    expiresAt: string;
+};