@treeship/verify 0.9.2

package/README.md

@@ -0,0 +1,143 @@
+# @treeship/verify
+
+Zero-dependency cryptographic verification for [Treeship](https://treeship.dev) Session Receipts and Agent Certificates. Runs anywhere WebAssembly and `fetch` are available.
+
+## Install
+
+```bash
+npm install @treeship/verify
+```
+
+The only dependency is `@treeship/core-wasm` (the compiled Rust core, under 170 KB gzipped). No transitive dependency on `@treeship/sdk`, so you can ship this to an edge worker, browser dashboard, or audit tool without pulling the subprocess code path in at all.
+
+## API
+
+Three functions. Each accepts a parsed object, a JSON string, or a URL.
+
+### `verifyReceipt(target)`
+
+Runs the JSON-level checks a Treeship Session Receipt carries: Merkle root recomputation, inclusion proof verification, leaf-count parity, timeline ordering, chain linkage.
+
+```typescript
+import { verifyReceipt } from '@treeship/verify';
+
+const result = await verifyReceipt('https://treeship.dev/receipt/ssn_abc');
+
+if (result.outcome === 'pass') {
+  console.log(`session ${result.session.id} verified`);
+} else {
+  console.log(`verification failed:`, result.checks.filter(c => c.status === 'fail'));
+}
+```
+
+### `verifyCertificate(target, now?)`
+
+Verifies the Ed25519 signature on an Agent Certificate against the public key embedded in the certificate. With `now` supplied (Date or RFC 3339 string), also classifies the validity window.
+
+```typescript
+import { verifyCertificate } from '@treeship/verify';
+
+const result = await verifyCertificate('./researcher.agent/certificate.json', new Date());
+
+if (result.outcome === 'pass' && result.validity === 'valid') {
+  console.log(`certificate valid for ${result.certificate.agent_name}`);
+}
+```
+
+### `crossVerify(receipt, certificate, now?)`
+
+Answers three questions: do the receipt and certificate reference the same ship, was the certificate valid at `now`, was every tool the session called authorized by the certificate. The `ok` field is the roll-up.
+
+```typescript
+import { crossVerify } from '@treeship/verify';
+
+const result = await crossVerify(
+  'https://treeship.dev/receipt/ssn_abc',
+  'https://example.com/researcher.agent.json',
+);
+
+if (result.ok) {
+  console.log('complete trust loop verified');
+} else {
+  console.log('ship_id_status:', result.ship_id_status);
+  console.log('unauthorized:', result.unauthorized_tool_calls);
+}
+```
+
+## Runtime compatibility
+
+| Runtime | Supported |
+|---------|-----------|
+| Node.js 18+ | yes |
+| Node.js 20+ | yes |
+| Deno | yes |
+| Browser (bundler) | yes |
+| Vercel Edge | yes |
+| Cloudflare Workers | yes |
+| AWS Lambda (Node) | yes |
+
+The package ships `@treeship/core-wasm` with `--target bundler`. Runtimes that need a different WASM wrapper (plain Node without a bundler) can still consume the core via the subprocess-backed `@treeship/sdk`.
+
+## Examples
+
+### Vercel Edge Function
+
+```typescript
+import { verifyReceipt } from '@treeship/verify';
+
+export const config = { runtime: 'edge' };
+
+export default async function handler(req: Request) {
+  const { url } = await req.json();
+  const result = await verifyReceipt(url);
+  return Response.json(result);
+}
+```
+
+### Cloudflare Worker
+
+```typescript
+import { verifyReceipt } from '@treeship/verify';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const { url } = await request.json();
+    const result = await verifyReceipt(url);
+    return Response.json(result);
+  },
+};
+```
+
+### AWS Lambda (Node runtime)
+
+```typescript
+import { verifyReceipt } from '@treeship/verify';
+
+export const handler = async (event: { body: string }) => {
+  const { url } = JSON.parse(event.body);
+  const result = await verifyReceipt(url);
+  return { statusCode: 200, body: JSON.stringify(result) };
+};
+```
+
+### Browser dashboard
+
+```typescript
+import { verifyReceipt } from '@treeship/verify';
+
+const file = await fileInput.files[0];
+const text = await file.text();
+const result = await verifyReceipt(text);
+
+renderChecks(result.checks);
+```
+
+## What this package is NOT
+
+- **Not an attestation SDK.** For signing artifacts, session management, Hub push/pull, or agent registration, use [`@treeship/sdk`](../sdk-ts/) which shells out to the `treeship` CLI.
+- **Not a trust anchor.** The embedded Ed25519 signature on an Agent Certificate is verified against the certificate's own public key. Chaining a certificate to a trusted issuer is the caller's responsibility.
+- **Not a drop-in for local-chain verification.** Some signature verification needs the original envelope bytes, which a URL-fetched receipt does not carry. Use `treeship verify <artifact-id>` on the CLI for that.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/** Accepted input shapes across all exported functions. */
+export type VerifyTarget = string | URL | Record<string, unknown>;
+export interface VerifyCheck {
+    step: string;
+    status: 'pass' | 'fail' | 'warn';
+    detail: string;
+}
+export interface VerifyReceiptResult {
+    outcome: 'pass' | 'fail' | 'error';
+    checks: VerifyCheck[];
+    session: {
+        id: string;
+        ship_id?: string;
+        schema_version?: string;
+        agent: string;
+        duration_ms?: number;
+        actions: number;
+    };
+    error_code?: string;
+    message?: string;
+}
+export interface VerifyCertificateResult {
+    outcome: 'pass' | 'fail' | 'error';
+    signature_valid: boolean;
+    validity: 'valid' | 'expired' | 'not_yet_valid' | 'not_checked';
+    certificate: {
+        ship_id: string;
+        agent_name: string;
+        issued_at: string;
+        valid_until: string;
+        schema_version?: string;
+    };
+    error_code?: string;
+    message?: string;
+}
+export interface CrossVerifyResult {
+    outcome: 'pass' | 'fail' | 'error';
+    ok: boolean;
+    ship_id_status: 'match' | 'mismatch' | 'unknown';
+    certificate_status: 'valid' | 'expired' | 'not_yet_valid';
+    certificate_signature_valid: boolean;
+    authorized_tool_calls: string[];
+    unauthorized_tool_calls: string[];
+    authorized_tools_never_called: string[];
+    error_code?: string;
+    message?: string;
+}
+/**
+ * Verify a Treeship Session Receipt. Runs the checks derivable from the
+ * receipt JSON alone (Merkle root recomputation, inclusion proofs, leaf
+ * count, timeline ordering, chain linkage). Signature verification on
+ * individual envelopes requires the original envelope bytes and is out of
+ * scope for URL-fetched receipts; use the `treeship verify` CLI for that.
+ *
+ * Accepts:
+ * - a parsed receipt object (best for callers that already have the JSON)
+ * - a JSON string
+ * - a URL string (fetched with the runtime's global fetch)
+ * - a URL object
+ */
+export declare function verifyReceipt(target: VerifyTarget): Promise<VerifyReceiptResult>;
+/**
+ * Verify an Agent Certificate. Checks the embedded Ed25519 signature
+ * against the certificate's embedded public key, then optionally
+ * classifies the validity window relative to `now`.
+ *
+ * Omit `now` (or pass `undefined`) to defer validity classification
+ * (signature-only). Pass a `Date` or RFC 3339 string to check expiry.
+ */
+export declare function verifyCertificate(target: VerifyTarget, now?: Date | string): Promise<VerifyCertificateResult>;
+/**
+ * Cross-verify a Session Receipt against an Agent Certificate. Answers
+ * three questions in one call: do the receipt and certificate reference
+ * the same ship? Was the certificate valid at `now`? Was every tool the
+ * session called authorized by the certificate?
+ *
+ * The `ok` field is the roll-up: true iff all three checks pass. Defaults
+ * `now` to `Date.now()` if omitted.
+ */
+export declare function crossVerify(receipt: VerifyTarget, certificate: VerifyTarget, now?: Date | string): Promise<CrossVerifyResult>;

package/dist/index.js

@@ -0,0 +1,89 @@
+// @treeship/verify -- zero-dependency cryptographic verification.
+//
+// Install this package alone to verify Treeship Session Receipts and Agent
+// Certificates in any runtime with WebAssembly and fetch. It is deliberately
+// tiny: the only dependency is @treeship/core-wasm (the compiled Rust core,
+// ~170 KB gzipped). There is no transitive dependency on @treeship/sdk,
+// so shipping this to an edge worker, browser dashboard, or Witness doesn't
+// pull the subprocess code path in at all.
+//
+// Same rules `treeship verify` applies from the CLI, same result shape.
+// If a new schema version lands in core, this package picks it up via
+// core-wasm without an API change here.
+let wasmBindings = null;
+async function loadWasm() {
+    if (wasmBindings)
+        return wasmBindings;
+    const mod = (await import('@treeship/core-wasm'));
+    wasmBindings = mod;
+    return mod;
+}
+async function normalizeToJson(target) {
+    if (typeof target === 'object' && !(target instanceof URL)) {
+        return JSON.stringify(target);
+    }
+    const raw = target instanceof URL ? target.toString() : target;
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+        // Accept both the Hub JSON API path and the human-readable mirror.
+        const apiUrl = raw.replace('/receipt/', '/v1/receipt/');
+        const res = await fetch(apiUrl, { headers: { accept: 'application/json' } });
+        if (!res.ok)
+            throw new Error(`fetch ${apiUrl} returned HTTP ${res.status}`);
+        return await res.text();
+    }
+    return raw;
+}
+/**
+ * Verify a Treeship Session Receipt. Runs the checks derivable from the
+ * receipt JSON alone (Merkle root recomputation, inclusion proofs, leaf
+ * count, timeline ordering, chain linkage). Signature verification on
+ * individual envelopes requires the original envelope bytes and is out of
+ * scope for URL-fetched receipts; use the `treeship verify` CLI for that.
+ *
+ * Accepts:
+ * - a parsed receipt object (best for callers that already have the JSON)
+ * - a JSON string
+ * - a URL string (fetched with the runtime's global fetch)
+ * - a URL object
+ */
+export async function verifyReceipt(target) {
+    const json = await normalizeToJson(target);
+    const wasm = await loadWasm();
+    return JSON.parse(wasm.verify_receipt(json));
+}
+/**
+ * Verify an Agent Certificate. Checks the embedded Ed25519 signature
+ * against the certificate's embedded public key, then optionally
+ * classifies the validity window relative to `now`.
+ *
+ * Omit `now` (or pass `undefined`) to defer validity classification
+ * (signature-only). Pass a `Date` or RFC 3339 string to check expiry.
+ */
+export async function verifyCertificate(target, now) {
+    const json = await normalizeToJson(target);
+    const nowStr = now === undefined ? '' : now instanceof Date ? now.toISOString() : now;
+    const wasm = await loadWasm();
+    return JSON.parse(wasm.verify_certificate(json, nowStr));
+}
+/**
+ * Cross-verify a Session Receipt against an Agent Certificate. Answers
+ * three questions in one call: do the receipt and certificate reference
+ * the same ship? Was the certificate valid at `now`? Was every tool the
+ * session called authorized by the certificate?
+ *
+ * The `ok` field is the roll-up: true iff all three checks pass. Defaults
+ * `now` to `Date.now()` if omitted.
+ */
+export async function crossVerify(receipt, certificate, now) {
+    const [receiptJson, certJson] = await Promise.all([
+        normalizeToJson(receipt),
+        normalizeToJson(certificate),
+    ]);
+    const nowStr = now === undefined
+        ? new Date().toISOString()
+        : now instanceof Date
+            ? now.toISOString()
+            : now;
+    const wasm = await loadWasm();
+    return JSON.parse(wasm.cross_verify(receiptJson, certJson, nowStr));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@treeship/verify",
+  "version": "0.9.2",
+  "description": "Zero-dependency cryptographic verification for Treeship receipts and certificates. Runs anywhere WASM runs: Node, browser, Vercel Edge, Cloudflare Workers, AWS Lambda.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zerkerlabs/treeship",
+    "directory": "packages/verify-js"
+  },
+  "homepage": "https://treeship.dev",
+  "keywords": [
+    "treeship",
+    "verification",
+    "verify",
+    "attestation",
+    "receipts",
+    "certificate",
+    "cross-verification",
+    "wasm",
+    "edge",
+    "serverless"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@treeship/core-wasm": "0.9.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}