@keyhalve/node-sdk 0.1.0

package/dist/pdf.js

@@ -0,0 +1,172 @@
+/**
+ * QR placement helpers (file mode add-on).
+ *
+ * `createFileIntent` / `createIntent` seal a document and return
+ * `{ retrievalId, key }`. To actually verify it, a scannable QR encoding the
+ * verify URL must appear ON the document. WHERE that QR goes is the
+ * integrator's call — but historically they were on their own to render it
+ * and to guess coordinates, which is fiddly and error-prone (PDFs use a
+ * bottom-left origin; every screen uses top-left).
+ *
+ * This module fixes that with one canonical placement contract used by the
+ * SDK, the website "Try it" tool, and the docs, so a position you pick once
+ * (e.g. in the tool) maps to the exact same spot here.
+ *
+ * `pdf-lib` and `qrcode` are OPTIONAL peer dependencies — the core
+ * `KeyHalveClient` stays zero-dependency. They're loaded lazily, so you only
+ * need them installed if you call {@link embedQr}:
+ *
+ *     npm i pdf-lib qrcode
+ *
+ * The coordinate math ({@link resolveQrRect}) and {@link buildVerifyUrl} are
+ * pure and dependency-free — use them directly if you render PDFs with a
+ * different library.
+ */
+import { KeyHalveError } from "./types.js";
+const UNIT_TO_PT = { pt: 1, mm: 72 / 25.4, in: 72 };
+/**
+ * Smallest QR side we consider reliably scannable from a printed page at
+ * arm's length (~72pt ≈ 1in ≈ 2.54cm). Below this, {@link embedQr} emits a
+ * one-time console warning. Advisory only — not enforced.
+ */
+export const MIN_RECOMMENDED_QR_PT = 72;
+/** base64 → base64url. Phone QR scanners and share-sheets mangle `+`, `/`,
+ *  and `=` inside URL fragments, so keys must be base64url in a QR. Idempotent
+ *  on already-base64url input; the `/verify` page accepts both. */
+function toBase64Url(b64) {
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Build the canonical verify URL the QR encodes:
+ *
+ *     <baseUrl>/verify/<retrievalId>#key=<base64url(key)>
+ *
+ * The key is placed in the URL FRAGMENT (`#key=`), which browsers never send
+ * to any server — so the decryption share rides along with the scan without
+ * ever touching the platform's logs. The key is converted to base64url so phone
+ * scanners don't mangle it.
+ */
+export function buildVerifyUrl(retrievalId, key, opts = {}) {
+    if (!retrievalId) {
+        throw new KeyHalveError("invalid_argument", "retrievalId is required");
+    }
+    if (!key) {
+        throw new KeyHalveError("invalid_argument", "key is required");
+    }
+    const base = (opts.baseUrl ?? "https://verify.keyhalve.com").replace(/\/+$/, "");
+    return `${base}/verify/${encodeURIComponent(retrievalId)}#key=${toBase64Url(key)}`;
+}
+/**
+ * Convert a canonical {@link QrPlacement} (top-left-friendly, anchor-relative
+ * insets, arbitrary units) into pdf-lib's bottom-left-origin point rectangle
+ * for a page of the given size.
+ *
+ * This is the EXACT conversion the website "Try it" tool uses, so coordinates
+ * you copy from the tool land in the same place here. Pure and
+ * dependency-free.
+ */
+export function resolveQrRect(placement, pageWidthPt, pageHeightPt) {
+    const unit = UNIT_TO_PT[placement.units ?? "pt"];
+    const size = placement.width * unit;
+    const insetX = placement.x * unit;
+    const insetY = placement.y * unit;
+    const anchor = placement.anchor ?? "top-left";
+    const leftAnchored = anchor === "top-left" || anchor === "bottom-left";
+    const topAnchored = anchor === "top-left" || anchor === "top-right";
+    // Horizontal: inset measured from the left or right edge to the QR's left.
+    const x = leftAnchored ? insetX : pageWidthPt - insetX - size;
+    // Vertical: pdf-lib y is the QR's BOTTOM edge from the page bottom. A top
+    // inset measures from the page top down to the QR's top edge.
+    const y = topAnchored ? pageHeightPt - insetY - size : insetY;
+    return { x, y, size };
+}
+let smallQrWarned = false;
+/**
+ * Stamp a scannable verify QR onto an existing PDF and return the new PDF
+ * bytes. The input is not mutated.
+ *
+ * Requires the optional peer deps `pdf-lib` and `qrcode` (`npm i pdf-lib
+ * qrcode`); it throws a `missing_dependency` KeyHalveError if either is
+ * absent. Works in Node and the browser (both libs are isomorphic).
+ *
+ * @example
+ * const { retrievalId, key } = await client.createFileIntent({ documentType: "invoice", file });
+ * const sealed = await embedQr(originalPdfBytes, {
+ *   retrievalId, key,
+ *   placement: { anchor: "bottom-right", x: 36, y: 36, width: 90 },
+ * });
+ */
+export async function embedQr(pdf, opts) {
+    if (!(pdf instanceof Uint8Array) || pdf.length === 0) {
+        throw new KeyHalveError("invalid_argument", "pdf must be non-empty Uint8Array/Buffer bytes");
+    }
+    if (!opts?.placement) {
+        throw new KeyHalveError("invalid_argument", "placement is required");
+    }
+    if (!(opts.placement.width > 0)) {
+        throw new KeyHalveError("invalid_argument", "placement.width must be > 0");
+    }
+    const { PDFDocument } = await loadPdfLib();
+    const qrcode = await loadQrcode();
+    const url = buildVerifyUrl(opts.retrievalId, opts.key, { baseUrl: opts.baseUrl });
+    const q = opts.qr ?? {};
+    const dataUrl = await qrcode.toDataURL(url, {
+        errorCorrectionLevel: q.errorCorrectionLevel ?? "M",
+        margin: q.margin ?? 2,
+        width: q.renderPx ?? 1024,
+        color: { dark: q.darkColor ?? "#0A0F1E", light: q.lightColor ?? "#FFFFFF" },
+    });
+    const pngBytes = dataUrlToBytes(dataUrl);
+    const doc = await PDFDocument.load(pdf);
+    const pages = doc.getPages();
+    const pageIndex = (opts.placement.page ?? 1) - 1;
+    if (pageIndex < 0 || pageIndex >= pages.length) {
+        throw new KeyHalveError("invalid_argument", `placement.page ${opts.placement.page ?? 1} is out of range (document has ${pages.length} page(s))`);
+    }
+    const page = pages[pageIndex];
+    const { width, height } = page.getSize();
+    const rect = resolveQrRect(opts.placement, width, height);
+    if (rect.size < MIN_RECOMMENDED_QR_PT && !smallQrWarned) {
+        smallQrWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(`[validpay] QR is ${rect.size.toFixed(0)}pt wide — below the ~${MIN_RECOMMENDED_QR_PT}pt ` +
+            "(1in) recommended minimum; it may be hard to scan once printed.");
+    }
+    if (rect.x < 0 || rect.y < 0 || rect.x + rect.size > width || rect.y + rect.size > height) {
+        throw new KeyHalveError("invalid_argument", "placement puts the QR (partly) off the page — check x/y/width against the page size");
+    }
+    const png = await doc.embedPng(pngBytes);
+    page.drawImage(png, { x: rect.x, y: rect.y, width: rect.size, height: rect.size });
+    return doc.save();
+}
+// ── internals ───────────────────────────────────────────────────────────────
+/** Decode a `data:image/png;base64,...` URL to raw bytes (Node or browser). */
+function dataUrlToBytes(dataUrl) {
+    const b64 = dataUrl.replace(/^data:[^,]*,/, "");
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(b64, "base64"));
+    }
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+async function loadPdfLib() {
+    try {
+        return (await import("pdf-lib"));
+    }
+    catch {
+        throw new KeyHalveError("missing_dependency", "embedQr requires the optional peer dependency 'pdf-lib'. Install it: npm i pdf-lib");
+    }
+}
+async function loadQrcode() {
+    try {
+        const mod = (await import("qrcode"));
+        return (mod.default ?? mod);
+    }
+    catch {
+        throw new KeyHalveError("missing_dependency", "embedQr requires the optional peer dependency 'qrcode'. Install it: npm i qrcode");
+    }
+}
+//# sourceMappingURL=pdf.js.map

package/dist/pdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.js","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"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"}

package/dist/rail.d.ts

@@ -0,0 +1,18 @@
+/**
+ * KeyHalve rail client (verify side). Fetches the blind rail share `B_keyhalve` from
+ * the independent rail and verifies the rail's Ed25519 signature against a PINNED
+ * public key. Fails closed on any doubt. The caller XOR-combines the verified rail
+ * share with the platform share(s) (from the platform API) and ShareA (the QR key).
+ *
+ * The pinned key is shipped with the SDK, not fetched at runtime — a hijacked rail or
+ * DNS path then produces a signature that fails the pinned check.
+ */
+/** Default rail base + pinned KMS Ed25519 public key (SPKI DER, base64). */
+export declare const KEYHALVE_RAIL_BASE_URL = "https://rail.keyhalve.com";
+export declare const KEYHALVE_RAIL_PUBLIC_KEY_SPKI_B64 = "MCowBQYDK2VwAyEAngOcqC4hL467C9RyWUh4bAQD3Fohi9zqhY+l65bul6w=";
+/**
+ * Fetch and verify `B_keyhalve` for an intent. Throws (fails closed) on unreachable,
+ * missing, revoked, malformed, or bad-signature.
+ */
+export declare function fetchRailPiece(fetchImpl: typeof fetch, railBaseUrl: string, pinnedSpkiB64: string, intentId: string): Promise<string>;
+//# sourceMappingURL=rail.d.ts.map

package/dist/rail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail.d.ts","sourceRoot":"","sources":["../src/rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAClE,eAAO,MAAM,iCAAiC,iEACkB,CAAC;AAgBjE;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,OAAO,KAAK,EACvB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/rail.js

@@ -0,0 +1,58 @@
+/**
+ * KeyHalve rail client (verify side). Fetches the blind rail share `B_keyhalve` from
+ * the independent rail and verifies the rail's Ed25519 signature against a PINNED
+ * public key. Fails closed on any doubt. The caller XOR-combines the verified rail
+ * share with the platform share(s) (from the platform API) and ShareA (the QR key).
+ *
+ * The pinned key is shipped with the SDK, not fetched at runtime — a hijacked rail or
+ * DNS path then produces a signature that fails the pinned check.
+ */
+import { createPublicKey, verify } from "node:crypto";
+import { KeyHalveError } from "./types.js";
+/** Default rail base + pinned KMS Ed25519 public key (SPKI DER, base64). */
+export const KEYHALVE_RAIL_BASE_URL = "https://rail.keyhalve.com";
+export const KEYHALVE_RAIL_PUBLIC_KEY_SPKI_B64 = "MCowBQYDK2VwAyEAngOcqC4hL467C9RyWUh4bAQD3Fohi9zqhY+l65bul6w=";
+const HOLDER = "keyhalve";
+function canonicalMessage(intentId, piece) {
+    return `keyhalve-rail.v1\n${intentId}\n${HOLDER}\n${piece}`;
+}
+/**
+ * Fetch and verify `B_keyhalve` for an intent. Throws (fails closed) on unreachable,
+ * missing, revoked, malformed, or bad-signature.
+ */
+export async function fetchRailPiece(fetchImpl, railBaseUrl, pinnedSpkiB64, intentId) {
+    const base = railBaseUrl.replace(/\/+$/, "");
+    let res;
+    try {
+        res = await fetchImpl(`${base}/v1/piece/${encodeURIComponent(intentId)}`, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+        });
+    }
+    catch (cause) {
+        throw new KeyHalveError("rail_unreachable", "Could not reach the KeyHalve rail", { cause });
+    }
+    if (res.status === 404)
+        throw new KeyHalveError("rail_not_found", "Rail share not found");
+    if (res.status === 409)
+        throw new KeyHalveError("rail_revoked", "Rail share revoked");
+    if (!res.ok)
+        throw new KeyHalveError("rail_error", `Rail returned ${res.status}`);
+    const json = (await res.json());
+    if (json.error)
+        throw new KeyHalveError("rail_error", `Rail error: ${json.error}`);
+    if (!json.piece || !json.sig || json.holder !== HOLDER) {
+        throw new KeyHalveError("rail_malformed", "Malformed rail response");
+    }
+    const pub = createPublicKey({
+        key: Buffer.from(pinnedSpkiB64, "base64"),
+        format: "der",
+        type: "spki",
+    });
+    const ok = verify(null, Buffer.from(canonicalMessage(intentId, json.piece), "utf8"), pub, Buffer.from(json.sig, "base64"));
+    if (!ok) {
+        throw new KeyHalveError("rail_bad_signature", "Rail response failed signature verification");
+    }
+    return json.piece;
+}
+//# sourceMappingURL=rail.js.map

package/dist/rail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail.js","sourceRoot":"","sources":["../src/rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,2BAA2B,CAAC;AAClE,MAAM,CAAC,MAAM,iCAAiC,GAC5C,8DAA8D,CAAC;AAEjE,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,SAAS,gBAAgB,CAAC,QAAgB,EAAE,KAAa;IACvD,OAAO,qBAAqB,QAAQ,KAAK,MAAM,KAAK,KAAK,EAAE,CAAC;AAC9D,CAAC;AAUD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAuB,EACvB,WAAmB,EACnB,aAAqB,EACrB,QAAgB;IAEhB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,IAAI,aAAa,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE;YACxE,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,aAAa,CAAC,kBAAkB,EAAE,mCAAmC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,aAAa,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,CAAC;IAC1F,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,aAAa,CAAC,cAAc,EAAE,oBAAoB,CAAC,CAAC;IACtF,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,iBAAiB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAElF,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAsB,CAAC;IACrD,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,eAAe,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACnF,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACvD,MAAM,IAAI,aAAa,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,GAAG,GAAG,eAAe,CAAC;QAC1B,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC;QACzC,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,MAAM,CACf,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,EAC3D,GAAG,EACH,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAChC,CAAC;IACF,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,aAAa,CAAC,oBAAoB,EAAE,6CAA6C,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC;AACpB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+export interface KeyHalveClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+    /** KeyHalve rail base URL (End-Cell verify). Defaults to https://rail.keyhalve.com. */
+    railBaseUrl?: string;
+    /** Pinned rail Ed25519 public key (SPKI DER, base64). Defaults to the live rail key. */
+    railPublicKeySpki?: string;
+}
+/**
+ * Platform delegation (Fork B). When you integrate as a platform and seal on
+ * behalf of the businesses you serve, declare which business each seal is for.
+ * The verifier sees that business as the issuer ("who"), attributed through your
+ * platform ("through whom"), at the `delegated` trust rung.
+ *
+ * the platform stays blind to the document contents — this is identity only.
+ */
+export interface OnBehalfOf {
+    /** Your OWN id for this business. The dedupe key: same `ref` ⇒ same tracked
+     *  sub-issuer (its documents and verification counts roll up). */
+    ref: string;
+    /** The business name shown to verifiers on a scan. */
+    name: string;
+}
+export interface CreateIntentParams {
+    documentType: string;
+    payload: unknown;
+    validFrom?: string;
+    validUntil?: string;
+    /**
+     * Split-key protection (Patent C). Default `true` since 0.4.0: the
+     * returned `key` is Share A of the AES key and Share B is stored on
+     * the platform server — neither alone decrypts. Set `false` for the
+     * legacy single-key flow where `key` is the full AES key.
+     */
+    splitKey?: boolean;
+    /** Seal on behalf of one of your businesses (platform delegation). */
+    onBehalfOf?: OnBehalfOf;
+}
+/**
+ * Params for {@link KeyHalveClient.createEndCellIntent} (End-Cell, CVCP Layer 6B).
+ * Generalises split-key to an n-of-n XOR across ShareA (returned as `key`, embed in
+ * the QR) + one mandatory piece per server-side holder. The full key never exists on
+ * any single party.
+ */
+export interface EndCellIntentParams {
+    documentType: string;
+    payload: unknown;
+    validFrom?: string;
+    validUntil?: string;
+    /**
+     * Server-side holders, one mandatory XOR piece each. Defaults to
+     * `["keyhalve", "platform"]` (the blind rail + the platform) → a 3-of-3 split with
+     * the receiver's ShareA. Provide more to elect additional independent holders.
+     */
+    holders?: string[];
+    /** Seal on behalf of one of your businesses (platform delegation). */
+    onBehalfOf?: OnBehalfOf;
+}
+/** Params for {@link KeyHalveClient.createFileIntent} (file mode, Prompt 099). */
+export interface CreateFileIntentParams {
+    documentType: string;
+    /** Raw file bytes to seal (PDF/image/DOCX/…). Encrypted locally. */
+    file: Uint8Array;
+    /** Original filename, stored for issuer records. NOT echoed on public verify. */
+    fileName?: string;
+    /** MIME type, e.g. "application/pdf". Returned on verify for correct download. */
+    fileContentType?: string;
+    validFrom?: string;
+    validUntil?: string;
+    /** Split-key protection (Patent C). Default `true`. */
+    splitKey?: boolean;
+    /** Seal on behalf of one of your businesses (platform delegation). */
+    onBehalfOf?: OnBehalfOf;
+}
+export interface BatchIntentItem {
+    documentType: string;
+    payload: unknown;
+    validFrom?: string;
+    validUntil?: string;
+    /** Seal on behalf of one of your businesses (platform delegation). */
+    onBehalfOf?: OnBehalfOf;
+}
+export interface SelectiveIntentParams {
+    documentType: string;
+    payload: Record<string, unknown>;
+    disclosurePolicy: Record<string, string[]>;
+    splitKey?: boolean;
+    validFrom?: string;
+    validUntil?: string;
+    /** Seal on behalf of one of your businesses (platform delegation). */
+    onBehalfOf?: OnBehalfOf;
+}
+export interface CreateIntentResult {
+    retrievalId: string;
+    key: string;
+}
+export type TimeLockStatus = "valid" | "not_yet_valid" | "expired";
+export interface VerifyIntentResult<T = unknown> {
+    intentId: string;
+    payload: T;
+    issuer: string;
+    issuerVerified: boolean;
+    registeredAt: string;
+    status: string;
+    integrityVerified: boolean;
+    validFrom?: string | null;
+    validUntil?: string | null;
+    timeLockStatus?: TimeLockStatus | null;
+    /** Graded trust rung of the issuer: none < delegated < domain < business. */
+    verificationLevel?: "none" | "delegated" | "domain" | "business";
+    /** Set when `issuer` was sealed on behalf of, via a platform (delegation).
+     *  Names the vouching platform and its own proven level. */
+    delegatedBy?: {
+        platform: string;
+        platformLevel: "domain" | "business";
+    } | null;
+}
+export interface RevocationResult {
+    intentId: string;
+    status: string;
+    revokedAt?: string;
+    reinstatedAt?: string;
+}
+export interface RevocationEvent {
+    id: string;
+    action: "revoked" | "reinstated";
+    reason?: string;
+    performedAt: string;
+}
+export interface RawIntentResponse {
+    intent_id: string;
+    encrypted_payload: string | null;
+    issuer: string;
+    issuer_verified: boolean;
+    registered_at: string;
+    status: string;
+    document_type?: string;
+    commitment_hash?: string;
+    /** 1 = legacy SHA-256(plaintext), skipped on verify; 2 = SHA-256(ciphertext),
+     *  enforced. Absent is treated as 1 (Prompt 097 C-1). */
+    commitment_version?: number;
+    /** 1 = no AAD (legacy); 2 = {document_type, valid_from, valid_until} bound
+     *  as AES-GCM AAD. Absent is treated as 1 (Prompt 097 M-5). */
+    encryption_version?: number;
+    valid_from?: string | null;
+    valid_until?: string | null;
+    selective_disclosure?: boolean;
+    encrypted_key_map?: string;
+    split_key?: boolean;
+    /** End-Cell (CVCP Layer 6B): key split n-of-n XOR across ShareA + server pieces. */
+    end_cell?: boolean;
+    revocation_reason?: string;
+    revoked_at?: string;
+    verification_level?: "none" | "delegated" | "domain" | "business";
+    delegated_by?: {
+        platform: string;
+        platform_level: "domain" | "business";
+    } | null;
+}
+export interface RawCreateIntentResponse {
+    retrieval_id: string;
+    status: string;
+}
+export interface RawBatchCreateResponse {
+    results: Array<{
+        retrieval_id: string;
+        status?: string;
+    }>;
+}
+export interface ListIntentsParams {
+    /** Max results, default 50, max 200. */
+    limit?: number;
+    offset?: number;
+    /** ISO datetime — only intents created at or after this time. */
+    since?: string;
+    /** ISO datetime — only intents created at or before this time. */
+    until?: string;
+    status?: "active" | "revoked";
+    documentType?: string;
+    /** Ordering by createdAt. Default "desc". */
+    order?: "asc" | "desc";
+}
+export interface IntentMetadata {
+    retrievalId: string;
+    documentType: string;
+    status: string;
+    createdAt: string;
+    revokedAt: string | null;
+    revocationReason: string | null;
+    validFrom: string | null;
+    validUntil: string | null;
+    commitmentHash: string | null;
+    splitKey: boolean;
+    selectiveDisclosure: boolean;
+    verificationCount: number;
+    lastVerifiedAt: string | null;
+}
+export interface ListIntentsResult {
+    intents: IntentMetadata[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface RawIntentMetadata {
+    retrieval_id: string;
+    document_type: string;
+    status: string;
+    created_at: string;
+    revoked_at: string | null;
+    revocation_reason: string | null;
+    valid_from: string | null;
+    valid_until: string | null;
+    commitment_hash: string | null;
+    split_key: boolean;
+    selective_disclosure: boolean;
+    verification_count: number;
+    last_verified_at: string | null;
+}
+export interface RawListIntentsResponse {
+    intents: RawIntentMetadata[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface RawFragmentResponse {
+    fragment_b?: string;
+    /** End-Cell (CVCP Layer 6B): the per-holder server pieces. */
+    end_cell?: boolean;
+    holders?: string[];
+    pieces?: Record<string, string>;
+    error?: string;
+}
+export interface RawRevocationHistoryResponse {
+    events?: Array<{
+        id: string;
+        action: "revoked" | "reinstated";
+        reason?: string;
+        performed_at: string;
+    }>;
+}
+export declare class KeyHalveError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly details?: unknown;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+export class KeyHalveError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "KeyHalveError";
+        this.code = code;
+        this.status = options.status;
+        this.details = options.details;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+PA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAS;IACb,MAAM,CAAU;IAChB,OAAO,CAAW;IAE3B,YACE,IAAY,EACZ,OAAe,EACf,UAAmE,EAAE;QAErE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@keyhalve/node-sdk",
+  "version": "0.1.0",
+  "description": "KeyHalve SDK for Node.js — End-Cell blind-rail document sealing & verification: client-side AES-256-GCM, 3-share key split (QR + platform + independent KeyHalve rail), commitment hashing, QR placement. Zero required production dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "keyhalve",
+    "encryption",
+    "aes-256-gcm",
+    "document-verification",
+    "check-fraud",
+    "authentication",
+    "selective-disclosure",
+    "split-key",
+    "blind-escrow"
+  ],
+  "homepage": "https://github.com/keyhalve/node-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keyhalve/node-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/keyhalve/node-sdk/issues"
+  },
+  "license": "MIT",
+  "author": "KeyHalve (Attestura, LLC)",
+  "peerDependencies": {
+    "pdf-lib": ">=1.17.0",
+    "qrcode": ">=1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "pdf-lib": { "optional": true },
+    "qrcode": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/qrcode": "^1.5.5",
+    "pdf-lib": "^1.17.1",
+    "qrcode": "^1.5.4",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}