@xkova/sdk 0.1.0-alpha.6 → 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
@@ -124,6 +195,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 +291,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 +341,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
@@ -464,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) {