privateer-agent 0.7.0 → 0.8.0

package/src/providers/phala/aci-verifier/jcs.ts

@@ -0,0 +1,69 @@
+/**
+ * JSON Canonicalization Scheme (RFC 8785) for the ACI subset.
+ *
+ * ACI restricts JSON numbers to integers (§3), so this omits ECMAScript number
+ * formatting and instead *rejects* non-integer numbers — a conformant ACI object
+ * never contains one, and rejecting is safer than silently mis-serializing. For
+ * strings we reuse `JSON.stringify`, whose escaping is exactly RFC 8785's
+ * (minimal escapes, `\uXXXX` for other controls, lone surrogates escaped) since
+ * ES2019. Object members are ordered by their UTF-16 code units, which is what
+ * JavaScript's `<` on strings compares, and `undefined`-valued members are
+ * dropped (standard JSON behaviour) — build with explicit `null` where a field
+ * must appear.
+ */
+
+import { AciFormatError } from './errors';
+
+/** A value canonicalizable under the ACI JCS subset. */
+export type JcsValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JcsValue[]
+  | { [key: string]: JcsValue | undefined };
+
+/** Canonicalize a value to its RFC 8785 string form. */
+export function canonicalize(value: JcsValue): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isInteger(value)) {
+        throw new AciFormatError(
+          `JCS: ACI restricts numbers to integers, got ${value} (§3)`,
+        );
+      }
+      // -0 canonicalizes to "0".
+      return Object.is(value, -0) ? '0' : String(value);
+    case 'string':
+      return JSON.stringify(value);
+    case 'object':
+      if (Array.isArray(value)) {
+        return '[' + value.map(canonicalize).join(',') + ']';
+      }
+      return serializeObject(value);
+    default:
+      throw new AciFormatError(`JCS: unsupported type ${typeof value}`);
+  }
+}
+
+function serializeObject(obj: { [key: string]: JcsValue | undefined }): string {
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    // RFC 8785 orders by UTF-16 code units; JS `<` on strings does exactly that.
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  let out = '{';
+  for (let i = 0; i < keys.length; i++) {
+    const k = keys[i]!;
+    if (i > 0) out += ',';
+    out += JSON.stringify(k) + ':' + canonicalize(obj[k] as JcsValue);
+  }
+  return out + '}';
+}
+
+/** Canonicalize and encode to UTF-8 bytes — the form fed to SHA-256 and signatures. */
+export function jcsBytes(value: JcsValue): Uint8Array {
+  return new TextEncoder().encode(canonicalize(value));
+}

package/src/providers/phala/aci-verifier/receipt.ts

@@ -0,0 +1,139 @@
+/**
+ * Level 1 receipt verification (§10.2 checks 1–2) and helpers for the body-hash
+ * checks (§10.2 checks 3–4). "Established identity and keyset" means a keyset the
+ * caller already trusts — from a Level 2 report verification, or published by a
+ * party the client trusts. The recomputed `workload_id` and keyset digest of
+ * that keyset are the values the receipt must match.
+ */
+
+import { receiptSigningBytes, computeWorkloadId, computeKeysetDigest } from './digest';
+import { verifySignature, sha256Prefixed } from './crypto';
+import { fromHex } from './crypto';
+import type { Receipt, ReceiptEvent, WorkloadKeyset, Check, ReceiptVerification } from './types';
+
+/**
+ * Verify a receipt against an established keyset — §10.2 checks 1 and 2:
+ *
+ * 1. `signature.key_id` names a key in the keyset's `receipt_signing_keys`,
+ *    `signature.algo` matches that key, and the signature verifies over the
+ *    §8.5 canonical bytes under that key.
+ * 2. The receipt's `workload_id` and `workload_keyset_digest` equal the values
+ *    recomputed from the established keyset (§4.1, §4.2).
+ *
+ * Returns a per-check result — a failed check is `ok: false`, never thrown.
+ * Throws {@link UnsupportedAlgorithmError} only when the signing algorithm is
+ * outside Web Crypto scope (e.g. `ecdsa-secp256k1`).
+ */
+export async function verifyReceipt(
+  receipt: Receipt,
+  keyset: WorkloadKeyset,
+): Promise<ReceiptVerification> {
+  const checks: Check[] = [];
+
+  const establishedWorkloadId = await computeWorkloadId(keyset.workload_identity.public_key);
+  const establishedDigest = await computeKeysetDigest(keyset);
+
+  // Check 2: self-described identity matches the established keyset.
+  checks.push({
+    name: 'workload_id',
+    ok: receipt.workload_id === establishedWorkloadId,
+    ...(receipt.workload_id === establishedWorkloadId
+      ? {}
+      : { detail: `receipt ${receipt.workload_id} != established ${establishedWorkloadId}` }),
+  });
+  checks.push({
+    name: 'workload_keyset_digest',
+    ok: receipt.workload_keyset_digest === establishedDigest,
+    ...(receipt.workload_keyset_digest === establishedDigest
+      ? {}
+      : { detail: `receipt ${receipt.workload_keyset_digest} != established ${establishedDigest}` }),
+  });
+
+  // Check 1: signature under a named receipt signing key.
+  const keyEntry = keyset.receipt_signing_keys.find((k) => k.key_id === receipt.signature.key_id);
+  if (!keyEntry) {
+    checks.push({
+      name: 'signature',
+      ok: false,
+      detail: `signature.key_id "${receipt.signature.key_id}" not in receipt_signing_keys`,
+    });
+  } else if (receipt.signature.algo !== keyEntry.algo) {
+    // §3.1: the attested key decides the algorithm; the receipt may not override it.
+    checks.push({
+      name: 'signature',
+      ok: false,
+      detail: `signature.algo "${receipt.signature.algo}" != keyset entry algo "${keyEntry.algo}"`,
+    });
+  } else {
+    const message = receiptSigningBytes(receipt);
+    const ok = await verifySignature(
+      keyEntry.algo,
+      fromHex(keyEntry.public_key),
+      fromHex(receipt.signature.value),
+      message,
+      'receipt signature (§8.5)',
+    );
+    checks.push({ name: 'signature', ok, ...(ok ? {} : { detail: 'Ed25519 verification failed' }) });
+  }
+
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+/** Find the first event of a given type in a receipt's event log. */
+export function findEvent(receipt: Receipt, type: string): ReceiptEvent | undefined {
+  return receipt.event_log.find((e) => e.type === type);
+}
+
+/**
+ * `sha256:<hex>` of raw body bytes — the form ACI body hashes use (§3). Accepts a
+ * string (UTF-8 encoded) or raw bytes.
+ */
+export async function hashBody(body: Uint8Array | string): Promise<string> {
+  const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : body;
+  return sha256Prefixed(bytes);
+}
+
+/**
+ * §10.2 check 3: the request bytes the client sent match `request.received.body_hash`.
+ * For E2EE requests, pass the decrypted body as the service observed it (§8.3, §12).
+ * Returns false when the event or its hash is absent.
+ */
+export async function checkRequestBodyHash(
+  receipt: Receipt,
+  requestBody: Uint8Array | string,
+): Promise<boolean> {
+  const event = findEvent(receipt, 'request.received');
+  const expected = event?.body_hash;
+  if (typeof expected !== 'string') return false;
+  return (await hashBody(requestBody)) === expected;
+}
+
+/**
+ * §10.2 check 4: the response bytes the client received match
+ * `response.returned.wire_hash` — for a stream, the in-order raw SSE bytes.
+ * Returns false when the event or its hash is absent.
+ */
+export async function checkResponseWireHash(
+  receipt: Receipt,
+  responseBody: Uint8Array | string,
+): Promise<boolean> {
+  const event = findEvent(receipt, 'response.returned');
+  const expected = event?.wire_hash;
+  if (typeof expected !== 'string') return false;
+  return (await hashBody(responseBody)) === expected;
+}
+
+/**
+ * For E2EE responses, check the decrypted response bytes match
+ * `response.returned.cleartext_hash` (§10.2 check 4, §12). Only meaningful when
+ * the client can reproduce the service's pre-encryption serialization.
+ */
+export async function checkResponseCleartextHash(
+  receipt: Receipt,
+  cleartextBody: Uint8Array | string,
+): Promise<boolean> {
+  const event = findEvent(receipt, 'response.returned');
+  const expected = event?.cleartext_hash;
+  if (typeof expected !== 'string') return false;
+  return (await hashBody(cleartextBody)) === expected;
+}

package/src/providers/phala/aci-verifier/report.ts

@@ -0,0 +1,126 @@
+/**
+ * Level 2 report-binding checks (§10.1 checks 2–6), minus the hardware root of
+ * trust. This verifies the *cryptographic binding* of the report — that its
+ * `workload_id`, keyset digest, `report_data`, and endorsement are internally
+ * consistent and endorsed by the identity key — for the nonce the client
+ * supplied. It does NOT do §10.1 check 1 (the TEE quote verifies to the vendor
+ * root) or the "hardware evidence binds `report_data`" half of check 4: parsing
+ * and checking a TDX/SEV-SNP quote is verifier-profile territory and needs
+ * primitives outside the Web Crypto API. Compose this with a quote verifier and
+ * the custody/provenance/channel checks (§10.1 checks 1, 7–10) for full Level 2.
+ */
+
+import {
+  computeWorkloadId,
+  computeKeysetDigest,
+  computeReportData,
+  keysetEndorsementPayload,
+} from './digest';
+import { verifySignature, fromHex } from './crypto';
+import type { AttestationReport, Check, ReportVerification } from './types';
+
+/** Options for {@link verifyReportBinding}. */
+export interface ReportBindingOptions {
+  /**
+   * Current time in Unix seconds for the freshness check (§10.1 check 6).
+   * Defaults to the local clock. Pass an explicit value for deterministic tests.
+   */
+  now?: number;
+  /**
+   * Whether the profile trusts the platform's declared validity window
+   * (`freshness.fetched_at`/`stale_after`, §5.1). Off by default — recency comes
+   * from the nonce binding, and `fetched_at`/`stale_after` need a securely
+   * synced TEE clock to mean anything.
+   */
+  trustPlatformClock?: boolean;
+}
+
+/**
+ * Verify the report's cryptographic bindings for `nonce` (§10.1 checks 2–6).
+ * `nonce` is the value the verifier supplied to `GET /v1/aci/attestation`, or
+ * `null`/`undefined` when it requested no nonce (§4.4).
+ *
+ * Returns a per-check result and the identity recomputed from the report's
+ * keyset; a failed check is `ok: false`, never thrown. Throws
+ * {@link UnsupportedAlgorithmError} when the identity key algorithm is outside
+ * Web Crypto scope (e.g. `ecdsa-secp256k1`).
+ */
+export async function verifyReportBinding(
+  report: AttestationReport,
+  nonce: string | null | undefined,
+  options: ReportBindingOptions = {},
+): Promise<ReportVerification> {
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  const checks: Check[] = [];
+
+  const keyset = report.attestation.workload_keyset;
+  const identityKey = keyset.workload_identity.public_key;
+
+  // Check 2: workload_id == digest of the identity public key in the report's keyset.
+  const workloadId = await computeWorkloadId(identityKey);
+  pushEqual(checks, 'workload_id', report.workload_id, workloadId);
+
+  // Check 3: workload_keyset_digest == digest of the report's keyset.
+  const workloadKeysetDigest = await computeKeysetDigest(keyset);
+  pushEqual(checks, 'workload_keyset_digest', report.workload_keyset_digest, workloadKeysetDigest);
+
+  // Check 4 (binding half): report_data == the §4.4 statement digest for this nonce.
+  // The hardware-evidence-binds-report_data half is out of scope (see file header).
+  const expectedReportData = await computeReportData(workloadId, workloadKeysetDigest, nonce);
+  pushEqual(checks, 'report_data', report.attestation.report_data, expectedReportData);
+
+  // Check 5: keyset endorsement verifies under the identity key, algo matching.
+  const endorsement = report.attestation.keyset_endorsement;
+  if (endorsement.algo !== identityKey.algo) {
+    checks.push({
+      name: 'keyset_endorsement',
+      ok: false,
+      detail: `endorsement.algo "${endorsement.algo}" != identity key algo "${identityKey.algo}"`,
+    });
+  } else {
+    const ok = await verifySignature(
+      identityKey.algo,
+      fromHex(identityKey.public_key),
+      fromHex(endorsement.value),
+      keysetEndorsementPayload(workloadKeysetDigest),
+      'keyset endorsement (§4.3)',
+    );
+    checks.push({
+      name: 'keyset_endorsement',
+      ok,
+      ...(ok ? {} : { detail: 'endorsement signature failed under identity key' }),
+    });
+  }
+
+  // Check 6: freshness. Nonce binding is check 4; here bound the epoch and,
+  // when trusted, the declared validity window.
+  const notAfter = keyset.keyset_epoch.not_after;
+  const epochOk = now < notAfter;
+  checks.push({
+    name: 'keyset_epoch.not_after',
+    ok: epochOk,
+    ...(epochOk ? {} : { detail: `now ${now} >= not_after ${notAfter}` }),
+  });
+  if (options.trustPlatformClock) {
+    const freshness = report.attestation.freshness;
+    const fetchedAt = freshness?.fetched_at;
+    const staleAfter = freshness?.stale_after;
+    const windowOk =
+      typeof fetchedAt === 'number' &&
+      typeof staleAfter === 'number' &&
+      fetchedAt <= now &&
+      now < staleAfter;
+    checks.push({
+      name: 'freshness_window',
+      ok: windowOk,
+      ...(windowOk ? {} : { detail: `now ${now} outside [${fetchedAt}, ${staleAfter})` }),
+    });
+  }
+
+  return { ok: checks.every((c) => c.ok), checks, workloadId, workloadKeysetDigest };
+}
+
+function pushEqual(checks: Check[], name: string, actual: string, expected: string): void {
+  const ok = actual === expected;
+  checks.push({ name, ok, ...(ok ? {} : { detail: `report ${actual} != recomputed ${expected}` }) });
+}

package/src/providers/phala/aci-verifier/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Wire shapes for the ACI artifacts this verifier reads, plus the result types
+ * it returns. These mirror spec/aci.md §4, §5, §8, §9; only the fields the
+ * verifier touches are typed precisely, with an index signature left open so
+ * unknown extension fields (§3.2) survive canonicalization untouched.
+ */
+
+import type { JcsValue } from './jcs';
+
+/** A public key object: `{ algo, public_key }` (§4.1). */
+export interface PublicKey {
+  algo: string;
+  public_key: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/** The workload identity (§4.2): the identity public key plus an optional subject. */
+export interface WorkloadIdentity {
+  public_key: PublicKey;
+  subject?: string | null;
+  [key: string]: JcsValue | undefined;
+}
+
+/** A receipt signing key entry (§4.2). */
+export interface ReceiptSigningKey {
+  key_id: string;
+  algo: string;
+  public_key: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/** The workload keyset (§4.2). Digested with JCS to yield `workload_keyset_digest`. */
+export interface WorkloadKeyset {
+  workload_identity: WorkloadIdentity;
+  keyset_epoch: { version: number; not_after: number; [key: string]: JcsValue | undefined };
+  receipt_signing_keys: ReceiptSigningKey[];
+  e2ee_public_keys?: JcsValue[];
+  tls_public_keys?: JcsValue[];
+  [key: string]: JcsValue | undefined;
+}
+
+/** A receipt signature block (§8.2). `value` is dropped for canonical signing bytes (§8.5). */
+export interface ReceiptSignature {
+  algo: string;
+  key_id: string;
+  value: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/** A single receipt event (§8.3). Only `seq`/`type` are fixed; other fields are type-specific. */
+export interface ReceiptEvent {
+  seq: number;
+  type: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/** An inference receipt (§8.2). */
+export interface Receipt {
+  api_version: string;
+  receipt_id: string;
+  workload_id: string;
+  workload_keyset_digest: string;
+  event_log: ReceiptEvent[];
+  signature: ReceiptSignature;
+  [key: string]: JcsValue | undefined;
+}
+
+/** The keyset endorsement / revocation signature block (§4.3, §5.1). */
+export interface Endorsement {
+  algo: string;
+  value: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/** The `attestation` object of a report (§5.1); only the fields Level 1 reads are typed. */
+export interface Attestation {
+  workload_keyset: WorkloadKeyset;
+  report_data: string;
+  keyset_endorsement: Endorsement;
+  freshness?: { fetched_at?: number; stale_after?: number; [key: string]: JcsValue | undefined };
+  [key: string]: JcsValue | undefined;
+}
+
+/** An attestation report (§5.1). */
+export interface AttestationReport {
+  api_version: string;
+  workload_id: string;
+  workload_keyset_digest: string;
+  attestation: Attestation;
+  [key: string]: JcsValue | undefined;
+}
+
+/** A verifier-provided evidence block on a session record (§9.2). */
+export interface SessionEvidence {
+  digest?: string | null;
+  data?: string;
+  [key: string]: JcsValue | undefined;
+}
+
+/**
+ * An attested session record (§9.2). The `session_id` is recomputed from the
+ * named fields; absent optional fields (`endpoint`, `identity`, `evidence.digest`)
+ * are restored as JSON `null` in the content-addressing material.
+ */
+export interface SessionRecord {
+  upstream_name: string;
+  endpoint?: string | null;
+  verifier_id: string;
+  identity?: JcsValue;
+  channel_binding: JcsValue[];
+  claims: JcsValue;
+  evidence?: SessionEvidence | null;
+  [key: string]: JcsValue | undefined;
+}
+
+/** Outcome of one named verification check. */
+export interface Check {
+  /** Stable machine-readable id, e.g. `signature`, `workload_id`. */
+  name: string;
+  ok: boolean;
+  /** Human-readable detail, present when the check fails. */
+  detail?: string;
+}
+
+/** Result of {@link verifyReceipt}: overall pass plus the individual §10.2 checks. */
+export interface ReceiptVerification {
+  ok: boolean;
+  checks: Check[];
+}
+
+/** Result of {@link verifyReportBinding}: overall pass, the §10.1 checks, and the derived identity. */
+export interface ReportVerification {
+  ok: boolean;
+  checks: Check[];
+  /** `workload_id` recomputed from the report's keyset (§4.1). */
+  workloadId: string;
+  /** `workload_keyset_digest` recomputed from the report's keyset (§4.2). */
+  workloadKeysetDigest: string;
+}

package/src/providers/phala/sse.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal SSE (Server-Sent Events) parsing for streamed chat completions.
+ * Yields the parsed JSON object from each `data:` line; skips `[DONE]` and
+ * unparseable/partial lines. Used by the streaming provider transports.
+ */
+
+/** Stream parse: iterate a ReadableStream of bytes, yielding parsed SSE data objects. */
+export async function* iterateSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<any> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  try {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split('\n');
+      buf = lines.pop() ?? '';
+      for (const obj of parseDataLines(lines)) yield obj;
+    }
+    // Flush any trailing buffered line.
+    if (buf.trim()) for (const obj of parseDataLines([buf])) yield obj;
+  } finally {
+    try { await reader.cancel(); } catch { /* ignore */ }
+  }
+}
+
+/** Sync parse: extract SSE data objects from a fully-buffered body (RN fallback). */
+export function parseSSEText(text: string): any[] {
+  return parseDataLines(text.split('\n'));
+}
+
+function parseDataLines(lines: string[]): any[] {
+  const out: any[] = [];
+  for (const line of lines) {
+    if (!line.startsWith('data:')) continue;
+    const t = line.slice(5).trim();
+    if (!t || t === '[DONE]') continue;
+    try { out.push(JSON.parse(t)); } catch { /* partial / non-JSON — skip */ }
+  }
+  return out;
+}

package/src/providers/phala/webcrypto-globals.d.ts

@@ -0,0 +1,17 @@
+// The vendored @dstack/aci-verifier (and our phalaSeal) use the WebCrypto DOM
+// global type names — CryptoKey, CryptoKeyPair, KeyUsage, BufferSource. This
+// project's tsconfig `lib` is ES2023 (no DOM), so rather than pull the entire DOM
+// lib into a Node CLI (which would add a pile of browser globals and ambiguate
+// things like `fetch`), surface just those four names as globals, aliased to
+// Node's own `webcrypto` types. Node ≥ 22 provides the runtime (X25519/HKDF/
+// AES-GCM/Ed25519 on globalThis.crypto.subtle) — see the VENDORED.md note.
+import type { webcrypto } from "node:crypto";
+
+declare global {
+  type CryptoKey = webcrypto.CryptoKey;
+  type CryptoKeyPair = webcrypto.CryptoKeyPair;
+  type KeyUsage = webcrypto.KeyUsage;
+  type BufferSource = ArrayBufferView | ArrayBuffer;
+}
+
+export {};