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

package/README.md

@@ -93,6 +93,77 @@ one live successor; either key can be revoked immediately.
 
 ## Typed resources
 
+### Customer workforce applications
+
+Use `@xkova/sdk/workforce-bff` on a confidential server for an institution's
+staff application. It is separate from member login and Console operator
+sessions. The Console administrator first registers an exact issuer, audience,
+JWKS endpoint, application origins/callbacks and dedicated workspace API
+principal. They explicitly admit each immutable provider subject to an existing
+staff membership with narrowed roles and assigned resources. Email and provider
+groups never grant authority. A transport key cannot admit its own users.
+
+```ts
+import { XKOVAWorkforceBffClient } from '@xkova/sdk/workforce-bff';
+
+const workforce = new XKOVAWorkforceBffClient({
+  baseUrl: 'https://sandbox-api.xkova.com',
+  apiKey: process.env.XKOVA_WORKFORCE_API_KEY!,
+  workforceKey: process.env.XKOVA_WORKFORCE_KEY!,
+});
+```
+
+Use separate encrypted durable transaction/session stores implementing
+`XKOVAWorkforceStore`. Each write must commit independently of a later callback
+error. Serialize each reference across replicas, and make `replace` fail when
+the record is absent. The included PostgreSQL adapter demonstrates this contract.
+Use a distinct namespace from member sessions. Keep session material, provider
+proofs, PKCE verifiers and refresh attempts on the server.
+
+`beginAuthorization` returns the registered provider endpoint, audience, nonce,
+PKCE challenge and policy. Use a short-lived HttpOnly flow cookie for its state.
+Your BFF exchanges the real provider code and verifies its signature, issuer,
+audience, nonce and PKCE through `completeAuthorizationCallback`. XKOVA performs
+its own registered-provider verification before issuing the workforce session.
+An uncertain provider exchange cannot redeem the code again. A staged proof can
+recover the same API exchange attempt. A provider token's actual expiry bounds
+the session; refreshing XKOVA credentials does not refresh upstream identity.
+
+Read only `projectXKOVAWorkforceSession` into browser UI. Resolve resource access
+per request with `resolveResources({ reference, sessionStore, browserOrigin })`.
+The browser's Origin and session-bound CSRF proof must be checked before writes.
+The BFF pins its registered origin, workforce application and resolved human
+session. Roles/scopes/resources are intersected by the API, never combined with
+the transport principal's authority. A member credential cannot supply workforce
+authority, and workforce sessions cannot enter Console operator routes.
+
+For `human_authorization_required`, preserve the exact request, body, origin and
+idempotency key in a private review record. Use `inspectAction` and
+`beginActionProof` for its exact `authorization_token`. Show the returned review
+before starting real fresh provider authentication with the returned nonce and
+qualified assurance policy. Validate the provider callback's own state, PKCE,
+issuer, audience, nonce and current subject; require fresh authentication rather
+than accepting a cached login. Submit the real token with `completeActionProof`.
+Keep its short-lived grant server-side and pass it as `actionGrant` to
+`resolveResources` for only the unchanged frozen request. A grant never approves
+another request or replaces independent Safe signatures/quorum. These methods
+do not automatically retry an action or an uncertain proof completion.
+
+`logoutSession` durably blocks the local session before retiring it at XKOVA.
+Retry only that same logout if the network result is uncertain. It does not
+promise a global logout at the external provider. No request may fall back to a
+machine principal after workforce authentication fails.
+
+The resolved `wallets` resource supports `list`, `provision`, `register` and
+`signingBootstrap`. Provisioning and signing need the exact one-use human grant.
+Register only after signing the API's returned enrollment typed data. Signing
+bootstrap requires the existing proposal ID, its frozen Safe digest and nonce.
+Use `@xkova/browser/wallet` for the isolated browser ceremony, with a fresh
+purpose-bound admission and the expected wallet address. Keep the BFF key,
+provider proofs and workforce session credentials on the server. Provider
+admission does not replace wallet possession, current signer eligibility,
+independent-person quorum or confirmed chain settlement.
+
 Call resource methods with typed inputs:
 
 ```ts
@@ -533,6 +604,40 @@ try {
 }
 ```
 
+## Treasury vaults and transfer proposals
+
+Use `client.treasury` from a trusted backend with the workspace's explicitly
+granted treasury scopes and roles. Discover the chain and eligible assets before
+creating a vault or proposal. An existing same-chain vault retains its real
+owner set and threshold.
+
+```ts
+import { isHeldApproval } from '@xkova/sdk';
+
+const vaults = await xkova.treasury.listWallets();
+const proposal = await xkova.treasury.getTransfer('trf_...');
+const counterparties = await xkova.treasury.listCounterparties({ limit: 20 });
+```
+
+Vault and counterparty setup can return a governance hold. Check `isHeldApproval`
+before reading entity fields. Keep the original request and idempotency key;
+resume through normal policy after independently eligible approvers complete the
+required approval. The SDK does not approve, sign or retry a held operation.
+
+`draftTransfer` creates a proposal. `getTransfer` reads its frozen signing context
+and current quorum. Each eligible owner produces their own signature over that
+exact Safe transaction. `submitTransferSignature` submits an existing signature;
+it does not create a wallet or sign on anyone's behalf. `executeTransfer` retains
+current role, signer, nonce, quorum and policy checks. A returned relay result is
+not settlement; read the proposal until its actual confirmed or failed outcome.
+After a timeout, reconcile the existing proposal before creating another one.
+
+The API key's attributed staff ID is audit metadata, not a per-human session or
+permission to bootstrap a staff wallet. This namespace does not expose Console
+credentials, staff-wallet bootstrap credentials, or raw private-key material.
+The supported workforce authentication and independent signer ceremonies remain
+separate requirements for a complete customer treasury application.
+
 ## Webhooks and generated types
 
 ```ts

package/dist/client.d.ts

@@ -13,6 +13,7 @@ import { RampsResource } from './resources/ramps.js';
 import { RwaResource } from './resources/rwa.js';
 import { TenantResource } from './resources/tenant.js';
 import { TokenizationResource } from './resources/tokenization.js';
+import { TreasuryResource } from './resources/treasury.js';
 import { TransactionsResource } from './resources/transactions.js';
 import { WalletsResource } from './resources/wallets.js';
 import { WebhooksResource } from './resources/webhooks.js';
@@ -47,6 +48,7 @@ export interface XKOVAMutationOptions extends XKOVARequestControl {
 export declare class XKOVAClient {
     private readonly config;
     private readonly memberContext?;
+    private readonly workforceContext?;
     private readonly apiBaseUrl;
     private readonly fetchImpl;
     private constructor();
@@ -65,6 +67,8 @@ export declare class XKOVAClient {
     get rwa(): RwaResource;
     get tenant(): TenantResource;
     get tokenization(): TokenizationResource;
+    /** Tenant treasury operations retain server-side roles, governance and signer checks. */
+    get treasury(): TreasuryResource;
     get transactions(): TransactionsResource;
     get wallets(): WalletsResource;
     get webhooks(): WebhooksResource;

package/dist/client.js

@@ -16,6 +16,7 @@ import { RampsResource } from './resources/ramps.js';
 import { RwaResource } from './resources/rwa.js';
 import { TenantResource } from './resources/tenant.js';
 import { TokenizationResource } from './resources/tokenization.js';
+import { TreasuryResource } from './resources/treasury.js';
 import { TransactionsResource } from './resources/transactions.js';
 import { WalletsResource } from './resources/wallets.js';
 import { WebhooksResource } from './resources/webhooks.js';
@@ -25,11 +26,13 @@ import { WorkspacesResource } from './resources/workspaces.js';
 export class XKOVAClient {
     config;
     memberContext;
+    workforceContext;
     apiBaseUrl;
     fetchImpl;
-    constructor(config, memberContext) {
+    constructor(config, memberContext, workforceContext) {
         this.config = config;
         this.memberContext = memberContext;
+        this.workforceContext = workforceContext;
         if (config.timeoutMs !== undefined &&
             (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0)) {
             throw new Error('XKOVAClient timeoutMs must be a positive finite number');
@@ -83,6 +86,10 @@ export class XKOVAClient {
     get tokenization() {
         return (this.namespaces.tokenization ??= new TokenizationResource(this));
     }
+    /** Tenant treasury operations retain server-side roles, governance and signer checks. */
+    get treasury() {
+        return (this.namespaces.treasury ??= new TreasuryResource(this));
+    }
     get transactions() {
         return (this.namespaces.transactions ??= new TransactionsResource(this));
     }
@@ -108,6 +115,20 @@ export class XKOVAClient {
     static forMemberSession(options, context) {
         return new XKOVAClient(options, Object.freeze({ ...context }));
     }
+    /** @internal Created only after the workforce BFF resolves its confidential store. */
+    static forWorkforceSession(options, context) {
+        if (!/^xkova_wf_[A-Za-z0-9_-]{43}$/.test(context.workforceKey) ||
+            !/^xwfs_[A-Za-z0-9_-]{43}$/.test(context.sessionToken) ||
+            (context.humanAuthorization !== undefined &&
+                !/^[A-Za-z0-9_-]{43}$/.test(context.humanAuthorization))) {
+            throw new TypeError('Invalid workforce session material');
+        }
+        const origin = new URL(context.browserOrigin);
+        if (origin.origin !== context.browserOrigin || !isAllowedProtocol(origin)) {
+            throw new TypeError('Invalid workforce application origin');
+        }
+        return new XKOVAClient(options, undefined, Object.freeze({ ...context }));
+    }
     /** @internal Resource transport. Use typed namespaces instead. */
     async requestJson(options) {
         const prepared = await this.prepareRequest(options);
@@ -211,6 +232,9 @@ export class XKOVAClient {
             headers.set(name, value);
         }
         if (this.memberContext) {
+            if (headers.has('X-Workforce-Session') || headers.has('X-XKOVA-Workforce-Key')) {
+                throw new TypeError('Member and workforce authority cannot be combined');
+            }
             const authority = {
                 Authorization: `Bearer ${this.config.apiKey}`,
                 'X-Member-Session-Id': this.memberContext.memberSessionId,
@@ -224,6 +248,40 @@ export class XKOVAClient {
                 headers.set(name, value);
             }
         }
+        if (this.workforceContext) {
+            if (headers.has('X-XKOVA-Human-Authorization') && !this.workforceContext.humanAuthorization) {
+                throw new TypeError('A workforce action grant must come from the confidential context');
+            }
+            for (const name of [
+                'Cookie',
+                'X-Member-Session-Id',
+                'X-XKOVA-Publishable-Key',
+                'X-Account-Holder-Id',
+                'X-End-User-Id',
+                'X-OIDC-ID-Token',
+                'X-Active-Scope',
+                'X-Workspace-Id',
+                'X-Workspace-Type',
+            ]) {
+                if (headers.has(name))
+                    throw new TypeError('A workforce operation cannot mix identity or workspace contexts');
+            }
+            const authority = {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                'X-XKOVA-Workforce-Key': this.workforceContext.workforceKey,
+                'X-Workforce-Session': this.workforceContext.sessionToken,
+                Origin: this.workforceContext.browserOrigin,
+                ...(this.workforceContext.humanAuthorization !== undefined && {
+                    'X-XKOVA-Human-Authorization': this.workforceContext.humanAuthorization,
+                }),
+            };
+            for (const [name, value] of Object.entries(authority)) {
+                if (headers.has(name) && headers.get(name) !== value) {
+                    throw new TypeError('A workforce-bound operation cannot replace its session authority');
+                }
+                headers.set(name, value);
+            }
+        }
         return headers;
     }
     requestSignal(signal) {