@paybond/kit 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# `@paybond/kit`
+
+Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, and tenant-scoped ledger provenance reads.
+
+It does **not** currently expose a first-class Signal client or Signal analytics/reputation API surface. Signal remains a separate platform surface today.
+
+Install the public package with:
+
+```bash
+npm install @paybond/kit
+```
+
+## Requirements
+
+- Node.js 20+
+- A `paybond_sk_...` service-account API key
+- Reachable Gateway and Harbor base URLs
+
+## Tenant isolation
+
+Every session is bound to the tenant realm echoed by the gateway `POST /v1/auth/harbor-access` exchange.
+
+- Do not pass tenant ids by hand for normal SDK usage.
+- Construct one `Paybond` session per tenant/service account.
+- Treat any tenant or intent echo mismatch from Harbor as a severity-zero defect.
+
+## Quick start
+
+```ts
+import { Paybond } from "@paybond/kit";
+
+const paybond = await Paybond.open({
+  gatewayBaseUrl: "https://gateway.example.com",
+  apiKey: process.env.PAYBOND_API_KEY!,
+  harborBaseUrl: "https://harbor.example.com",
+});
+
+try {
+  const verified = await paybond.harbor.verifyCapability({
+    intentId: process.env.PAYBOND_INTENT_ID!,
+    token: process.env.PAYBOND_CAPABILITY!,
+    operation: "payments.capture",
+    requestedSpendCents: 18_700,
+  });
+
+  if (!verified.allow) {
+    throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
+  }
+} finally {
+  await paybond.aclose();
+}
+```
+
+## What the package includes
+
+- `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
+- `HarborClient` for capability verification, intent creation, evidence submission, and ledger reads
+- `PaybondIntents` helpers for principal-signed intent creation and payee-signed evidence submission
+- Low-level signing helpers exported for advanced callers
+
+`allowedTools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.
+
+## What it does not include
+
+- No first-class `SignalClient`
+- No Signal reputation or analytics fetch API
+- No operator-tier settlement or console workflows
+
+## Docs
+
+- Long-form docs: `docs/kit/`
+- Agents SDK tutorial: `docs/kit/openai-agents.md`
+- TypeScript quickstart: `docs/kit/quickstart-typescript.md`
+- TypeScript SDK reference: `docs/kit/sdk-reference-typescript.md`
+- Example app: `examples/paybond-kit-typescript/`
+- OpenAI Agents example: `examples/paybond-kit-openai-agents-typescript/`
+
+## Release verification
+
+From `kit/ts`:
+
+```bash
+npm run verify:release
+```
+
+This runs tests, performs a clean build, inspects the packed tarball for stray files, and compiles a temporary consumer app against the packed package.

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
+ * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
+ */
+import { type BuildSignedCreateIntentParams } from "./principal-intent.js";
+import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
+export type VerifyCapabilityResult = {
+    allow: boolean;
+    auditId: string;
+    tenant: string;
+    intentId: string;
+    code?: string;
+    message?: string;
+};
+export type SubmitEvidenceResult = {
+    intentId: string;
+    tenant: string;
+    state: string;
+    predicatePassed?: boolean;
+};
+/** Async supplier for short-lived Harbor JWTs minted by the Paybond gateway. */
+export type HarborBearerSupplier = () => Promise<string | null | undefined>;
+/**
+ * Structured HTTP failure from Harbor with operator-facing diagnostics.
+ */
+export declare class HarborHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+    });
+}
+/**
+ * Gateway rejected the service-account exchange or returned an unusable harbor-access payload.
+ */
+export declare class GatewayAuthError extends Error {
+    readonly statusCode: number | undefined;
+    readonly bodyText: string | undefined;
+    constructor(message: string, init?: {
+        statusCode?: number;
+        bodyText?: string;
+    });
+}
+/**
+ * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
+ * gateway response (no separate tenant env var for the default path).
+ */
+export declare class GatewayHarborTokenProvider {
+    private readonly gatewayBase;
+    private readonly apiKey;
+    private readonly path;
+    private readonly skewMs;
+    private readonly clock;
+    private token;
+    private tenantIdValue;
+    private notAfterMonotonic;
+    private refreshTail;
+    constructor(init: {
+        gatewayBaseUrl: string;
+        apiKey: string;
+        harborAccessPath?: string;
+        clockSkewSeconds?: number;
+        /** Injectable monotonic clock (milliseconds) for tests. */
+        clock?: () => number;
+    });
+    get tenantId(): string | null;
+    /**
+     * First exchange; returns tenant realm echoed by the gateway.
+     */
+    ensureInitial(): Promise<string>;
+    /** Return a valid Harbor JWT, refreshing when near expiry. */
+    bearer(): Promise<string>;
+    /** Force rotation (credential rotation drills). */
+    forceRotate(): Promise<void>;
+    private refresh;
+    private refreshInner;
+}
+/**
+ * Tenant-scoped Harbor binding for one funded intent and one Biscuit capability token.
+ */
+export declare class PaybondCapabilityBinding {
+    readonly harbor: HarborClient;
+    readonly intentId: string;
+    readonly capabilityToken: string;
+    constructor(harbor: HarborClient, intentId: string, capabilityToken: string);
+}
+export type ServiceAccountHarborSessionInit = {
+    gatewayBaseUrl: string;
+    apiKey: string;
+    harborBaseUrl: string;
+    harborAccessPath?: string;
+    clockSkewSeconds?: number;
+    maxRetries?: number;
+};
+/**
+ * Harbor client plus gateway token lifecycle for one service account.
+ */
+export declare class ServiceAccountHarborSession {
+    readonly harbor: HarborClient;
+    private readonly tokens;
+    private constructor();
+    /**
+     * Build a tenant-bound {@link HarborClient} using gateway-derived tenant id and JWT supplier.
+     */
+    static open(init: ServiceAccountHarborSessionInit): Promise<ServiceAccountHarborSession>;
+    rotateHarborToken(): Promise<void>;
+    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
+    aclose(): Promise<void>;
+}
+type HarborClientOptions = {
+    harborBearerSupplier?: HarborBearerSupplier;
+    staticHarborBearerToken?: string;
+    maxRetries?: number;
+};
+/**
+ * HTTP client for Harbor: capability verify, intents, evidence, and tenant-scoped ledger reads
+ * (`GET /ledger/v1/*`, PAYBOND-007).
+ */
+export declare class HarborClient {
+    private readonly base;
+    /** Tenant realm from the gateway exchange; sent as `x-tenant-id` on every Harbor request. */
+    readonly tenantId: string;
+    private readonly bearerSupplier?;
+    private readonly staticBearer?;
+    private readonly maxRetries;
+    /**
+     * @param harborBase - Harbor origin, e.g. `https://harbor.example.com` (trailing slash optional)
+     * @param tenantId - Tenant realm; sent as `x-tenant-id` on every request
+     */
+    constructor(harborBase: string, tenantId: string, options?: HarborClientOptions);
+    private authHeader;
+    /**
+     * Ledger JSON responses include `tenant_id`; reject if it drifts from the bound client tenant.
+     */
+    private assertLedgerTenant;
+    /** GET with the same 429/5xx retry behavior as {@link HarborClient.fetchWithRetries}. */
+    private fetchGetWithRetries;
+    private fetchWithRetries;
+    /**
+     * POST `/verify` with a Biscuit capability token (PAYBOND-006).
+     *
+     * @throws HarborHttpError when HTTP fails
+     * @throws Error when Harbor echoes a different tenant / intent than requested
+     */
+    verifyCapability(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
+    /**
+     * POST `/intents` with a principal-signed `CreateIntentRequest` JSON body.
+     *
+     * @throws HarborHttpError when HTTP fails
+     */
+    createIntent(body: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * POST `/intents/{intentId}/evidence` with a signed evidence JSON body.
+     *
+     * @param idempotencyKey - Optional Harbor idempotency header for safe retries
+     */
+    submitEvidence(intentId: string, evidenceBody: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+    }): Promise<SubmitEvidenceResult>;
+    /**
+     * `GET /ledger/v1/tip` — latest sequence and entry commitment for the authenticated tenant.
+     *
+     * @throws HarborHttpError on HTTP failure
+     * @throws Error when JSON `tenant_id` does not match the bound client tenant
+     */
+    getLedgerTip(): Promise<Record<string, unknown>>;
+    /**
+     * `GET /ledger/v1/authority` — hex-encoded Ed25519 verifying key for this Harbor deployment.
+     */
+    getLedgerAuthority(): Promise<Record<string, unknown>>;
+    /**
+     * `GET /ledger/v1/events` — paginated append-only history; `afterSeq` is an exclusive cursor.
+     * `limit` is clamped to 1…256 to match Harbor.
+     */
+    getLedgerEvents(options?: {
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * `GET /ledger/v1/merkle/latest` — last Merkle checkpoint envelope for the tenant (checkpoint may be null).
+     */
+    getLedgerMerkleLatest(): Promise<Record<string, unknown>>;
+}
+/** Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client). */
+export type PaybondCreateIntentParams = Omit<BuildSignedCreateIntentParams, "tenantId" | "intentId"> & {
+    intentId?: string;
+};
+/** Parameters for {@link PaybondIntents.submitEvidence} (tenant is taken from the bound Harbor client). */
+export type PaybondSubmitEvidenceParams = Omit<SignPayeeEvidenceParams, "tenantId">;
+/**
+ * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
+ */
+export declare class PaybondIntents {
+    private readonly harbor;
+    constructor(harbor: HarborClient);
+    /**
+     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be 32 bytes.
+     */
+    create(params: PaybondCreateIntentParams & {
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
+     */
+    submitEvidence(params: PaybondSubmitEvidenceParams & {
+        idempotencyKey?: string;
+    }): Promise<SubmitEvidenceResult>;
+}
+/**
+ * High-level Kit entrypoint: same session lifecycle as {@link ServiceAccountHarborSession}, plus {@link PaybondIntents}.
+ */
+export declare class Paybond {
+    readonly harbor: HarborClient;
+    readonly intents: PaybondIntents;
+    private readonly session;
+    private constructor();
+    /** Open a tenant-bound session via gateway `harbor-access` exchange. */
+    static open(init: ServiceAccountHarborSessionInit): Promise<Paybond>;
+    rotateHarborToken(): Promise<void>;
+    /** Release HTTP resources (Harbor client + gateway token provider). */
+    aclose(): Promise<void>;
+}
+export { normalizeJson, jsonValueDigest } from "./json-digest.js";
+export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, } from "./principal-intent.js";
+export { artifactsDigest, signPayeeEvidenceBinding, type SignPayeeEvidenceParams } from "./payee-evidence.js";

package/dist/index.js

@@ -0,0 +1,570 @@
+/**
+ * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
+ * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
+ */
+import { buildSignedCreateIntentBody } from "./principal-intent.js";
+import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+/**
+ * Structured HTTP failure from Harbor with operator-facing diagnostics.
+ */
+export class HarborHttpError extends Error {
+    statusCode;
+    url;
+    bodyText;
+    constructor(message, init) {
+        super(message);
+        this.name = "HarborHttpError";
+        this.statusCode = init.statusCode;
+        this.url = init.url;
+        this.bodyText = init.bodyText;
+    }
+}
+/**
+ * Gateway rejected the service-account exchange or returned an unusable harbor-access payload.
+ */
+export class GatewayAuthError extends Error {
+    statusCode;
+    bodyText;
+    constructor(message, init) {
+        super(message);
+        this.name = "GatewayAuthError";
+        this.statusCode = init?.statusCode;
+        this.bodyText = init?.bodyText;
+    }
+}
+function normalizeBase(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+function backoffMs(attempt) {
+    const base = 200 * 2 ** attempt;
+    const jitter = Math.random() * 100;
+    return Math.min(base + jitter, 5000);
+}
+function parseRetryAfterSeconds(v) {
+    if (!v)
+        return null;
+    const n = Number.parseFloat(v.trim());
+    if (!Number.isFinite(n))
+        return null;
+    return Math.min(n, 30);
+}
+const DEFAULT_HARBOR_ACCESS_PATH = "/v1/auth/harbor-access";
+/**
+ * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
+ * gateway response (no separate tenant env var for the default path).
+ */
+export class GatewayHarborTokenProvider {
+    gatewayBase;
+    apiKey;
+    path;
+    skewMs;
+    clock;
+    token = null;
+    tenantIdValue = null;
+    notAfterMonotonic = 0;
+    refreshTail = Promise.resolve();
+    constructor(init) {
+        this.gatewayBase = normalizeBase(init.gatewayBaseUrl);
+        this.apiKey = init.apiKey.trim();
+        const rawPath = (init.harborAccessPath ?? DEFAULT_HARBOR_ACCESS_PATH).trim();
+        this.path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+        this.skewMs = Math.max(0, (init.clockSkewSeconds ?? 90) * 1000);
+        this.clock = init.clock ?? (() => performance.now());
+    }
+    get tenantId() {
+        return this.tenantIdValue;
+    }
+    /**
+     * First exchange; returns tenant realm echoed by the gateway.
+     */
+    async ensureInitial() {
+        await this.refresh(true);
+        if (!this.tenantIdValue) {
+            throw new GatewayAuthError("harbor-access response missing tenant_id; upgrade gateway (PAYBOND-V1-008)");
+        }
+        return this.tenantIdValue;
+    }
+    /** Return a valid Harbor JWT, refreshing when near expiry. */
+    async bearer() {
+        await this.refresh(false);
+        if (!this.token) {
+            throw new GatewayAuthError("harbor-access did not return access_token");
+        }
+        return this.token;
+    }
+    /** Force rotation (credential rotation drills). */
+    async forceRotate() {
+        await this.refresh(true);
+    }
+    async refresh(force) {
+        const job = this.refreshTail.then(() => this.refreshInner(force));
+        this.refreshTail = job.then(() => undefined, () => undefined);
+        await job;
+    }
+    async refreshInner(force) {
+        const now = this.clock();
+        if (!force && this.token && now < this.notAfterMonotonic) {
+            return;
+        }
+        const url = `${this.gatewayBase}${this.path}`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                accept: "application/json",
+            },
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new GatewayAuthError(`harbor-access HTTP ${res.status}`, {
+                statusCode: res.status,
+                bodyText: text,
+            });
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new GatewayAuthError("harbor-access response was not JSON", { bodyText: text });
+        }
+        const access = String(body.access_token ?? "").trim();
+        if (!access) {
+            throw new GatewayAuthError("harbor-access JSON missing access_token", { bodyText: text });
+        }
+        const expIn = Number(body.expires_in ?? 0);
+        if (!Number.isFinite(expIn) || expIn <= 0) {
+            throw new GatewayAuthError("harbor-access JSON missing expires_in", { bodyText: text });
+        }
+        const tidRaw = body.tenant_id;
+        if (typeof tidRaw === "string" && tidRaw.trim()) {
+            this.tenantIdValue = tidRaw.trim();
+        }
+        if (!this.tenantIdValue) {
+            throw new GatewayAuthError("harbor-access response missing tenant_id; upgrade gateway (PAYBOND-V1-008)", { bodyText: text });
+        }
+        this.token = access;
+        this.notAfterMonotonic = now + Math.max(1000, expIn * 1000 - this.skewMs);
+    }
+}
+/**
+ * Tenant-scoped Harbor binding for one funded intent and one Biscuit capability token.
+ */
+export class PaybondCapabilityBinding {
+    harbor;
+    intentId;
+    capabilityToken;
+    constructor(harbor, intentId, capabilityToken) {
+        this.harbor = harbor;
+        this.intentId = intentId;
+        this.capabilityToken = capabilityToken;
+    }
+}
+/**
+ * Harbor client plus gateway token lifecycle for one service account.
+ */
+export class ServiceAccountHarborSession {
+    harbor;
+    tokens;
+    constructor(harbor, tokens) {
+        this.harbor = harbor;
+        this.tokens = tokens;
+    }
+    /**
+     * Build a tenant-bound {@link HarborClient} using gateway-derived tenant id and JWT supplier.
+     */
+    static async open(init) {
+        const tokens = new GatewayHarborTokenProvider({
+            gatewayBaseUrl: init.gatewayBaseUrl,
+            apiKey: init.apiKey,
+            harborAccessPath: init.harborAccessPath,
+            clockSkewSeconds: init.clockSkewSeconds,
+        });
+        const tenant = await tokens.ensureInitial();
+        const harbor = new HarborClient(init.harborBaseUrl, tenant, {
+            harborBearerSupplier: () => tokens.bearer(),
+            maxRetries: init.maxRetries ?? 3,
+        });
+        return new ServiceAccountHarborSession(harbor, tokens);
+    }
+    async rotateHarborToken() {
+        await this.tokens.forceRotate();
+    }
+    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
+    async aclose() {
+        await Promise.resolve();
+    }
+}
+/**
+ * HTTP client for Harbor: capability verify, intents, evidence, and tenant-scoped ledger reads
+ * (`GET /ledger/v1/*`, PAYBOND-007).
+ */
+export class HarborClient {
+    base;
+    /** Tenant realm from the gateway exchange; sent as `x-tenant-id` on every Harbor request. */
+    tenantId;
+    bearerSupplier;
+    staticBearer;
+    maxRetries;
+    /**
+     * @param harborBase - Harbor origin, e.g. `https://harbor.example.com` (trailing slash optional)
+     * @param tenantId - Tenant realm; sent as `x-tenant-id` on every request
+     */
+    constructor(harborBase, tenantId, options) {
+        if (options?.harborBearerSupplier && options?.staticHarborBearerToken) {
+            throw new Error("pass at most one of harborBearerSupplier or staticHarborBearerToken");
+        }
+        this.base = normalizeBase(harborBase) + "/";
+        this.tenantId = tenantId.trim();
+        this.bearerSupplier = options?.harborBearerSupplier;
+        this.staticBearer = options?.staticHarborBearerToken?.trim();
+        this.maxRetries = Math.max(1, options?.maxRetries ?? 3);
+    }
+    async authHeader() {
+        if (this.staticBearer) {
+            return { authorization: `Bearer ${this.staticBearer}` };
+        }
+        if (this.bearerSupplier) {
+            const tok = await this.bearerSupplier();
+            if (tok && String(tok).trim()) {
+                return { authorization: `Bearer ${String(tok).trim()}` };
+            }
+        }
+        return {};
+    }
+    /**
+     * Ledger JSON responses include `tenant_id`; reject if it drifts from the bound client tenant.
+     */
+    assertLedgerTenant(body, url) {
+        const tid = String(body.tenant_id ?? "");
+        if (tid !== this.tenantId) {
+            throw new Error(`ledger tenant mismatch: client=${this.tenantId} harbor=${tid} url=${url}`);
+        }
+    }
+    /** GET with the same 429/5xx retry behavior as {@link HarborClient.fetchWithRetries}. */
+    async fetchGetWithRetries(url) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                const headers = new Headers({
+                    accept: "application/json",
+                    "x-tenant-id": this.tenantId,
+                });
+                const auth = await this.authHeader();
+                for (const [k, v] of Object.entries(auth)) {
+                    headers.set(k, v);
+                }
+                res = await fetch(url, { method: "GET", headers });
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status)) {
+                if (attempt + 1 >= this.maxRetries) {
+                    return res;
+                }
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async fetchWithRetries(url, init, { retryBody }) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                const headers = new Headers(init.headers);
+                const auth = await this.authHeader();
+                for (const [k, v] of Object.entries(auth)) {
+                    headers.set(k, v);
+                }
+                res = await fetch(url, { ...init, headers });
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status)) {
+                if (attempt + 1 >= this.maxRetries) {
+                    return res;
+                }
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                init = {
+                    ...init,
+                    body: JSON.stringify(retryBody),
+                };
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    /**
+     * POST `/verify` with a Biscuit capability token (PAYBOND-006).
+     *
+     * @throws HarborHttpError when HTTP fails
+     * @throws Error when Harbor echoes a different tenant / intent than requested
+     */
+    async verifyCapability(input) {
+        const url = `${this.base}verify`;
+        const payload = {
+            intent_id: input.intentId,
+            token: input.token,
+            operation: input.operation,
+            requested_spend_cents: input.requestedSpendCents ?? 0,
+        };
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-tenant-id": this.tenantId,
+            },
+            body: JSON.stringify(payload),
+        }, { retryBody: payload });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor verify HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        if (body.tenant !== this.tenantId) {
+            throw new Error(`verify tenant mismatch: client=${this.tenantId} harbor=${body.tenant}`);
+        }
+        if (body.intent_id !== input.intentId) {
+            throw new Error(`verify intent mismatch: requested=${input.intentId} harbor=${body.intent_id}`);
+        }
+        return {
+            allow: body.allow,
+            auditId: body.audit_id,
+            tenant: body.tenant,
+            intentId: body.intent_id,
+            code: body.code,
+            message: body.message,
+        };
+    }
+    /**
+     * POST `/intents` with a principal-signed `CreateIntentRequest` JSON body.
+     *
+     * @throws HarborHttpError when HTTP fails
+     */
+    async createIntent(body, options) {
+        const url = `${this.base}intents`;
+        const headers = {
+            "content-type": "application/json",
+            "x-tenant-id": this.tenantId,
+        };
+        if (options?.idempotencyKey?.trim()) {
+            headers["idempotency-key"] = options.idempotencyKey.trim();
+        }
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        }, { retryBody: body });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor create intent HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return JSON.parse(text);
+    }
+    /**
+     * POST `/intents/{intentId}/evidence` with a signed evidence JSON body.
+     *
+     * @param idempotencyKey - Optional Harbor idempotency header for safe retries
+     */
+    async submitEvidence(intentId, evidenceBody, options) {
+        const url = `${this.base}intents/${intentId}/evidence`;
+        const headers = {
+            "content-type": "application/json",
+            "x-tenant-id": this.tenantId,
+        };
+        if (options?.idempotencyKey?.trim()) {
+            headers["idempotency-key"] = options.idempotencyKey.trim();
+        }
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(evidenceBody),
+        }, { retryBody: evidenceBody });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor evidence HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        return {
+            intentId: body.intent_id,
+            tenant: body.tenant,
+            state: body.state,
+            predicatePassed: body.predicate_passed,
+        };
+    }
+    /**
+     * `GET /ledger/v1/tip` — latest sequence and entry commitment for the authenticated tenant.
+     *
+     * @throws HarborHttpError on HTTP failure
+     * @throws Error when JSON `tenant_id` does not match the bound client tenant
+     */
+    async getLedgerTip() {
+        const url = `${this.base}ledger/v1/tip`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor ledger tip HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        this.assertLedgerTenant(body, url);
+        return body;
+    }
+    /**
+     * `GET /ledger/v1/authority` — hex-encoded Ed25519 verifying key for this Harbor deployment.
+     */
+    async getLedgerAuthority() {
+        const url = `${this.base}ledger/v1/authority`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor ledger authority HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        this.assertLedgerTenant(body, url);
+        return body;
+    }
+    /**
+     * `GET /ledger/v1/events` — paginated append-only history; `afterSeq` is an exclusive cursor.
+     * `limit` is clamped to 1…256 to match Harbor.
+     */
+    async getLedgerEvents(options) {
+        const afterSeq = Math.max(0, Math.floor(options?.afterSeq ?? 0));
+        const rawLimit = options?.limit ?? 64;
+        const limit = Math.max(1, Math.min(Math.floor(rawLimit), 256));
+        const qs = new URLSearchParams({
+            after_seq: String(afterSeq),
+            limit: String(limit),
+        });
+        const url = `${this.base}ledger/v1/events?${qs.toString()}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor ledger events HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        this.assertLedgerTenant(body, url);
+        return body;
+    }
+    /**
+     * `GET /ledger/v1/merkle/latest` — last Merkle checkpoint envelope for the tenant (checkpoint may be null).
+     */
+    async getLedgerMerkleLatest() {
+        const url = `${this.base}ledger/v1/merkle/latest`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new HarborHttpError(`Harbor ledger merkle HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        this.assertLedgerTenant(body, url);
+        return body;
+    }
+}
+/**
+ * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
+ */
+export class PaybondIntents {
+    harbor;
+    constructor(harbor) {
+        this.harbor = harbor;
+    }
+    /**
+     * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be 32 bytes.
+     */
+    async create(params) {
+        const { idempotencyKey, intentId: maybeIntentId, ...fields } = params;
+        const intentId = maybeIntentId ?? globalThis.crypto.randomUUID();
+        const body = buildSignedCreateIntentBody({
+            tenantId: this.harbor.tenantId,
+            intentId,
+            ...fields,
+        });
+        return this.harbor.createIntent(body, { idempotencyKey });
+    }
+    /**
+     * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
+     */
+    async submitEvidence(params) {
+        const { idempotencyKey, ...rest } = params;
+        const wire = signPayeeEvidenceBinding({
+            tenantId: this.harbor.tenantId,
+            ...rest,
+        });
+        return this.harbor.submitEvidence(rest.intentId, wire, { idempotencyKey });
+    }
+}
+/**
+ * High-level Kit entrypoint: same session lifecycle as {@link ServiceAccountHarborSession}, plus {@link PaybondIntents}.
+ */
+export class Paybond {
+    harbor;
+    intents;
+    session;
+    constructor(session) {
+        this.session = session;
+        this.harbor = session.harbor;
+        this.intents = new PaybondIntents(session.harbor);
+    }
+    /** Open a tenant-bound session via gateway `harbor-access` exchange. */
+    static async open(init) {
+        const session = await ServiceAccountHarborSession.open(init);
+        return new Paybond(session);
+    }
+    async rotateHarborToken() {
+        await this.session.rotateHarborToken();
+    }
+    /** Release HTTP resources (Harbor client + gateway token provider). */
+    async aclose() {
+        await this.session.aclose();
+    }
+}
+export { normalizeJson, jsonValueDigest } from "./json-digest.js";
+export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, } from "./principal-intent.js";
+export { artifactsDigest, signPayeeEvidenceBinding } from "./payee-evidence.js";

package/dist/json-digest.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical JSON normalization and BLAKE3 digest (matches `paybond-evidence` / Harbor signing).
+ */
+/** Recursively sort object keys for stable JSON serialization. */
+export declare function normalizeJson(value: unknown): unknown;
+/** BLAKE3 digest (32 bytes) over compact JSON of {@link normalizeJson}. */
+export declare function jsonValueDigest(value: unknown): Uint8Array;

package/dist/json-digest.js

@@ -0,0 +1,29 @@
+/**
+ * Canonical JSON normalization and BLAKE3 digest (matches `paybond-evidence` / Harbor signing).
+ */
+import { hash } from "blake3";
+/** Recursively sort object keys for stable JSON serialization. */
+export function normalizeJson(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeJson(item));
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const out = {};
+    for (const k of keys) {
+        if (Object.prototype.hasOwnProperty.call(obj, k)) {
+            out[k] = normalizeJson(obj[k]);
+        }
+    }
+    return out;
+}
+/** BLAKE3 digest (32 bytes) over compact JSON of {@link normalizeJson}. */
+export function jsonValueDigest(value) {
+    const normalized = normalizeJson(value);
+    const text = JSON.stringify(normalized);
+    const buf = hash(text, { length: 32 });
+    return new Uint8Array(buf);
+}

package/dist/payee-evidence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Payee evidence signing bytes (matches `paybond-evidence` `EvidenceSignV1` + `encode_evidence_sign_v1`).
+ */
+/** BLAKE3 digest of concatenated artifact hashes (empty list matches Harbor / `paybond-evidence`). */
+export declare function artifactsDigest(artifactHashes32: Uint8Array[]): Uint8Array;
+export type SignPayeeEvidenceParams = {
+    tenantId: string;
+    intentId: string;
+    payeeDid: string;
+    payload: Record<string, unknown>;
+    artifactsBlake3Hex: string[];
+    submittedAtRfc3339: string;
+    payeeSigningSeed: Uint8Array;
+};
+/** Build Harbor `POST /intents/{id}/evidence` JSON with detached Ed25519 payee signature. */
+export declare function signPayeeEvidenceBinding(params: SignPayeeEvidenceParams): Record<string, unknown>;

package/dist/payee-evidence.js

@@ -0,0 +1,89 @@
+/**
+ * Payee evidence signing bytes (matches `paybond-evidence` `EvidenceSignV1` + `encode_evidence_sign_v1`).
+ */
+import { sign, getPublicKey } from "@noble/ed25519";
+import { createHash } from "blake3";
+import { parse as parseUuid } from "uuid";
+import { jsonValueDigest } from "./json-digest.js";
+function concatBytes(...parts) {
+    const n = parts.reduce((a, p) => a + p.length, 0);
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function encodeU64(n) {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+    return b;
+}
+function encodeBincodeString(s) {
+    const utf8 = new TextEncoder().encode(s);
+    return concatBytes(encodeU64(utf8.length), utf8);
+}
+/** BLAKE3 digest of concatenated artifact hashes (empty list matches Harbor / `paybond-evidence`). */
+export function artifactsDigest(artifactHashes32) {
+    const h = createHash();
+    for (const a of artifactHashes32) {
+        h.update(a);
+    }
+    const buf = h.digest({ length: 32 });
+    return new Uint8Array(buf);
+}
+function encodeEvidenceSignV1(input) {
+    const version = new Uint8Array([1]);
+    const intentBytes = parseUuid(input.intentId);
+    if (intentBytes.length !== 16) {
+        throw new Error("intentId must be a UUID string");
+    }
+    if (input.payloadDigest.length !== 32 || input.artifactsDigest.length !== 32) {
+        throw new Error("digest must be 32 bytes");
+    }
+    return concatBytes(version, encodeBincodeString(input.tenantId), encodeU64(16), intentBytes, encodeBincodeString(input.payeeDid), input.payloadDigest, input.artifactsDigest, encodeBincodeString(input.submittedAtRfc3339));
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+}
+function hexToBytes(hex) {
+    const s = hex.trim();
+    if (s.length % 2 !== 0)
+        throw new Error("bad hex");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/** Build Harbor `POST /intents/{id}/evidence` JSON with detached Ed25519 payee signature. */
+export function signPayeeEvidenceBinding(params) {
+    if (params.payeeSigningSeed.length !== 32) {
+        throw new Error("payeeSigningSeed must be 32 bytes");
+    }
+    const artifactBin = params.artifactsBlake3Hex.map((h) => hexToBytes(h));
+    const payloadDigest = jsonValueDigest(params.payload);
+    const artDigest = artifactsDigest(artifactBin);
+    const msg = encodeEvidenceSignV1({
+        tenantId: params.tenantId,
+        intentId: params.intentId,
+        payeeDid: params.payeeDid,
+        payloadDigest,
+        artifactsDigest: artDigest,
+        submittedAtRfc3339: params.submittedAtRfc3339,
+    });
+    const sig = sign(msg, params.payeeSigningSeed);
+    const pub = getPublicKey(params.payeeSigningSeed);
+    return {
+        payload: params.payload,
+        artifacts: params.artifactsBlake3Hex,
+        payee_did: params.payeeDid,
+        payee_pubkey: bytesToBase64(pub),
+        payee_signature: bytesToBase64(sig),
+        submitted_at: params.submittedAtRfc3339,
+    };
+}

package/dist/principal-intent.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Principal intent creation signing for raw `predicate_dsl` (no managed-policy binding).
+ * Matches `crates/harbor-intent-escrow/src/signing.rs` (`intent_creation_sign_bytes_raw`).
+ */
+export declare function intentCreationSignBytesRaw(input: {
+    tenantId: string;
+    intentId: string;
+    principalDid: string;
+    payeeDid: string;
+    amountCents: number;
+    currency: string;
+    deadlineRfc3339: string;
+    budget: Record<string, unknown>;
+    evidenceSchema: Record<string, unknown>;
+    predicate: Record<string, unknown>;
+    predicateRef: string;
+    allowedTools: string[];
+}): Uint8Array;
+export type BuildSignedCreateIntentParams = {
+    tenantId: string;
+    intentId: string;
+    principalDid: string;
+    principalSigningSeed: Uint8Array;
+    payeeDid: string;
+    budget: Record<string, unknown>;
+    predicate: Record<string, unknown>;
+    currency: string;
+    amountCents: number;
+    evidenceSchema: Record<string, unknown>;
+    deadlineRfc3339: string;
+    allowedTools: string[];
+    predicateRef?: string;
+};
+/**
+ * Build a Harbor `POST /intents` JSON body with principal Ed25519 detached signature.
+ */
+export declare function buildSignedCreateIntentBody(params: BuildSignedCreateIntentParams): Record<string, unknown>;

package/dist/principal-intent.js

@@ -0,0 +1,128 @@
+/**
+ * Principal intent creation signing for raw `predicate_dsl` (no managed-policy binding).
+ * Matches `crates/harbor-intent-escrow/src/signing.rs` (`intent_creation_sign_bytes_raw`).
+ */
+import { sign, getPublicKey } from "@noble/ed25519";
+import { parse as parseUuid } from "uuid";
+import { jsonValueDigest } from "./json-digest.js";
+function concatBytes(...parts) {
+    const n = parts.reduce((a, p) => a + p.length, 0);
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function encodeU64(n) {
+    if (!Number.isInteger(n) || n < 0) {
+        throw new Error("encodeU64: expected non-negative integer");
+    }
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+    return b;
+}
+function encodeI64(n) {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigInt64(0, BigInt(n), true);
+    return b;
+}
+function encodeBincodeString(s) {
+    const utf8 = new TextEncoder().encode(s);
+    return concatBytes(encodeU64(utf8.length), utf8);
+}
+function dslDigest(predicate) {
+    return jsonValueDigest(predicate);
+}
+function allowedToolsDigest(tools) {
+    const sorted = [...tools]
+        .map((s) => s.trim().toLowerCase())
+        .sort()
+        .filter((v, i, a) => a.indexOf(v) === i);
+    return jsonValueDigest(sorted);
+}
+/** Bincode payload for principal intent creation (wire format revision byte `2`). */
+function encodeIntentCreationSign(input) {
+    const version = new Uint8Array([2]);
+    const intentBytes = parseUuid(input.intentId);
+    if (intentBytes.length !== 16) {
+        throw new Error("intentId must be a UUID string");
+    }
+    // Serde `Uuid` + bincode uses a u64 length prefix (16) before the raw 16 bytes (matches Rust).
+    return concatBytes(version, encodeBincodeString(input.tenantId), encodeU64(16), intentBytes, encodeBincodeString(input.principalDid), encodeBincodeString(input.payeeDid), encodeI64(input.amountCents), encodeBincodeString(input.currency), encodeBincodeString(input.deadlineRfc3339), input.budgetDigest, input.evidenceSchemaDigest, input.predicateDslDigest, encodeBincodeString(input.predicateRef), input.allowedToolsDigest);
+}
+export function intentCreationSignBytesRaw(input) {
+    const budgetDigest = jsonValueDigest(input.budget);
+    const evidenceSchemaDigest = jsonValueDigest(input.evidenceSchema);
+    const predicateDslDigest = dslDigest(input.predicate);
+    const allowedDigest = allowedToolsDigest(input.allowedTools);
+    return encodeIntentCreationSign({
+        tenantId: input.tenantId,
+        intentId: input.intentId,
+        principalDid: input.principalDid,
+        payeeDid: input.payeeDid,
+        amountCents: input.amountCents,
+        currency: input.currency,
+        deadlineRfc3339: input.deadlineRfc3339,
+        budgetDigest,
+        evidenceSchemaDigest,
+        predicateDslDigest,
+        predicateRef: input.predicateRef,
+        allowedToolsDigest: allowedDigest,
+    });
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+}
+/**
+ * Build a Harbor `POST /intents` JSON body with principal Ed25519 detached signature.
+ */
+export function buildSignedCreateIntentBody(params) {
+    if (params.principalSigningSeed.length !== 32) {
+        throw new Error("principalSigningSeed must be 32 bytes");
+    }
+    if (params.allowedTools.length === 0) {
+        throw new Error("allowedTools must be non-empty");
+    }
+    const predicateRef = params.predicateRef ?? "";
+    const msg = intentCreationSignBytesRaw({
+        tenantId: params.tenantId,
+        intentId: params.intentId,
+        principalDid: params.principalDid,
+        payeeDid: params.payeeDid,
+        amountCents: params.amountCents,
+        currency: params.currency,
+        deadlineRfc3339: params.deadlineRfc3339,
+        budget: params.budget,
+        evidenceSchema: params.evidenceSchema,
+        predicate: params.predicate,
+        predicateRef,
+        allowedTools: params.allowedTools,
+    });
+    const sig = sign(msg, params.principalSigningSeed);
+    const pub = getPublicKey(params.principalSigningSeed);
+    const body = {
+        intent_id: params.intentId,
+        principal_did: params.principalDid,
+        principal_pubkey: bytesToBase64(pub),
+        principal_signature: bytesToBase64(sig),
+        payee_did: params.payeeDid,
+        budget: params.budget,
+        currency: params.currency,
+        amount_cents: params.amountCents,
+        evidence_schema: params.evidenceSchema,
+        deadline: params.deadlineRfc3339,
+        predicate_dsl: params.predicate,
+        signing_version: 2,
+        policy_binding: null,
+        allowed_tools: params.allowedTools,
+    };
+    if (predicateRef.trim() !== "") {
+        body.predicate_ref = predicateRef;
+    }
+    return body;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@paybond/kit",
+  "version": "0.1.0",
+  "description": "Paybond Kit for TypeScript: tenant-bound Harbor sessions, capability verification, and signed intent/evidence flows.",
+  "license": "(MIT OR Apache-2.0)",
+  "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"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nonameuserd/pacta.git",
+    "directory": "kit/ts"
+  },
+  "homepage": "https://github.com/nonameuserd/pacta/tree/main/kit/ts",
+  "bugs": {
+    "url": "https://github.com/nonameuserd/pacta/issues"
+  },
+  "keywords": [
+    "paybond",
+    "harbor",
+    "agents",
+    "typescript",
+    "escrow",
+    "capabilities"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "clean": "node ./scripts/clean-dist.mjs",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "pack:dry-run": "npm pack --dry-run",
+    "verify:release": "node ./scripts/verify-release.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.2.1",
+    "blake3": "^2.1.7",
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
+}