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

package/examples/postgres-checkpoint-store.mjs

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+/** Install pg separately. The application owns the pool, schema, retention and key rotation. */
+export class PostgresCheckpointStore {
+  #context = new AsyncLocalStorage();
+  #key;
+
+  constructor(pool, namespace, encryptionKey) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(namespace)) throw new Error('Invalid store namespace');
+    if (!Buffer.isBuffer(encryptionKey) || encryptionKey.length !== 32)
+      throw new Error('A 32-byte application encryption key is required');
+    this.pool = pool;
+    this.namespace = namespace;
+    this.#key = Buffer.from(encryptionKey);
+  }
+
+  #binding(reference) {
+    return JSON.stringify([this.namespace, reference]);
+  }
+
+  #encrypt(reference, record) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
+    cipher.setAAD(Buffer.from(this.#binding(reference)));
+    const bytes = Buffer.concat([cipher.update(JSON.stringify(record), 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), bytes]);
+  }
+
+  #decrypt(reference, bytes) {
+    if (!Buffer.isBuffer(bytes) || bytes.length < 29) throw new Error('Invalid stored envelope');
+    const decipher = createDecipheriv('aes-256-gcm', this.#key, bytes.subarray(0, 12));
+    decipher.setAAD(Buffer.from(this.#binding(reference)));
+    decipher.setAuthTag(bytes.subarray(12, 28));
+    return JSON.parse(
+      Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString('utf8'),
+    );
+  }
+
+  #db() {
+    return this.#context.getStore()?.client ?? this.pool;
+  }
+
+  async put(reference, record) {
+    await this.#db().query(
+      'INSERT INTO xkova_helper_checkpoints(namespace, reference, envelope, expires_at) VALUES ($1,$2,$3,$4)',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+  }
+
+  async get(reference) {
+    const result = await this.#db().query(
+      'SELECT envelope FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2 AND expires_at > now()',
+      [this.namespace, reference],
+    );
+    return result.rowCount ? this.#decrypt(reference, result.rows[0].envelope) : null;
+  }
+
+  async replace(reference, record) {
+    const result = await this.#db().query(
+      'UPDATE xkova_helper_checkpoints SET envelope=$3, expires_at=$4 WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference, this.#encrypt(reference, record), this.#expiry(record)],
+    );
+    if (result.rowCount !== 1) throw new Error('Cannot replace a missing checkpoint');
+  }
+
+  async delete(reference) {
+    await this.#db().query(
+      'DELETE FROM xkova_helper_checkpoints WHERE namespace=$1 AND reference=$2',
+      [this.namespace, reference],
+    );
+  }
+
+  #expiry(record) {
+    const value = record.applicationExpiresAt ?? record.expiresAt;
+    if (!Number.isSafeInteger(value)) throw new Error('Invalid checkpoint expiry');
+    return new Date(value);
+  }
+
+  /** A session lock, with separate autocommit checkpoints, never an outer SQL transaction. */
+  async runExclusive(reference, work) {
+    const existing = this.#context.getStore();
+    if (existing) {
+      if (existing.reference !== reference) throw new Error('Nested references are unsupported');
+      return work();
+    }
+    const client = await this.pool.connect();
+    let locked = false;
+    let discard = false;
+    try {
+      await client.query("SET lock_timeout = '5s'");
+      await client.query("SET statement_timeout = '10s'");
+      await client.query('SELECT pg_advisory_lock(hashtextextended($1, 0))', [
+        this.#binding(reference),
+      ]);
+      locked = true;
+      return await this.#context.run({ client, reference }, work);
+    } finally {
+      try {
+        if (locked) {
+          const result = await client.query(
+            'SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS released',
+            [this.#binding(reference)],
+          );
+          if (result.rows[0]?.released !== true) throw new Error('Checkpoint lock was lost');
+        }
+        await client.query('RESET lock_timeout');
+        await client.query('RESET statement_timeout');
+      } catch {
+        // A connection with an uncertain lock must never return to the pool.
+        discard = true;
+      }
+      client.release(discard);
+    }
+  }
+}

package/examples/postgres-checkpoints.sql

@@ -0,0 +1,9 @@
+-- Apply through your application's normal migration process, to its own database.
+CREATE TABLE xkova_helper_checkpoints (
+  namespace text NOT NULL,
+  reference text NOT NULL,
+  envelope bytea NOT NULL,
+  expires_at timestamptz NOT NULL,
+  PRIMARY KEY (namespace, reference)
+);
+CREATE INDEX xkova_helper_checkpoints_expiry ON xkova_helper_checkpoints (expires_at);

package/llms.txt

@@ -9,6 +9,7 @@ Use this package on a Node.js 22+ server. Read the installed declarations before
 - `dist/generated/types.d.ts`: exact request bodies, responses, parameters, and operation IDs. Import types through @xkova/sdk/types.
 - `dist/member-bff.d.ts`: authorization, session persistence, refresh, logout, action reviews, and human authorization.
 - `dist/member-resources.d.ts`: typed resources bound to the exact authenticated member.
+- `dist/workforce-bff.d.ts`: confidential workforce sessions, durable callback recovery, exact action reviews and fresh provider proof. Use @xkova/sdk/workforce-bff, separately from member login and Console operators.
 - [Quickstart](https://docs.xkova.com/getting-started.html): sandbox access and first authenticated call.
 - [Customer OpenAPI](https://github.com/XKOVA/typescript-sdk/blob/main/schema/customer-api.json): machine-readable contract for the public SDK source. For an installed release, use its generated declarations.
 - [SDK guide](https://docs.xkova.com/sdk-overview.html): client and resource examples.
@@ -22,6 +23,7 @@ Use this package on a Node.js 22+ server. Read the installed declarations before
 1. Server business integration: create XKOVAClient.forTenant({ baseUrl, apiKey }). Use https://sandbox-api.xkova.com for sandbox and https://api.xkova.com for production. The API key binds the workspace and mode.
 2. Member application: use XKOVAMemberBffClient from @xkova/sdk/member-bff in your BFF. Resolve confidential sessions to request-scoped resources with resolveResources(). The browser sends only its application cookie and CSRF proof to your BFF.
 3. Browser companion: optionally install @xkova/browser. It calls your same-origin routes; it does not create those routes or install a session store.
+4. Customer staff application: use XKOVAWorkforceBffClient from @xkova/sdk/workforce-bff, an explicitly registered dedicated principal and immutable admitted provider subjects. Resolve each authenticated person per request. API-key attribution, email, groups and member credentials cannot create staff authority.
 
 ## Find a capability
 
@@ -40,6 +42,7 @@ Each namespace below is a property of XKOVAClient. Read its declaration under di
 | Transaction history | transactions |
 | Fee schedules and platform fees | feeSchedules |
 | Customer tokens, deployment, minting, supply, access | tokenization |
+| Tenant treasury vaults, proposals, owner signatures, quorum and transfer status | treasury |
 | Real-world assets, cap tables, distributions, corporate actions, provenance | rwa |
 | Gateway registration and conformance | integrationGateways |
 | Branding and sending-domain configuration | branding |
@@ -48,6 +51,7 @@ Each namespace below is a property of XKOVAClient. Read its declaration under di
 | Webhook subscriptions and delivery operations | webhooks |
 | Token deployment/mint polling and off-ramp initiation | workflows |
 | Session exchange, durable review recovery, fresh human authorization | @xkova/sdk/member-bff |
+| Institution workforce login, scoped sessions and exact action proofs | @xkova/sdk/workforce-bff |
 | Verify webhook signatures over raw body bytes | @xkova/sdk/webhook |
 | Offline RWA transparency proofs | @xkova/sdk/rwa-verify |
 | Customer contract ABIs | @xkova/sdk/abi |
@@ -60,6 +64,7 @@ API availability does not grant permission. Product entitlement, selected API-ke
 - Use exported package entry points and typed resource methods. Do not import dist files as runtime subpaths, fabricate request fields, or suppress type errors with any.
 - Production writes require the bearer key plus an active asymmetric requestSigner credential. Its async callback signs through your key provider. The SDK supplies RFC 9421 signatures and RFC 9530 digests. Production reads use bearer authentication.
 - Generate one idempotency key before a logical mutation and persist it. Reuse it only with the identical request. The SDK does not automatically retry writes. A timeout or disconnect can leave the outcome unknown; reconcile the existing resource before starting another operation.
+- Treasury methods preserve API roles, governance holds, independent owner signatures and Safe quorum. An API key is not an authenticated staff session or a wallet signer. Use isHeldApproval before reading an entity from a governed mutation; approval does not itself produce a signature or prove settlement.
 - Use decimal strings for monetary values according to the request type. Preserve asset and chain identity throughout a flow. Do not perform monetary calculations with JavaScript floating-point numbers.
 - Read pagination and response types. Use paginateCursor or collectCursor where applicable; bound collection sizes and polling. Propagate AbortSignal and request deadlines.
 - Handle XKOVAApiError with its code, status, correlationId, and retryAfter. Handle XKOVAUploadError for the object-storage stage. Do not expose transport headers, provider proofs, or signed URLs in user errors or logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xkova/sdk",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "TypeScript SDK for the XKOVA API.",
   "homepage": "https://docs.xkova.com",
   "repository": {
@@ -31,6 +31,10 @@
       "types": "./dist/member-bff.d.ts",
       "default": "./dist/member-bff.js"
     },
+    "./workforce-bff": {
+      "types": "./dist/workforce-bff.d.ts",
+      "default": "./dist/workforce-bff.js"
+    },
     "./webhook": {
       "types": "./dist/webhook.d.ts",
       "default": "./dist/webhook.js"
@@ -46,7 +50,8 @@
   },
   "files": [
     "dist",
-    "llms.txt"
+    "llms.txt",
+    "examples"
   ],
   "dependencies": {
     "viem": "^2.21.0"