@xkova/sdk 0.1.0-alpha.1

package/dist/rwa-verify.d.ts

@@ -0,0 +1,50 @@
+export interface VerifyInclusionInput {
+    /** Raw leaf data as hex: the metadata version's `chain_leaf`. */
+    readonly leafData: string;
+    /** 0-based index of the leaf in the tree (its `version_seq`). */
+    readonly leafIndex: number;
+    /** Number of leaves in the tree the STH committed to (`tree_size`). */
+    readonly treeSize: number;
+    /** Audit path, leaf→root, as hex node hashes. */
+    readonly proof: readonly string[];
+    /** The signed tree head's `root_hash` (hex). */
+    readonly root: string;
+}
+/**
+ * Checks the leaf and audit path against the root using RFC 6962 section 2.1.1.
+ * This does not authenticate the root; verify its signed tree head separately.
+ */
+export declare function verifyInclusion(input: VerifyInclusionInput): boolean;
+export interface VerifyConsistencyInput {
+    /** Size of the earlier tree (the earlier STH's `tree_size`). */
+    readonly first: number;
+    /** Size of the later tree (the later STH's `tree_size`). */
+    readonly second: number;
+    /** Consistency proof, hex node hashes. */
+    readonly proof: readonly string[];
+    /** The earlier STH's `root_hash` (hex). */
+    readonly firstRoot: string;
+    /** The later STH's `root_hash` (hex). */
+    readonly secondRoot: string;
+}
+/**
+ * Checks that the earlier tree is a prefix of the later tree using RFC 6962
+ * section 2.1.2. Retain an earlier trusted tree head to detect rewritten history.
+ */
+export declare function verifyConsistency(input: VerifyConsistencyInput): boolean;
+export interface VerifyTreeHeadInput {
+    readonly treeSize: number;
+    /** The STH root hash (hex, 0x-prefixed 32 bytes). */
+    readonly rootHash: string;
+    readonly timestampMs: number;
+    readonly chainId: number;
+    /** The STH signature (hex). */
+    readonly signature: string;
+    /** The address the signature is expected to recover to (the trusted signer). */
+    readonly expectedSigner: string;
+}
+/**
+ * Checks the EIP-712 signature against `expectedSigner`. Obtain that address
+ * from a trusted source, not from the proof being verified.
+ */
+export declare function verifySth(input: VerifyTreeHeadInput): Promise<boolean>;

package/dist/rwa-verify.js

@@ -0,0 +1,159 @@
+/**
+ * Verify RWA transparency proofs offline. Inclusion checks a metadata version
+ * against a tree head; consistency checks that a later tree only appended data.
+ * Verify the tree head's signature separately against a trusted signer address.
+ *
+ * RFC 6962 domain separation: leaf = SHA-256(0x00 || data),
+ * node = SHA-256(0x01 || left || right).
+ */
+import { createHash } from 'node:crypto';
+import { hashTypedData, recoverAddress } from 'viem';
+const LEAF_PREFIX = Buffer.from([0x00]);
+const NODE_PREFIX = Buffer.from([0x01]);
+function hashLeaf(data) {
+    return createHash('sha256').update(LEAF_PREFIX).update(data).digest();
+}
+function hashNode(left, right) {
+    return createHash('sha256').update(NODE_PREFIX).update(left).update(right).digest();
+}
+function fromHex(h, expectedBytes) {
+    const raw = h.startsWith('0x') ? h.slice(2) : h;
+    if (!/^(?:[0-9a-fA-F]{2})*$/.test(raw)) {
+        throw new Error('invalid hex');
+    }
+    const value = Buffer.from(raw, 'hex');
+    if (expectedBytes !== undefined && value.length !== expectedBytes) {
+        throw new Error(`expected ${expectedBytes} bytes`);
+    }
+    return value;
+}
+/**
+ * Checks the leaf and audit path against the root using RFC 6962 section 2.1.1.
+ * This does not authenticate the root; verify its signed tree head separately.
+ */
+export function verifyInclusion(input) {
+    const { leafIndex, treeSize } = input;
+    if (!Number.isInteger(leafIndex) || !Number.isInteger(treeSize))
+        return false;
+    if (leafIndex < 0 || leafIndex >= treeSize)
+        return false;
+    try {
+        let fn = leafIndex;
+        let sn = treeSize - 1;
+        let r = hashLeaf(fromHex(input.leafData));
+        for (const pHex of input.proof) {
+            if (sn === 0)
+                return false;
+            const p = fromHex(pHex, 32);
+            if ((fn & 1) === 1 || fn === sn) {
+                r = hashNode(p, r);
+                if ((fn & 1) === 0) {
+                    do {
+                        fn >>= 1;
+                        sn >>= 1;
+                    } while ((fn & 1) === 0 && fn !== 0);
+                }
+            }
+            else {
+                r = hashNode(r, p);
+            }
+            fn >>= 1;
+            sn >>= 1;
+        }
+        return sn === 0 && r.equals(fromHex(input.root, 32));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks that the earlier tree is a prefix of the later tree using RFC 6962
+ * section 2.1.2. Retain an earlier trusted tree head to detect rewritten history.
+ */
+export function verifyConsistency(input) {
+    const { first, second } = input;
+    if (!Number.isInteger(first) || !Number.isInteger(second))
+        return false;
+    if (first < 1 || first > second)
+        return false;
+    try {
+        const firstRoot = fromHex(input.firstRoot, 32);
+        const secondRoot = fromHex(input.secondRoot, 32);
+        if (first === second)
+            return input.proof.length === 0 && firstRoot.equals(secondRoot);
+        const isPow2 = (first & (first - 1)) === 0;
+        const proof = (isPow2 ? [input.firstRoot, ...input.proof] : input.proof).map((hex) => fromHex(hex, 32));
+        if (proof.length === 0)
+            return false;
+        let fn = first - 1;
+        let sn = second - 1;
+        while ((fn & 1) === 1) {
+            fn >>= 1;
+            sn >>= 1;
+        }
+        let fr = proof[0];
+        let sr = proof[0];
+        for (let i = 1; i < proof.length; i++) {
+            const c = proof[i];
+            if (sn === 0)
+                return false;
+            if ((fn & 1) === 1 || fn === sn) {
+                fr = hashNode(c, fr);
+                sr = hashNode(c, sr);
+                if ((fn & 1) === 0) {
+                    do {
+                        fn >>= 1;
+                        sn >>= 1;
+                    } while ((fn & 1) === 0 && fn !== 0);
+                }
+            }
+            else {
+                sr = hashNode(sr, c);
+            }
+            fn >>= 1;
+            sn >>= 1;
+        }
+        return sn === 0 && fr.equals(firstRoot) && sr.equals(secondRoot);
+    }
+    catch {
+        return false;
+    }
+}
+const TREE_HEAD_TYPES = {
+    TreeHead: [
+        { name: 'treeSize', type: 'uint256' },
+        { name: 'rootHash', type: 'bytes32' },
+        { name: 'timestampMs', type: 'uint256' },
+    ],
+};
+const TRANSPARENCY_LOG_VERIFYING_CONTRACT = '0x0000000000000000000000000000000000000000';
+/**
+ * Checks the EIP-712 signature against `expectedSigner`. Obtain that address
+ * from a trusted source, not from the proof being verified.
+ */
+export async function verifySth(input) {
+    try {
+        const root = input.rootHash.startsWith('0x') ? input.rootHash : `0x${input.rootHash}`;
+        const sig = input.signature.startsWith('0x') ? input.signature : `0x${input.signature}`;
+        const digest = hashTypedData({
+            domain: {
+                name: 'XKOVA TransparencyLog',
+                version: '1',
+                chainId: input.chainId,
+                verifyingContract: TRANSPARENCY_LOG_VERIFYING_CONTRACT,
+            },
+            types: TREE_HEAD_TYPES,
+            primaryType: 'TreeHead',
+            message: {
+                treeSize: BigInt(input.treeSize),
+                rootHash: root,
+                timestampMs: BigInt(input.timestampMs),
+            },
+        });
+        const recovered = await recoverAddress({ hash: digest, signature: sig });
+        return recovered.toLowerCase() === input.expectedSigner.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/webhook.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Verify the raw body before parsing it; reserializing JSON changes the bytes
+ * covered by the signature. The header is `t=<unix_ts>,v1=<hex_hmac_sha256>`.
+ * HMAC-SHA256 covers `<t>.<rawBody>`. The default timestamp tolerance is five
+ * minutes in either direction.
+ */
+export type VerifyWebhookSignatureResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare function verifyWebhookSignature(opts: {
+    /** The raw request body as XKOVA sent it. Byte-for-byte sensitive. */
+    rawBody: string;
+    /** Value of the `XKOVA-Webhook-Signature` request header. */
+    header: string;
+    /** Endpoint secret; rotate via /v1/webhook-endpoints/{id}/rotate. */
+    secret: string;
+    /** Override clock for tests; defaults to Date.now(). */
+    now?: () => number;
+    /** Override tolerance window; default 300s. */
+    toleranceSec?: number;
+}): VerifyWebhookSignatureResult;

package/dist/webhook.js

@@ -0,0 +1,56 @@
+/**
+ * Verify the raw body before parsing it; reserializing JSON changes the bytes
+ * covered by the signature. The header is `t=<unix_ts>,v1=<hex_hmac_sha256>`.
+ * HMAC-SHA256 covers `<t>.<rawBody>`. The default timestamp tolerance is five
+ * minutes in either direction.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const REPLAY_WINDOW_SEC = 300;
+export function verifyWebhookSignature(opts) {
+    const parsed = parseHeader(opts.header);
+    if (!parsed)
+        return { valid: false, reason: 'malformed_header' };
+    const tolerance = opts.toleranceSec ?? REPLAY_WINDOW_SEC;
+    const nowSec = Math.floor((opts.now?.() ?? Date.now()) / 1000);
+    if (Math.abs(nowSec - parsed.timestampSec) > tolerance) {
+        return { valid: false, reason: 'timestamp_outside_tolerance' };
+    }
+    const expectedHex = createHmac('sha256', opts.secret)
+        .update(`${parsed.timestampSec}.${opts.rawBody}`)
+        .digest('hex');
+    const expected = Buffer.from(expectedHex, 'hex');
+    for (const v1 of parsed.v1Hexes) {
+        const candidate = Buffer.from(v1, 'hex');
+        if (candidate.length !== expected.length)
+            continue;
+        if (timingSafeEqual(candidate, expected))
+            return { valid: true };
+    }
+    return { valid: false, reason: 'no_signature_match' };
+}
+function parseHeader(header) {
+    const parts = header.split(',').map((s) => s.trim());
+    let t = null;
+    const v1s = [];
+    for (const p of parts) {
+        const eq = p.indexOf('=');
+        if (eq < 0)
+            return null;
+        const key = p.slice(0, eq);
+        const val = p.slice(eq + 1);
+        if (key === 't') {
+            const n = Number.parseInt(val, 10);
+            if (!Number.isFinite(n) || n <= 0)
+                return null;
+            t = n;
+        }
+        else if (key === 'v1') {
+            if (!/^[0-9a-f]+$/.test(val))
+                return null;
+            v1s.push(val);
+        }
+    }
+    if (t === null || v1s.length === 0)
+        return null;
+    return { timestampSec: t, v1Hexes: v1s };
+}

package/llms.txt

@@ -0,0 +1,84 @@
+# Build with @xkova/sdk
+
+Use this package on a Node.js 22+ server. Read the installed declarations before writing code: live documentation may describe a newer release. Use @xkova/browser for browser calls to your own same-origin backend for frontend (BFF).
+
+## Read first
+
+- [Package guide](README.md): installation, production signing, Hosted Auth, member sessions, durable stores, cancellation, errors, webhooks, and proof verification.
+- [Client declarations](dist/client.d.ts): exact resource properties and client options for this installed release.
+- [Customer API types](dist/generated/types.d.ts): exact request bodies, responses, parameters, and operation IDs. Import types through @xkova/sdk/types.
+- [Member BFF declarations](dist/member-bff.d.ts): authorization, session persistence, refresh, logout, action reviews, and human authorization.
+- [Member resources](dist/member-resources.d.ts): typed resources bound to the exact authenticated member.
+- [Quickstart](https://docs.xkova.com/getting-started.html): sandbox access and first authenticated call.
+- [Customer OpenAPI](https://docs.xkova.com/data/openapi-customer.json): machine-readable customer contract for the current published documentation.
+- [SDK guide](https://docs.xkova.com/sdk-overview.html): client and resource examples.
+- [Workflow guide](https://docs.xkova.com/sdk-workflows.html): supported workflow helpers.
+- [Member integration](https://docs.xkova.com/embedded-member.html): browser, BFF, identity, and signing boundaries.
+- [Documentation index](https://docs.xkova.com/llms.txt): current public feature guides.
+- [Full documentation](https://docs.xkova.com/llms-full.txt): expanded public guidance. Console concepts do not imply SDK methods.
+
+## Choose a client
+
+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. Institution staff and management: use the Console and its documented setup flows. Do not invent customer SDK methods for API-key lifecycle, treasury administration, staff governance, or platform management.
+
+## Find a capability
+
+Each namespace below is a property of XKOVAClient. Read its declaration under dist/resources/ for exact methods and parameters.
+
+| Need | Namespace or entry point |
+| --- | --- |
+| Discover supported networks and usable assets | chains, workspaceTokens, workspaces |
+| Account holders, consent, profile, avatar, balances, verification, history | accountHolders; resolveResources().self for a member |
+| Wallets and coordinated provisioning | wallets; resolveResources().self for a member |
+| Contacts and recipients | contacts |
+| Quotes, payments, status, cancellation | payments |
+| Escrow creation, status, events, cancellation initialization | escrows |
+| Funding and payment requests | paymentRequests |
+| Deposits, conversion, withdrawals, off-ramp status | ramps |
+| Transaction history | transactions |
+| Fee schedules and platform fees | feeSchedules |
+| Customer tokens, deployment, minting, supply, access | tokenization |
+| Real-world assets, cap tables, distributions, corporate actions, provenance | rwa |
+| Gateway registration and conformance | integrationGateways |
+| Branding and sending-domain configuration | branding |
+| Tenant reads, Hosted application registration, exact origins and callbacks | tenant |
+| Setup progress | onboarding |
+| 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 |
+| Verify webhook signatures over raw body bytes | @xkova/sdk/webhook |
+| Offline RWA transparency proofs | @xkova/sdk/rwa-verify |
+| Customer contract ABIs | @xkova/sdk/abi |
+
+API availability does not grant permission. Product entitlement, selected API-key scopes and roles, account eligibility, configured policies, and required human approval still apply. Production outbound operations require explicit institution policy setup. Discover chains and assets; never silently pick the first or assume a default network.
+
+## Requests and results
+
+- Start with the README's sandbox read example. Validate required environment variables on the server; never emit their values into logs, generated files, browser bundles, or prompts.
+- Use exported package entry points and typed resource methods. Do not import dist files as runtime subpaths, use private endpoints, 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.
+- 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.
+- For webhooks, verify the signature against the exact raw body before parsing or acting. Deduplicate event processing and reconcile authoritative resource status. An accepted request, signing result, or 202 response is not settled money.
+
+## Member applications
+
+- Keep the API key, provider proof, XKOVA member session, and refresh credentials server-side. Never accept a caller-selected acting account holder or browser-provided member authority.
+- Register exact application origins and callbacks. Enforce the browser Origin and a session-bound CSRF proof for mutations. Durable cookies are host-only, Secure, HttpOnly, Path=/, and SameSite=Strict. A short-lived SameSite=Lax transaction cookie is only for cross-site authorization callbacks.
+- Implement durable session and authorization transaction stores from the exported contracts. Serialize refresh/logout across BFF replicas and encrypt sensitive records at rest. An in-memory demonstration is not a production store.
+- Hosted Auth is optional. Your registered identity provider determines proof verification and fresh human authorization. Do not silently switch providers or substitute Hosted login for a customer's configured identity flow.
+- Reuse one createMemberActionReference() from @xkova/browser for a durable review. Save the draft before setup detours. Expired or missing reviews require checking activity and an explicit new review.
+- Setup readiness is advisory. beginMemberAction() and completeMemberAction() obtain fresh approval for the exact resource. Browser code must not receive provider wallet credentials or internal signing capabilities. Completion of authorization is distinct from execution and settlement.
+
+## Dependencies
+
+The server SDK uses viem for offline RWA signature verification. The browser companion has no runtime dependencies. Neither imports Thirdweb. You may see Thirdweb in API provider metadata, but these integrations require no Thirdweb SDK or credentials.
+
+## Before handing off code
+
+List the Console setup and stores the application needs. Test denied access, uncertain writes, pagination, cancellation, and terminal outcomes. Report a missing method or setup requirement explicitly. Do not invent methods, suppress type errors, or bypass authorization to make an example run.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@xkova/sdk",
+  "version": "0.1.0-alpha.1",
+  "description": "Server-side TypeScript client for the XKOVA customer API, with customer-only generated types and production request signing.",
+  "homepage": "https://docs.xkova.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XKOVA/typescript-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/XKOVA/typescript-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/generated/types.d.ts",
+      "default": "./dist/generated/types.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./member-bff": {
+      "types": "./dist/member-bff.d.ts",
+      "default": "./dist/member-bff.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook.d.ts",
+      "default": "./dist/webhook.js"
+    },
+    "./rwa-verify": {
+      "types": "./dist/rwa-verify.d.ts",
+      "default": "./dist/rwa-verify.js"
+    },
+    "./abi": {
+      "types": "./dist/abi.d.ts",
+      "default": "./dist/abi.js"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}