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

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/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;
+};