@keyhalve/node-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Attestura, LLC (KeyHalve)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,419 @@
+# @keyhalve/node-sdk
+
+KeyHalve SDK for Node.js — the **blind-rail** document-verification core. Seal a
+document so it can be verified later, with the decryption key split so **no single
+party — not the platform, not KeyHalve — can read it.** Payloads are encrypted on
+your server before anything leaves the box; the platform stores only ciphertext,
+KeyHalve's rail holds one blind share, and the verifier reconstructs in-browser.
+
+- **End-Cell (recommended)** — a 3-share split: the QR (ShareA) ⊕ the platform ⊕ the independent **KeyHalve rail**. No single holder can reassemble the key.
+- **AES-256-GCM** authenticated encryption (tampering detected on decrypt)
+- **SHA-256 commitment** — detects any server-side tampering with the ciphertext
+- **Pinned-rail verification** — the rail's Ed25519 signature is checked against a key shipped in the SDK; fails closed on any doubt
+- **Split-key** (simpler 2-share) + **selective disclosure**, **time-lock**, **revocation**, **QR placement** helpers
+- **Zero production dependencies** — Node built-in `crypto` + native `fetch`; TypeScript-first, ESM-only, Node `>= 20`
+- The encryption key is **never** sent to the platform API or to KeyHalve
+
+> KeyHalve is the independent blind rail. This SDK is platform-agnostic — point
+> `baseUrl` at the issuing platform's API; the KeyHalve rail is the only fixed
+> dependency. (ValidPay's own SDK lives at `@validpay/node-sdk`.)
+
+## Install
+
+```bash
+npm install @keyhalve/node-sdk
+```
+
+## Quick start
+
+```ts
+import { KeyHalveClient } from "@keyhalve/node-sdk";
+
+const client = new KeyHalveClient({ apiKey: process.env.PLATFORM_API_KEY! });
+
+// 1. Issuer side — seal with End-Cell (recommended). The AES key is split
+//    THREE ways: `key` is ShareA (rides the QR); one share goes to the
+//    platform; one goes to the independent KeyHalve rail. No single party —
+//    not the platform, not KeyHalve — can read or reassemble the key.
+const { retrievalId, key } = await client.createEndCellIntent({
+  documentType: "ssn_card",
+  payload: { ssn: "123-45-6789", name: "Jane Doe" },
+  // holders defaults to ["keyhalve", "platform"] → a 3-of-3 split with ShareA
+});
+
+// retrievalId is public (e.g. "vp_abc123def456") — embed in a QR code.
+// key (ShareA) is secret — deliver it ONLY to the intended verifier, out-of-band.
+
+// 2. Verifier side — fetch and decrypt (no API key needed). verifyIntent
+//    fetches the platform share + the rail share (the rail's Ed25519 signature
+//    is verified against a PINNED key, fail-closed), recombines in memory,
+//    decrypts locally, and re-checks the commitment hash.
+const result = await client.verifyIntent<{ ssn: string; name: string }>(retrievalId, key);
+
+console.log(result.payload);             // { ssn: "123-45-6789", name: "Jane Doe" }
+console.log(result.integrityVerified);   // true — commitment hash matched
+console.log(result.issuer);              // "Acme Bank"
+console.log(result.issuerVerified);      // true
+```
+
+> **Simpler 2-share option:** `createSplitKeyIntent()` splits the key between the
+> document and the platform only — no independent rail share, so the platform
+> alone could reconstruct. `createIntent()` also defaults to split-key. Prefer
+> **End-Cell** above when independence from the platform matters.
+
+### Building a verification URL
+
+The `retrievalId` is public; the `key` is secret. Stamp them into a URL fragment (the `#` part — fragments are never sent to the server, even by curl) so a single link both identifies the intent and decrypts it:
+
+```ts
+function toBase64Url(b64: string): string {
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+const verifyUrl = `https://verify.keyhalve.com/verify/${retrievalId}#key=${toBase64Url(key)}`;
+// → encode in a QR, paste in an email, scan with a phone camera.
+// The /verify page reads the fragment client-side and decrypts locally.
+```
+
+`toBase64Url` matters because phone QR scanners + browser share-sheets mangle `+`, `/`, and `=` in URL fragments. The `/verify` page accepts both standard base64 and base64url for backward compatibility, but new links should always emit base64url.
+
+### Placing the QR on a document (`embedQr`)
+
+For a PDF, `embedQr` builds the verify QR and stamps it onto the page for you — so you don't have to wire up a QR library, base64url the key, or wrestle with PDF coordinates (PDFs use a bottom-left origin; everything else uses top-left).
+
+`embedQr` needs two **optional** peer dependencies — the core client stays dependency-free, so install them only if you use it:
+
+```bash
+npm i pdf-lib qrcode
+```
+
+```ts
+import { KeyHalveClient, embedQr } from "@keyhalve/node-sdk";
+import { readFile, writeFile } from "node:fs/promises";
+
+const client = new KeyHalveClient({ apiKey: process.env.PLATFORM_API_KEY! });
+
+const original = await readFile("invoice.pdf");
+const { retrievalId, key } = await client.createFileIntent({
+  documentType: "invoice",
+  file: original,
+  fileContentType: "application/pdf",
+});
+
+const sealed = await embedQr(original, {
+  retrievalId,
+  key,
+  // 90pt (1.25in) QR, 36pt in from the bottom-right corner.
+  placement: { anchor: "bottom-right", x: 36, y: 36, width: 90 },
+});
+await writeFile("invoice-sealed.pdf", sealed);
+```
+
+#### The placement contract
+
+Coordinates read the way you think about a page, and are identical to what the **"Try it" placement tool** in the developer console emits — so position once in the UI, copy the call, and it lands in the same spot.
+
+| field    | meaning | default |
+| -------- | ------- | ------- |
+| `anchor` | which page **corner** the insets are measured from (`top-left` \| `top-right` \| `bottom-left` \| `bottom-right`) | `top-left` |
+| `x`      | horizontal inset from that corner's vertical edge | — |
+| `y`      | vertical inset from that corner's horizontal edge | — |
+| `width`  | QR side length (it's square) | — |
+| `units`  | `pt` (1/72in) \| `mm` \| `in` | `pt` |
+| `page`   | 1-based page number | `1` |
+
+`{ anchor: "bottom-right", x: 36, y: 36, width: 90 }` sits 36pt in from the bottom and right edges — and stays bottom-right on any page size. Keep the QR **≥ ~72pt (1in)** so it scans reliably once printed; `embedQr` warns below that and throws if the placement runs off the page.
+
+If you render PDFs with a different library, the two pure helpers are exported too:
+
+```ts
+import { buildVerifyUrl, resolveQrRect } from "@keyhalve/node-sdk";
+
+const url  = buildVerifyUrl(retrievalId, key);               // base64url key in the fragment
+const rect = resolveQrRect(placement, pageWidthPt, pageHeightPt); // → { x, y, size } in pdf bottom-left points
+```
+
+## How it works
+
+1. `createIntent` generates a fresh 256-bit key, encrypts your payload locally with AES-256-GCM, computes a SHA-256 commitment hash of the plaintext, and POSTs only the ciphertext + hash to `POST /v1/intent`.
+2. The API returns a public `retrieval_id` and stores the ciphertext + commitment hash.
+3. You hand the verifier the `retrievalId` and the `key` through your own secure channel.
+4. The verifier calls `verifyIntent`, which fetches `GET /v1/intent/:id`, decrypts the ciphertext locally, then recomputes the commitment hash and compares — any server-side tampering would change the hash.
+
+The key is generated client-side, used client-side, and transmitted client-side. Neither the platform nor KeyHalve can read the payload.
+
+## API reference
+
+### `new KeyHalveClient(options)`
+
+| Option    | Type                | Default                     | Notes                                       |
+| --------- | ------------------- | --------------------------- | ------------------------------------------- |
+| `apiKey`  | `string` (required) | —                           | Your issuing platform API key.               |
+| `baseUrl` | `string` (required) | —                           | The issuing platform's API base (e.g. your own API). No platform default. |
+| `timeout` | `number`            | `30000`                     | Request timeout (ms).                       |
+| `fetch`   | `typeof fetch`      | global `fetch`              | Inject a custom fetch (useful for testing). |
+
+### End-Cell (recommended)
+
+#### `client.createEndCellIntent({ documentType, payload, holders?, validFrom?, validUntil?, onBehalfOf? }) → { retrievalId, key }`
+
+KeyHalve's blind-rail flow. Generates a key, encrypts `JSON.stringify(payload)`, and XOR-splits the key into **ShareA** (returned as `key`, for the QR) plus one share per holder. `holders` defaults to `["keyhalve", "platform"]` → a **3-of-3** split: the independent KeyHalve rail share + the platform share + ShareA. No single party can read or reassemble the key. Verify with `verifyIntent` (below), which fetches the platform + rail shares, verifies the rail's Ed25519 signature against a **pinned** key (fail-closed), recombines in memory, and decrypts. **The full key never exists on any single system.** Requires the API deployment to have End-Cell issuance enabled.
+
+```ts
+const { retrievalId, key } = await client.createEndCellIntent({
+  documentType: "ssn_card",
+  payload: { ssn: "123-45-6789" },
+});
+const result = await client.verifyIntent(retrievalId, key); // one call handles all share models
+```
+
+### Core
+
+#### `client.createIntent({ documentType, payload, validFrom?, validUntil?, splitKey?, onBehalfOf? }) → { retrievalId, key }`
+
+Generates a key, encrypts `JSON.stringify(payload)`, posts ciphertext + commitment hash to `/v1/intent`. Defaults to **split-key** (2-share): the returned `key` is Share A and Share B goes to the platform — neither alone decrypts, but there is **no independent rail share** (the platform alone could reconstruct). For independence from the platform, prefer **`createEndCellIntent`** above. Pass `splitKey: false` for the legacy single-key flow. **The full key is never sent to the API.**
+
+#### `client.createIntentBatch(items[]) → { retrievalId, key }[]`
+
+Same as `createIntent` for up to 100 intents in a single request. Each item gets a unique AES key; results match the input order.
+
+#### `client.verifyIntent<T>(retrievalId, key) → VerifyIntentResult<T>`
+
+Fetches the intent and decrypts the payload locally. Verifies the commitment hash. Throws `KeyHalveError`:
+
+- `decryption_failed` — wrong key or tampered ciphertext (GCM auth-tag failure)
+- `integrity_failure` — commitment hash mismatch (server-side tampering detected)
+- `intent_revoked` — the intent has been revoked
+- `split_key_required` / `selective_disclosure_required` — use the specialised verify method
+
+```ts
+interface VerifyIntentResult<T> {
+  intentId: string;
+  payload: T;
+  issuer: string;
+  issuerVerified: boolean;
+  registeredAt: string; // ISO 8601
+  status: string;
+  integrityVerified: boolean;
+  validFrom?: string | null;
+  validUntil?: string | null;
+  timeLockStatus?: "valid" | "not_yet_valid" | "expired" | null;
+}
+```
+
+### Split-key (Patent C) — the default
+
+All documents created with SDK v0.4+ use split-key by default — `createIntent`
+returns Share A and stores Share B at the API; `verifyIntent` detects a
+split-key intent, fetches Share B from `/v1/intent/:id/fragment`,
+XOR-combines, and decrypts:
+
+```ts
+const { retrievalId, key: shareA } = await client.createIntent({
+  documentType: "ssn_card",
+  payload: { ssn: "123-45-6789" },
+});
+// shareA goes in the QR; shareB stays at the API.
+
+const result = await client.verifyIntent(retrievalId, shareA);
+```
+
+Backward compatibility: `createIntent({ ..., splitKey: false })` gives the
+legacy single-key flow; `createSplitKeyIntent()` is a deprecated alias of
+`createIntent()` (emits a `DeprecationWarning`); `verifySplitKeyIntent()`
+still works.
+
+### Platform delegation — `onBehalfOf`
+
+If you integrate as a **platform** and seal on behalf of the businesses you
+serve, name the business on each seal. The verifier sees that business as the
+issuer ("who"), attributed *through* your platform ("through whom"), at the
+`delegated` trust rung. The businesses never touch the platform — no account, no
+login — and the platform stays blind to the document contents.
+
+```ts
+const { retrievalId, key } = await client.createIntent({
+  documentType: "lease",
+  payload: { unit: "4B", term: "12mo" },
+  onBehalfOf: {
+    ref: "landlord_8675309",        // YOUR id for this business (the dedupe key)
+    name: "Smith Properties LLC",   // who the verifier sees
+  },
+});
+
+const result = await client.verifyIntent(retrievalId, key);
+result.issuer;            // "Smith Properties LLC"
+result.verificationLevel; // "delegated"
+result.delegatedBy;       // { platform: "Your Platform", platformLevel: "domain" }
+```
+
+Same `ref` ⇒ same tracked business (its documents and verification counts roll
+up). A sub-issuer surfaces as `delegated` only once **your** platform account is
+domain-verified; until then its documents show as unverified.
+
+### Selective disclosure (Patent E)
+
+```ts
+const { retrievalId, key } = await client.createSelectiveIntent({
+  documentType: "check",
+  payload: { amount: 1500, payee: "Alice", memo: "rent" },
+  disclosurePolicy: {
+    bank: ["amount"],
+    auditor: ["amount", "payee"],
+  },
+});
+
+const bankView = await client.verifySelectiveIntent(retrievalId, key, "bank");
+// { amount: 1500, payee: "[REDACTED]", memo: "[REDACTED]" }
+
+const fullView = await client.verifySelectiveIntent(retrievalId, key, "full");
+// { amount: 1500, payee: "Alice", memo: "rent" }
+```
+
+### Audit + list (Prompt 080)
+
+When you need to reconcile your own records against the platform — "how many intents did I create this month, and which got scanned?" — use the audit endpoints. **Metadata only; no ciphertext, no key material.**
+
+```ts
+const { intents, total } = await client.listIntents({
+  since: "2026-06-01T00:00:00Z",
+  status: "active",
+  limit: 100,
+});
+//   total: 142
+//   intents[0]: {
+//     retrievalId: "vp_abc123def456",
+//     documentType: "check",
+//     status: "active",
+//     createdAt: "2026-06-04T15:52:25Z",
+//     verificationCount: 3,
+//     lastVerifiedAt: "2026-06-04T16:01:00Z",
+//     ...
+//   }
+
+const meta = await client.getIntent("vp_abc123def456");
+//   status, verificationCount, revokedAt, etc.
+//   Use verifyIntent(retrievalId, key) if you want to decrypt.
+```
+
+Filters: `since` / `until` (ISO datetime), `status` (`active` | `revoked`), `documentType`, `limit` (≤200), `offset`, `order` (`asc` | `desc`).
+
+### Revocation (Patent H)
+
+```ts
+await client.revokeIntent(retrievalId, "stop payment requested");
+await client.reinstateIntent(retrievalId, "false alarm");
+const history = await client.getRevocationHistory(retrievalId);
+```
+
+### Health
+
+```ts
+const { status, version } = await client.health();
+```
+
+### Low-level crypto helpers
+
+```ts
+import {
+  generateKey,
+  encrypt,
+  decrypt,
+  commitmentHash,
+  splitKey,
+  combineKeyShares,
+  encryptFields,
+  buildKeyMap,
+  decryptFields,
+} from "@keyhalve/node-sdk";
+
+const key = generateKey();                       // base64 32-byte key
+const blob = encrypt("hello world", key);        // base64(iv[12] || authTag[16] || ciphertext)
+const plain = decrypt(blob, key);                // "hello world"
+const hash = commitmentHash(plain);              // SHA-256 hex
+
+const [a, b] = splitKey(key);
+const reconstructed = combineKeyShares(a, b);    // === key
+```
+
+### `KeyHalveError`
+
+All SDK errors throw `KeyHalveError` with a stable `code`:
+
+| Code                            | Meaning                                                       |
+| ------------------------------- | ------------------------------------------------------------- |
+| `invalid_config`                | Missing `apiKey` (or other constructor options).              |
+| `invalid_argument`              | Required method argument is missing or invalid.               |
+| `invalid_key`                   | Key is not valid base64 or not 32 bytes.                      |
+| `invalid_blob`                  | Blob is not valid base64 or too short.                        |
+| `decryption_failed`             | Wrong key, or ciphertext tampered (GCM auth-tag failure).     |
+| `integrity_failure`             | Commitment hash didn't match — server tampering detected.     |
+| `intent_revoked`                | The intent has been revoked.                                  |
+| `split_key_required`            | Intent uses split-key; use `verifySplitKeyIntent` instead.    |
+| `selective_disclosure_required` | Intent uses per-field encryption; use `verifySelectiveIntent`. |
+| `invalid_role`                  | Role not present in the disclosure policy.                    |
+| `missing_fragment`              | API did not return a key fragment for a split-key intent.     |
+| `network_error`                 | `fetch` itself rejected (DNS, TCP, abort, etc.).              |
+| `http_error`                    | API returned non-2xx with no machine-readable error.          |
+| `not_found`                     | API returned 404 (e.g. unknown retrieval ID).                 |
+| `unauthorized`                  | API returned 401 (invalid or missing API key).                |
+| `invalid_response`              | API returned 2xx but response shape was unexpected.           |
+| `invalid_payload`               | Decrypted bytes were not valid JSON.                          |
+
+### API error codes (wire format)
+
+When the API itself rejects a request, the response body carries a canonical `code` field alongside the legacy `error` string. SDKs (this one included) surface both — use `code` for exhaustive `switch` checks because the values are stable across versions.
+
+| `code`                   | HTTP | Meaning                                                                   |
+| ------------------------ | ---- | ------------------------------------------------------------------------- |
+| `INVALID_BODY`           | 400  | Request body failed schema validation. `details` carries the field-level errors. |
+| `INVALID_CREDENTIALS`    | 401  | Wrong email or password on /v1/auth/login.                                |
+| `INVALID_API_KEY`        | 401  | API key is missing, malformed, or revoked.                                |
+| `MISSING_TOKEN`          | 401  | Endpoint requires a bearer token and didn't get one.                       |
+| `INVALID_TOKEN`          | 401  | Bearer token is expired or doesn't decode.                                |
+| `ACCOUNT_LOCKED`         | 423  | Too many failed sign-ins. `message` carries the retry window.             |
+| `INSUFFICIENT_SCOPE`     | 403  | API key doesn't have the scope this endpoint requires.                    |
+| `INTENT_NOT_FOUND`       | 404  | No intent matches this retrieval ID.                                      |
+| `INTENT_REVOKED`         | 200  | Body is intentionally empty — issuer revoked the intent.                  |
+| `DOCUMENT_LIMIT_REACHED` | 402  | Free or sandbox quota exhausted. `message` describes the upgrade path.    |
+| `PAYLOAD_TOO_LARGE`      | 413  | Encrypted payload exceeds the per-route limit (25 MB for uploads).        |
+| `RATE_LIMIT_EXCEEDED`    | 429  | Per-API-key bucket exhausted. Honour the `Retry-After` header.            |
+| `VALIDATION_ERROR`       | 422  | Domain-level rule rejected the request (e.g. `valid_from > valid_until`). |
+| `NOT_FOUND`              | 404  | Generic — the route exists but the resource doesn't.                      |
+| `INTERNAL_ERROR`         | 500  | Unhandled server error. Retry with backoff; report if it persists.        |
+
+Error `code`s follow the platform API's contract; consult your platform's API docs for the full list.
+
+### Rate limits
+
+All authenticated responses carry three standard headers — read them to pace yourself before you hit a 429:
+
+| Header                  | Meaning                                                                |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `X-RateLimit-Limit`     | Cap per API key per minute. Currently 600.                             |
+| `X-RateLimit-Remaining` | Requests left in the current window.                                   |
+| `X-RateLimit-Reset`     | UNIX timestamp (seconds) when the window resets.                       |
+
+On 429 you'll also see `Retry-After` (seconds) — the SDK doesn't auto-retry; honour it from your caller.
+
+## Blob format
+
+`encrypt()` returns a base64 string whose decoded bytes are:
+
+```
+[ iv (12 bytes) | authTag (16 bytes) | ciphertext (variable) ]
+```
+
+This matches the Python SDK exactly, so blobs are interoperable in both directions.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,80 @@
+import { type KeyHalveClientOptions, type CreateIntentParams, type EndCellIntentParams, type CreateFileIntentParams, type BatchIntentItem, type SelectiveIntentParams, type CreateIntentResult, type VerifyIntentResult, type RevocationResult, type RevocationEvent, type ListIntentsParams, type ListIntentsResult, type IntentMetadata } from "./types.js";
+export declare class KeyHalveClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchImpl;
+    private readonly railBaseUrl;
+    private readonly railPublicKeySpki;
+    constructor(options: KeyHalveClientOptions);
+    /**
+     * Encrypt `payload` locally and register it with the issuing platform API.
+     *
+     * Since 0.4.0 this uses **split-key protection (Patent C) by default**:
+     * the AES-256 key is split into two XOR shares — Share A is returned as
+     * `key` (embed it in the QR code exactly as before), Share B is stored
+     * on the platform server. The full decryption key never exists on any
+     * single system after this call returns. Pass `splitKey: false` for the
+     * legacy single-key flow.
+     */
+    createIntent(params: CreateIntentParams): Promise<CreateIntentResult>;
+    /**
+     * Seal a document with End-Cell (CVCP Layer 6B): an n-of-n XOR split across
+     * ShareA (returned as `key`, embed in the QR) + one mandatory piece per holder
+     * (default: the Keyhalve rail + the platform). The full key never exists on any
+     * single party, and no single holder can read or assemble it alone. The returned
+     * `key` is ShareA; `verifyIntent` reconstructs by XOR-ing it with the server pieces.
+     *
+     * Requires the API deployment to have End-Cell issuance enabled.
+     */
+    createEndCellIntent(params: EndCellIntentParams): Promise<CreateIntentResult>;
+    /**
+     * Seal a full document file (PDF, image, DOCX, …) end-to-end (Prompt 099).
+     *
+     * Unlike {@link createIntent}, which JSON-encodes a structured payload, this
+     * AES-256-GCM-encrypts the raw `file` bytes directly and registers them with
+     * file metadata — so a verifier decrypts back the exact original bytes for a
+     * byte-for-byte match and downloads them with the correct content type.
+     * Split-key protection (Patent C) is on by default.
+     */
+    createFileIntent(params: CreateFileIntentParams): Promise<CreateIntentResult>;
+    createIntentBatch(items: BatchIntentItem[]): Promise<CreateIntentResult[]>;
+    verifyIntent<T = unknown>(retrievalId: string, key: string): Promise<VerifyIntentResult<T>>;
+    /**
+     * @deprecated Since 0.4.0 `createIntent()` uses split-key protection by
+     * default, so this alias adds nothing. Call `createIntent()` instead.
+     * Kept so 0.3.x code keeps working; will be removed in 1.0.
+     */
+    createSplitKeyIntent(params: CreateIntentParams): Promise<CreateIntentResult>;
+    /** Fetch Share B from the public fragment endpoint (Patent C). */
+    private fetchFragmentB;
+    /** Fetch the End-Cell server pieces from the public fragment endpoint (Layer 6B).
+     *  Returns the pieces in the server-advertised holder order for XOR-combining. */
+    private fetchPieces;
+    verifySplitKeyIntent<T = unknown>(retrievalId: string, shareA: string): Promise<VerifyIntentResult<T>>;
+    createSelectiveIntent(params: SelectiveIntentParams): Promise<CreateIntentResult>;
+    verifySelectiveIntent(retrievalId: string, key: string, role?: string): Promise<VerifyIntentResult<Record<string, unknown>>>;
+    revokeIntent(retrievalId: string, reason?: string): Promise<RevocationResult>;
+    reinstateIntent(retrievalId: string, reason?: string): Promise<RevocationResult>;
+    getRevocationHistory(retrievalId: string): Promise<RevocationEvent[]>;
+    /**
+     * List the intents this API key has created. Returns metadata only —
+     * the AES payload + key are NEVER part of the response, by design.
+     * Use this for audit, reconciliation, and "did this intent get
+     * scanned?" dashboards.
+     */
+    listIntents(params?: ListIntentsParams): Promise<ListIntentsResult>;
+    /**
+     * Fetch metadata for a single intent. Distinct from `verifyIntent` —
+     * this endpoint never returns ciphertext or key material, so it's
+     * safe to call from any service that just needs status / verification
+     * counts / revocation state.
+     */
+    getIntent(retrievalId: string): Promise<IntentMetadata>;
+    health(): Promise<{
+        status: string;
+        version?: string;
+    }>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAMpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AAyBpB,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,OAAO,EAAE,qBAAqB;IAoB1C;;;;;;;;;OASG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgD3E;;;;;;;;OAQG;IACG,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmDnF;;;;;;;;OAQG;IACG,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0D7E,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA0E1E,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5B,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IA+EjC;;;;OAIG;IACG,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKnF,kEAAkE;YACpD,cAAc;IAmB5B;sFACkF;YACpE,WAAW;IAwBnB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EACpC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAkD3B,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4EjF,qBAAqB,CACzB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,SAAS,GACZ,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAkGjD,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoB7E,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBhF,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E;;;;;OAKG;IACG,WAAW,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqB7E;;;;;OAKG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAcvD,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;YAQ/C,OAAO;CAgDtB"}