@xkova/sdk 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,453 @@
+# @xkova/sdk
+
+TypeScript client for the XKOVA API. Use it on your server to manage account
+holders, wallets, payments, tokenization, and other customer resources.
+
+## Install
+
+```bash
+npm install @xkova/sdk@0.1.0-alpha.1
+```
+
+Requires Node.js 22 or newer. Keep this package and your API keys on the server.
+
+For a web application with signed-in account holders, use the included
+`@xkova/sdk/member-bff` helper to manage sessions in your backend for frontend
+(BFF). The optional `@xkova/browser` package calls that BFF from the browser.
+
+## Create a client
+
+```ts
+import { XKOVAClient } from '@xkova/sdk';
+
+const xkova = XKOVAClient.forTenant({
+  baseUrl: 'https://sandbox-api.xkova.com',
+  apiKey: process.env.XKOVA_API_KEY!,
+  timeoutMs: 10_000,
+});
+
+const chains = await xkova.chains.listAvailable();
+const assets = await xkova.workspaceTokens.list();
+```
+
+Create one client per workspace API key. The key determines the tenant,
+workspace, and environment. You can pass an API origin or a URL ending in `/v1`.
+Failed API requests throw `XKOVAApiError`.
+
+## Production request signing
+
+Production writes require your bearer API key and an active signing credential
+registered to the same API principal. Supply the credential ID, algorithm, and
+a callback to your key provider:
+
+```ts
+import { XKOVAClient, type XKOVARequestSignInput } from '@xkova/sdk';
+
+async function signWithCustomerKey(input: XKOVARequestSignInput): Promise<Uint8Array> {
+  // Adapt this call to your KMS or HSM. Return signature bytes, not base64 text.
+  return customerKeyProvider.sign(input);
+}
+
+const production = XKOVAClient.forTenant({
+  baseUrl: 'https://api.xkova.com',
+  apiKey: process.env.XKOVA_API_KEY!,
+  requestSigner: {
+    credentialId: process.env.XKOVA_SIGNING_CREDENTIAL_ID!,
+    algorithm: 'ecdsa-p256-sha256',
+    sign: signWithCustomerKey,
+  },
+});
+```
+
+The private key stays with your key provider. The callback must return:
+
+| Algorithm           | Signature format                                       |
+| ------------------- | ------------------------------------------------------ |
+| `ecdsa-p256-sha256` | 64-byte IEEE P1363                                     |
+| `ed25519`           | 64 bytes                                               |
+| `rsa-pss-sha256`    | RSA-PSS with SHA-256, MGF1 SHA-256, and a 32-byte salt |
+
+The optional `lifetimeSeconds` accepts an integer from 30 to 60; the default is 45. The registered credential determines the algorithm. XKOVA omits the RFC
+9421 `alg` parameter because that RFC has no `rsa-pss-sha256` identifier.
+
+The SDK sets `Signature-Input` and `Signature` using RFC 9421. Requests with a
+body also receive an RFC 9530 SHA-256 `Content-Digest`. The signature covers the
+destination, path, query, authorization, body metadata, idempotency key, and
+XKOVA routing and member headers. The SDK serializes the body once, so it signs
+the same bytes it sends.
+
+Send signed requests to the configured public API origin. A proxy that changes
+the `Host` authority will cause signature verification to fail.
+
+A production write fails before sending if no signer is configured. Production
+reads use bearer authentication. Sandbox requests need the API key; sandbox
+writes are signed only when you configure `requestSigner`.
+
+Each call gets a fresh nonce and signature. To retry a write, call the method
+again with the same idempotency key and unchanged input. Manage signing
+credentials in the Console.
+
+Key rotation requires proof of possession of the successor key. Activation
+allows five minutes of overlap with the previous key. Each credential can have
+one live successor; either key can be revoked immediately.
+
+## Typed resources
+
+Call resource methods with typed inputs:
+
+```ts
+const quote = await xkova.payments.quote(
+  {
+    account_holder_id: 'ah_...',
+    from_wallet_id: 'wlt_...',
+    to_address: '0x...',
+    token_deployment_id: '...',
+    gross_amount: '25.00',
+  },
+  { idempotencyKey: crypto.randomUUID() },
+);
+
+const contacts = await xkova.contacts.list({ limit: 25 });
+const paymentRequests = await xkova.paymentRequests.list({ limit: 25 });
+```
+
+Writes accept an optional caller-provided `idempotencyKey`. Reuse the same key when retrying the same logical request. If omitted, the SDK generates a new key for that individual call.
+
+Account-holder `self` methods require a member session and its application's
+publishable key. Load both from your BFF's session store. These methods act on
+the signed-in account holder; browser input cannot select a different person:
+
+```ts
+const balance = await xkova.accountHolders.selfBalance({
+  memberSessionId: session.sessionId,
+  memberAuthPublishableKey: session.applicationData.memberAuthPublishableKey,
+});
+```
+
+## Register a Hosted Auth application
+
+Hosted Auth provides an optional XKOVA-hosted sign-in flow. Register an
+application against an existing API principal in the same workspace, then add
+its exact origin and callback URL:
+
+```ts
+const application = await xkova.tenant.createHostedApplication({
+  api_key_id: 'key_1A2b3C4d5E6f7G8h9I0jK1',
+  name: 'Acme Member App',
+  enrollment_mode: 'invite_only',
+  is_default: true,
+});
+
+await xkova.tenant.createAllowedOrigin({
+  application_id: application.id,
+  origin: 'https://app.example.com',
+});
+
+await xkova.tenant.createRedirectUrl({
+  application_id: application.id,
+  purpose: 'authorization_result',
+  url: 'https://app.example.com/api/auth/callback',
+});
+
+const applications = await xkova.tenant.listMemberAuthApplications();
+await xkova.tenant.updateHostedApplication(application.id, {
+  enrollment_mode: 'open',
+});
+await xkova.tenant.disableHostedApplication(application.id);
+```
+
+The response includes a publishable key that identifies the application. It is
+not a secret and grants no authority on its own. You control the name,
+enrollment policy, default selection, allowed origins, callbacks, and enabled
+state. XKOVA manages the Hosted identity provider.
+
+## Member BFF integration
+
+Use `@xkova/sdk/member-bff` to manage account-holder authentication and sessions:
+
+```ts
+import { XKOVAMemberBffClient, serializeXKOVAMemberSessionCookie } from '@xkova/sdk/member-bff';
+
+const memberAuth = new XKOVAMemberBffClient({
+  baseUrl: process.env.XKOVA_API_URL!,
+  apiKey: process.env.XKOVA_API_KEY!,
+  publishableKey: process.env.XKOVA_PUBLISHABLE_KEY!,
+  requestSigner,
+});
+
+const start = await memberAuth.beginHostedAuthorization({
+  browserOrigin: 'https://app.example.com',
+  redirectUri: 'https://app.example.com/api/auth/callback',
+  transactionStore,
+});
+
+// Redirect only to start.authorizationUrl. Store start.state in the
+// short-lived SameSite=Lax flow cookie, then recover it at callback.
+const established = await memberAuth.completeHostedAuthorization({
+  callbackUrl: request.url,
+  expectedState: flowCookieState,
+  transactionStore,
+  sessionStore,
+  applicationData: {},
+});
+```
+
+For your own OIDC provider, use `beginAuthorization` and
+`completeAuthorizationCallback`. Your BFF exchanges the provider's authorization
+code unless your integration explicitly assigns that exchange to XKOVA. Both
+sign-in paths use the same XKOVA session and store contracts.
+
+### Sandbox demo sign-in
+
+For a sandbox application explicitly enabled for demo sign-in, call
+`completeSandboxDemoAuthorization({ state: start.state, transactionStore })`
+after `beginHostedAuthorization`. The SDK obtains the capability and exact
+callback from the server-held transaction, validates the returned callback and
+expiry, and returns `{ callbackUrl, expiresAt }`. Complete that callback through
+`completeHostedAuthorization` with the original browser flow cookie. The API
+reserves a demo account for the session. This operation is not
+available to ordinary tenant applications or production workspaces, and it
+accepts no member, email, wallet, or callback selector.
+
+Keep the same pending reservation and transaction after an ambiguous admission
+failure. Repeating the method uses the same idempotency key and recovers the
+same demo account reservation. The method never retries automatically.
+`isDefinitiveXKOVASandboxDemoAdmissionFailure(error)` identifies confirmed
+rejection before an account was reserved; network, malformed-response, and
+unknown server failures can leave the reservation outcome uncertain.
+API errors retain their status, correlation ID, and Retry-After. Both admission
+and session requests reject HTTP redirects.
+
+### Stores and callback recovery
+
+The helper creates state, nonce, and PKCE values, validates callbacks, exchanges
+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.
+
+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
+clock synchronized so it can validate these deadlines.
+
+After your authorization store persists `stagedProviderExchange`, repeating
+the same callback reuses the stored proof, exchange attempt, and session
+reference. It does not redeem the provider code again. Keep completed records
+until their expiry so a lost response or store acknowledgement can recover the
+session that was already created.
+
+Before that record is stored, a lost provider response or store acknowledgement
+may cause another call to `exchangeProviderCode`. Your provider adapter must
+resolve that uncertainty or reject the attempt and start a new authorization
+transaction. For later recoverable failures, preserve the flow cookie and
+transaction. `XKOVAMemberAuthorizationTerminalError` means the transaction
+cannot continue.
+
+Recovery records bind the API origin, principal, and application. A shared store
+can serve several applications, but one client cannot resume another's records.
+
+If `exchangeProviderCode` returns a separate `nonceToken`, validate its JOSE
+signature, issuer, audience, algorithm, expiry, and nonce first. The helper only
+compares its nonce claim; XKOVA cannot validate a token it never receives.
+
+To exchange a proof without a browser callback, call `establishSession` with an
+`XKOVAMemberProofExchangeTransactionStore`, a session store, and a stable
+`exchangeId`. Persist that ID before the first attempt and reuse it on retries.
+The store serializes attempts and preserves the exchange and session references.
+
+### Account Center and action callbacks
+
+Account Center accepts a same-origin `applicationReturnUri` and preserves it
+through successful callback recovery. Member actions separately accept
+`applicationReviewUri` for cancellation or expiry and `applicationReturnUri`
+for the signing-completion destination. The exact resource and review location
+stay in the confidential transaction. Callback query parameters cannot override
+them. Terminal errors expose a stored review location only after validating the
+client fingerprint and exact callback; missing transactions have no trusted
+return location. They must use a neutral result screen, not guess an action.
+
+Use `xkovaMemberFlowCookieName(prefix, state)` when setting the short-lived
+HttpOnly Lax cookie and `readXKOVAMemberCallbackFlow()` when receiving the callback.
+Each ceremony gets a distinct cookie, so concurrent tabs do not replace one
+another's binding. Clear only the returned `cookieName` on completion or a
+terminal error. Preserve both the cookie and durable transaction after a
+recoverable failure. Never clear the ordinary application-session cookie just
+because an action failed. These helpers do not themselves persist unfinished
+form input or deduplicate business-resource creation.
+
+### Save and recover a payment review
+
+Use `resolveActionIntents({ reference, sessionStore, intentStore })` to preserve
+a review across reloads and authentication steps. The manager is bound to the
+principal, application, member, and opaque application session. Its `create()`
+stores a frozen typed payment, escrow, or payment-request approval plus reviewed
+form fields and an exact same-origin review URI. It creates no business resource.
+`read()` restores that review. Explicit `prepare()` serializes across replicas,
+uses one stable creation idempotency key, and persists the resulting resource.
+An ambiguous create/store acknowledgement can retry the identical request with
+that same key. A changed request is a conflict, not a replacement. Signing and
+execution remain separate, freshly authorized operations.
+
+Generate the public review reference once with `createMemberActionReference()`
+from `@xkova/browser`. It contains a six-byte millisecond creation time and 26
+random bytes, encoded as 43 base64url characters. It grants no authority. The
+server enforces one-hour expiry and at most five minutes of future clock skew.
+Even after complete store loss, the same old reference cannot restart after the
+API's 24-hour idempotency window. The store must encrypt review payloads at rest,
+serialize each reference across replicas, and retain records through
+`retainUntil` (the application session), not just the shorter review expiry.
+Expired references return 410. Unknown or differently bound reviews return 404.
+Do not silently create a new reference after either result; ask the person to
+check activity and explicitly start a separate review.
+
+### Authorize an action
+
+For payment, escrow, or member approval signing, use
+`beginMemberAction()` and `completeMemberAction()` from the BFF helper. The
+begin result selects the registered method: a Hosted application redirects to
+the branded Account Center passkey ceremony. Your own OIDC integration receives
+the required issuer, audience, nonce, maximum authentication age, ACR, and AMR
+requirements for a fresh provider proof. Completion exchanges the one-use
+result into a signing projection. The BFF then calls
+`exchangeMemberActionSigningCode()` server-side and sets the returned opaque
+signing session only on XKOVA's controlled signing surface. Do not place the
+exchange code, member session, provider proof, or wallet signing credentials in
+browser-accessible storage.
+
+### Call resources for the signed-in member
+
+Validate the browser's exact Origin and session-bound CSRF token in your BFF
+before handling a mutation. Resolve the session for each request:
+
+```ts
+const resolved = await memberAuth.resolveResources({ reference, sessionStore });
+if (!resolved) return new Response('Sign in required', { status: 401 });
+const readiness = await resolved.resources.self.walletReadiness();
+const security = await resolved.resources.self.actionReadiness();
+const payment = await resolved.resources.payments.retrieve('pay_...');
+```
+
+`self.actionReadiness()` reports passkey enrollment, recovery steps, or OIDC
+setup without calling the provider or creating an action. Refresh it after
+Account Center or credential changes. `requires_fresh_proof` stays true and
+`provider_status` is `not_checked`: readiness describes setup, not approval or
+provider health. Ownership, policy, quorum, and settlement still need their
+own checks. A failed read must not enable an action.
+
+`resolveResources` refreshes and validates the session, then binds every call
+to its principal, application, and account holder. It rejects conflicting
+session headers and actor overrides before sending. Resolve it for each BFF
+request; do not cache it or send it to the browser. API scopes, roles, ownership,
+revocation, and fresh authorization checks still apply.
+
+Business requests use `no-store` and reject redirects so credentials cannot
+follow a redirect. Network failures preserve the application session. Reuse the
+original idempotency key when reconciling an uncertain write.
+
+`resolved.resources.self.verification()` returns the member's verification
+requirements and sessions through the public self-verification operation.
+`resolved.resources.self.uploadAvatar(image)` performs presign, object upload,
+confirmation, and refreshed avatar lookup. Pass a nonempty PNG, JPEG, WebP, or GIF
+`Blob` of at most 5 MiB. Storage receives only the image bytes and their content
+headers, never bearer credentials, request signatures, member context, or cookies.
+The helper rejects redirects, expired capabilities, URL credentials, and non-HTTPS
+storage URLs (localhost HTTP is permitted for local development). It does not
+retry an upload. `XKOVAUploadError` identifies the object-storage stage without
+exposing the signed URL; API failures retain `XKOVAApiError` metadata.
+
+In sandbox, `resolved.resources.self.sandboxBankingContext()` returns the
+member's simulated bank account and funding references. Keep them server-side
+and pass them to the funding and off-ramp methods. This read creates no accounts
+and moves no money. It rejects a mismatched tenant and returns 404 in production.
+
+### Session storage and cookies
+
+Your application owns the routes, identity-provider integration, database,
+deployment, and store encryption. Authorization and proof-exchange records can
+contain provider proofs; protect them like refresh credentials. Serialize
+refresh and logout for each session reference across all BFF instances.
+
+Durable application cookies use the host-only `__Host-` prefix, `Secure`, `HttpOnly`, `Path=/`, and `SameSite=Strict`. A separate short-lived `SameSite=Lax` flow cookie is available only for OAuth or OIDC callback state. Do not send the API key, provider proof, XKOVA session ID, refresh token, or provider credentials to browser SDK code.
+
+The publishable key is a non-secret application registration identifier. It grants no member or tenant authority by itself. The registered application pins tenant, workspace, environment, provider kind, issuer, audience, origins, redirects, and session policy, and must also match the authenticated workspace principal.
+
+## Cancellation and deadlines
+
+Set `timeoutMs` on the client for a default request deadline. Mutation options and workflow polling also accept an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+await xkova.payments.cancel('pay_...', {
+  idempotencyKey: crypto.randomUUID(),
+  signal: controller.signal,
+});
+```
+
+The SDK does not automatically retry writes. Use `withRetry` with a stable idempotency key when retry behavior is appropriate for your application.
+
+## Errors
+
+`XKOVAApiError.retryAfter` preserves the upstream `Retry-After` header when
+present. A BFF should forward valid retry guidance with the original status and
+correlation ID. This is response metadata, not automatic mutation retry.
+
+```ts
+import { XKOVAApiError } from '@xkova/sdk/errors';
+
+try {
+  await xkova.payments.retrieve('pay_...');
+} catch (error) {
+  if (error instanceof XKOVAApiError) {
+    console.error(error.code, error.correlationId);
+  }
+  throw error;
+}
+```
+
+## Webhooks and generated types
+
+```ts
+import { verifyWebhookSignature } from '@xkova/sdk/webhook';
+import type { components, paths } from '@xkova/sdk/types';
+```
+
+Pass the raw request body to `verifyWebhookSignature`. The `types` subpath contains only the customer operations included in this SDK release.
+
+The package also exposes `@xkova/sdk/rwa-verify` for offline RWA transparency proof verification and `@xkova/sdk/abi` for the documented customer contract ABIs.
+
+## Compatibility and documentation
+
+This release targets API namespace `/v1` and Node.js 22+. See the
+[XKOVA documentation](https://docs.xkova.com) for API and workflow guides. The
+installed declarations list the methods in your version. Use the Console for
+staff administration, API-key management, and signing-key registration.
+
+## Build with a coding assistant
+
+Give your coding assistant the package-local [llms.txt](llms.txt), this README,
+and the installed package declarations. The guide maps capabilities to resource
+namespaces and explains authentication, production signing, member BFF stores,
+idempotency, and settlement. It links the public customer OpenAPI and expanded
+documentation. Installed declarations determine the methods available in your
+version; live documentation may describe a newer release.
+
+## Thirdweb and dependencies
+
+The only direct runtime dependency is `viem`, used for offline RWA signature
+verification. This SDK does not import Thirdweb. The optional `@xkova/browser`
+browser companion has no runtime dependencies. XKOVA manages wallet signing,
+and API provider metadata may name Thirdweb. You do not need to install its SDK
+or obtain Thirdweb credentials.
+
+## Contributing
+
+Run `pnpm check` from the source repository root before committing. The
+[contributor guide](https://github.com/XKOVA/typescript-sdk/blob/main/CONTRIBUTING.md)
+covers generated files, local pre-push checks, writing rules, and packaging.
+
+## License
+
+Copyright 2026 XKOVA LLC.
+
+This package is licensed under the [Apache License, Version 2.0](LICENSE).