@vaultgraph/sdk 0.1.1

package/README.md

@@ -0,0 +1,110 @@
+# VaultGraph SDK
+
+VaultGraph client helpers for generating, signing, verifying, and submitting VaultGraph JobReceipts. Intended for server-side usage (Node 18+/edge runtimes with `fetch`).
+
+## Install
+
+```bash
+pnpm add @vaultgraph/sdk
+```
+
+## Usage
+
+### Generate a keypair (one-time, server-side)
+
+**Supported algorithm (MVP): Ed25519.** The ingestion API verifies with `algorithm: null`, which assumes Ed25519/Ed448; RSA/ECDSA signatures are not accepted right now.
+
+```ts
+import { generateKeyPairSync } from "crypto";
+
+const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
+  privateKeyEncoding: { format: "pem", type: "pkcs8" },
+  publicKeyEncoding: { format: "pem", type: "spki" },
+});
+
+console.log("Private key (keep secret):\n", privateKey);
+console.log("Public key (share with VaultGraph):\n", publicKey);
+```
+
+Store the private key in your secrets manager; never ship it to the browser. Publish the public key wherever you manage org settings or bundle it with exports.
+
+### Create, sign, verify, and submit
+
+```ts
+import {
+  createReceipt,
+  createSignedReceipt,
+  hashContext,
+  signReceipt,
+  submitReceipt,
+  verifyReceipt,
+} from "@vaultgraph/sdk";
+
+// 1) Hash any sensitive context before sending
+const contextHash = hashContext({ transcript: "..." });
+
+// 2) Build the canonical receipt payload
+const receipt = createReceipt({
+  agentId: "agent-123",
+  consumerId: "consumer-456",
+  jobId: "job-789",
+  resolution: "resolved",
+  contextHash,
+  metadata: { channel: "email" },
+});
+
+// 3) Sign the receipt (Ed25519, ECDSA, RSA supported)
+const { signature } = createSignedReceipt({
+  receipt,
+  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
+});
+
+// 4) Optionally verify locally
+const ok = verifyReceipt({
+  receipt,
+  signature,
+  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
+});
+
+// 5) Submit to your portal deployment
+await submitReceipt({
+  apiUrl: "https://app.vaultgraph.com", // or your self-hosted URL
+  receipt,
+  signature,
+  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
+  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
+});
+```
+
+### Convenience: create + sign in one step
+
+```ts
+import { createSignedReceipt } from "@vaultgraph/sdk";
+
+const { receipt, signature } = createSignedReceipt({
+  agentId: "agent-123",
+  consumerId: "consumer-456",
+  jobId: "job-789",
+  resolution: "resolved",
+  contextHash: "abc123",
+  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
+  metadata: { channel: "sms" },
+});
+```
+
+## API surface
+
+- `hashContext(value, options?)` → sha256 hash of canonical JSON/bytes
+- `createReceipt(input)` → normalized `JobReceipt`
+- `serializeReceipt(receipt)` → canonical JSON string
+- `signReceipt(options)` → signature string (base64 default)
+- `verifyReceipt(options)` → boolean
+- `createSignedReceipt(options)` → `{ receipt, signature }`
+- `submitReceipt(options)` → POSTs to `/api/receipts` (requires `apiKey`)
+- Types: `JobReceipt`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`
+
+## Notes
+
+- Do not send raw conversation context; send `context_hash` instead.
+- Keep your private key and vendor API key server-side only (API key is required for ingestion).
+- Receipt versioning currently `v0`; breaking changes will bump the major version of this package.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { KeyLike, BinaryToTextEncoding } from 'crypto';
+import { CreateReceiptInput, JobReceipt } from '@repo/lib/job-receipt';
+export { CreateReceiptInput, JOB_RESOLUTIONS, JobReceipt, JobReceiptV0, JobResolution, ReceiptVersion, canonicalJSONStringify, createReceipt, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, verifyReceipt } from '@repo/lib/job-receipt';
+export { SubmitReceiptOptions, SubmitReceiptResponse, submitReceipt } from '@repo/lib/submit-receipt';
+
+interface CreateSignedReceiptOptions extends CreateReceiptInput {
+    privateKey: KeyLike;
+    algorithm?: string | null;
+    encoding?: BinaryToTextEncoding;
+}
+/**
+ * Convenience helper to construct and sign a receipt in one step.
+ */
+declare function createSignedReceipt(options: CreateSignedReceiptOptions): {
+    receipt: JobReceipt;
+    signature: string;
+};
+
+export { type CreateSignedReceiptOptions, createSignedReceipt };

package/dist/index.js

@@ -0,0 +1,237 @@
+import { createHash, sign, verify, createPrivateKey, createPublicKey } from 'crypto';
+
+// ../lib/src/job-receipt.ts
+var JOB_RESOLUTIONS = ["resolved", "partial", "failed"];
+var VALID_JOB_RESOLUTIONS = JOB_RESOLUTIONS;
+var jobReceiptV0Schema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://vaultgraph.com/schemas/job-receipt-v0.json",
+  type: "object",
+  required: [
+    "version",
+    "agent_id",
+    "consumer_id",
+    "job_id",
+    "resolution",
+    "context_hash",
+    "issued_at",
+    "metadata"
+  ],
+  properties: {
+    version: { type: "string", enum: ["v0"] },
+    agent_id: { type: "string", minLength: 1 },
+    consumer_id: { type: "string", minLength: 1 },
+    job_id: { type: "string", minLength: 1 },
+    resolution: { type: "string", enum: [...JOB_RESOLUTIONS] },
+    context_hash: { type: "string", minLength: 1 },
+    issued_at: { type: "string", format: "date-time" },
+    metadata: {
+      type: "object",
+      additionalProperties: true
+    }
+  },
+  additionalProperties: false
+};
+function canonicalJSONStringify(value) {
+  return canonicalize(value);
+}
+function hashContext(value, options = {}) {
+  const encoding = options.encoding ?? "hex";
+  const payload = typeof value === "string" || value instanceof Uint8Array ? value : canonicalJSONStringify(value);
+  return createHash("sha256").update(payload).digest(encoding);
+}
+function createReceipt(input) {
+  const receipt = {
+    version: "v0",
+    agent_id: normalizeNonEmpty(input.agentId, "agentId"),
+    consumer_id: normalizeNonEmpty(input.consumerId, "consumerId"),
+    job_id: normalizeNonEmpty(input.jobId, "jobId"),
+    resolution: validateResolution(input.resolution),
+    context_hash: normalizeNonEmpty(input.contextHash, "contextHash"),
+    issued_at: normalizeIssuedAt(input.issuedAt),
+    metadata: normalizeMetadata(input.metadata)
+  };
+  assertValidReceipt(receipt);
+  return receipt;
+}
+function serializeReceipt(receipt) {
+  assertValidReceipt(receipt);
+  return canonicalJSONStringify(receipt);
+}
+function signReceipt(options) {
+  const privateKey = normalizePrivateKey(options.privateKey);
+  const algorithm = resolveAlgorithm(privateKey, options.algorithm);
+  const payload = serializeReceipt(options.receipt);
+  const signature = sign(algorithm, Buffer.from(payload), privateKey);
+  return signature.toString(options.encoding ?? "base64");
+}
+function verifyReceipt(options) {
+  const publicKey = normalizePublicKey(options.publicKey);
+  const algorithm = resolveAlgorithm(publicKey, options.algorithm);
+  const payload = serializeReceipt(options.receipt);
+  const signature = typeof options.signature === "string" ? Buffer.from(options.signature, options.encoding ?? "base64") : options.signature;
+  return verify(algorithm, Buffer.from(payload), publicKey, signature);
+}
+function normalizeNonEmpty(value, field) {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) {
+    throw new Error(`${field} is required`);
+  }
+  return trimmed;
+}
+function validateResolution(resolution) {
+  if (!VALID_JOB_RESOLUTIONS.includes(resolution)) {
+    throw new Error(`Invalid resolution: ${resolution}`);
+  }
+  return resolution;
+}
+function normalizeIssuedAt(issuedAt) {
+  if (!issuedAt) {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  if (issuedAt instanceof Date) {
+    return issuedAt.toISOString();
+  }
+  const parsed = new Date(issuedAt);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(
+      "issuedAt must be a valid ISO date string or Date instance"
+    );
+  }
+  return parsed.toISOString();
+}
+function normalizeMetadata(metadata) {
+  if (metadata === void 0) return {};
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error("metadata must be a plain object");
+  }
+  return metadata;
+}
+function assertValidReceipt(receipt) {
+  normalizeNonEmpty(receipt.agent_id, "agent_id");
+  normalizeNonEmpty(receipt.consumer_id, "consumer_id");
+  normalizeNonEmpty(receipt.job_id, "job_id");
+  normalizeNonEmpty(receipt.context_hash, "context_hash");
+  validateResolution(receipt.resolution);
+  normalizeIssuedAt(receipt.issued_at);
+  normalizeMetadata(receipt.metadata);
+}
+function normalizePrivateKey(key) {
+  return typeof key === "string" || Buffer.isBuffer(key) ? createPrivateKey(key) : key;
+}
+function normalizePublicKey(key) {
+  return typeof key === "string" || Buffer.isBuffer(key) ? createPublicKey(key) : key;
+}
+function resolveAlgorithm(key, algorithm) {
+  if (algorithm !== void 0) {
+    return algorithm;
+  }
+  const keyType = key.asymmetricKeyType;
+  if (keyType === "ed25519" || keyType === "ed448") {
+    return null;
+  }
+  return "sha256";
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  const type = typeof value;
+  if (type === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("Non-finite numbers are not supported in canonical JSON");
+    }
+    return JSON.stringify(value);
+  }
+  if (type === "boolean" || type === "string") {
+    return JSON.stringify(value);
+  }
+  if (value instanceof Date) {
+    return JSON.stringify(value.toISOString());
+  }
+  if (value instanceof Uint8Array) {
+    return JSON.stringify(Buffer.from(value).toString("base64"));
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => canonicalize(item)).join(",");
+    return `[${items}]`;
+  }
+  if (type === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const entries = keys.map(
+      (key) => `${JSON.stringify(key)}:${canonicalize(obj[key])}`
+    );
+    return `{${entries.join(",")}}`;
+  }
+  throw new Error("Unsupported data type for canonical JSON");
+}
+
+// ../lib/src/submit-receipt.ts
+async function submitReceipt(options) {
+  const {
+    apiUrl,
+    receipt,
+    signature,
+    publicKey,
+    metadata,
+    apiKey,
+    fetchImpl
+  } = options;
+  if (!apiUrl || !apiUrl.trim()) {
+    throw new Error("apiUrl is required");
+  }
+  if (!apiKey || !apiKey.trim()) {
+    throw new Error("apiKey is required");
+  }
+  const target = new URL("/api/receipts", apiUrl).toString();
+  const fetcher = fetchImpl ?? fetch;
+  const res = await fetcher(target, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey
+    },
+    body: JSON.stringify({
+      receipt,
+      signature,
+      public_key: publicKey,
+      metadata
+    })
+  });
+  const payload = await safeParseJson(res);
+  if (!res.ok) {
+    const detail = payload && typeof payload === "object" ? payload : null;
+    const message = detail?.detail || detail?.error || res.statusText || "Receipt submission failed";
+    throw new Error(message);
+  }
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid response payload");
+  }
+  const id = payload.id;
+  const status = payload.status;
+  if (!id || !status) {
+    throw new Error("Response missing id or status");
+  }
+  return { id, status };
+}
+async function safeParseJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+// src/index.ts
+function createSignedReceipt(options) {
+  const { privateKey, algorithm, encoding, ...receiptInput } = options;
+  const receipt = createReceipt(receiptInput);
+  const signature = signReceipt({
+    receipt,
+    privateKey,
+    algorithm,
+    encoding
+  });
+  return { receipt, signature };
+}
+
+export { JOB_RESOLUTIONS, canonicalJSONStringify, createReceipt, createSignedReceipt, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, submitReceipt, verifyReceipt };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@vaultgraph/sdk",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "vaultgraph",
+    "sdk",
+    "ai",
+    "agent",
+    "job-receipt",
+    "trust",
+    "trust-layer",
+    "trust-score",
+    "attestation",
+    "verification"
+  ],
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check-types": "tsc --noEmit",
+    "release": "bash ./scripts/publish.sh"
+  },
+  "devDependencies": {
+    "@repo/lib": "workspace:*",
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@repo/vitest-config": "workspace:*",
+    "@types/node": "^22.15.3",
+    "eslint": "^9.39.1",
+    "tsup": "^8.3.6",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.16"
+  }
+}