privateer-agent 0.7.0 → 0.8.2

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 {};

package/src/providers/phalaSeal.ts

@@ -0,0 +1,200 @@
+// Phala (ACI E2EE) sealed transport for the account channel — the Node port of
+// treeview's client PhalaProvider.
+//
+// Where Tinfoil seals the whole body at the transport layer (EHBP via SecureClient),
+// Phala's Attested Confidential Inference encrypts the request's *content fields*
+// (x25519-aes-256-gcm-hkdf-sha256) to the enclave's attested X25519 key, sends the
+// `X-E2EE-*` headers alongside, and decrypts the response fields. The Privateer relay
+// (`${server}/api/sealed/phala`, treeview/server/routes/sealed.js) injects PHALA_API_KEY
+// and forwards ciphertext — it can't read prompts or responses.
+//
+// Crypto is the vendored @dstack/aci-verifier (./phala/aci-verifier), pure Web Crypto
+// (X25519/HKDF/AES-GCM/Ed25519). Node ≥ 22 provides all of it on globalThis.crypto —
+// no polyfills, unlike the RN app.
+//
+// Two-layer attestation, fail-secure:
+//   (1) verifyReportBinding — the report's crypto binding (keyset digest,
+//       report_data == statement(nonce), endorsement sig). Self-attesting alone.
+//   (2) verifyHardwareQuote — the hardware root: @phala/dcap-qvl verifies the TDX quote
+//       against Intel collateral and binds the quote's report_data to (1)'s statement
+//       digest. requireQuote defaults TRUE; PRIVATEER_PHALA_REQUIRE_QUOTE=0 drops it
+//       (local testing only — removes the hardware root of trust).
+
+import type { Report } from "@phala/dcap-qvl";
+import {
+  verifyReportBinding,
+  openE2eeChannel,
+  toHex,
+  fromHex,
+  type AttestationReport,
+  type ReportVerification,
+  type E2eeChannel,
+} from "./phala/aci-verifier/index.ts";
+import { serverBaseUrl } from "../auth/privateer.ts";
+
+const DEFAULT_ACCEPTABLE_TCB = ["UpToDate"];
+
+function relayBase(): string {
+  return `${serverBaseUrl().replace(/\/+$/, "")}/api/sealed/phala`;
+}
+
+// Hardware quote check on by default (fail-secure). Only "0"/"false" disables it.
+function requireQuote(): boolean {
+  const v = process.env.PRIVATEER_PHALA_REQUIRE_QUOTE;
+  return !(v === "0" || v === "false");
+}
+function pccsUrl(): string | undefined {
+  return process.env.PRIVATEER_PHALA_PCCS_URL || undefined;
+}
+function acceptableTcb(): Set<string> {
+  const v = process.env.PRIVATEER_PHALA_TCB;
+  const list = v ? v.split(",").map((s) => s.trim()).filter(Boolean) : DEFAULT_ACCEPTABLE_TCB;
+  return new Set(list);
+}
+
+// The 64-byte report_data from a verified TDX quote report (TD1.0/1.5 layouts).
+function extractQuoteReportData(report: Report): Uint8Array {
+  const td10 = report.asTd10?.();
+  if (td10?.reportData) return new Uint8Array(td10.reportData);
+  const td15 = report.asTd15?.();
+  if (td15?.base?.reportData) return new Uint8Array(td15.base.reportData);
+  const data = report.data as { reportData?: Uint8Array } | undefined;
+  if (data?.reportData) return new Uint8Array(data.reportData);
+  throw new Error("phala: verified quote report has no reportData");
+}
+
+interface VerifiedAttestation {
+  report: AttestationReport;
+  verification: ReportVerification;
+}
+
+// Attest once, cache the verified report; drop the memo on failure so a later call
+// re-attests rather than caching the error.
+let attestationPromise: Promise<VerifiedAttestation> | null = null;
+
+function attest(): Promise<VerifiedAttestation> {
+  if (!attestationPromise) {
+    attestationPromise = establishAttestation().catch((err) => {
+      attestationPromise = null;
+      throw err as Error;
+    });
+  }
+  return attestationPromise;
+}
+
+export function resetPhala(): void {
+  attestationPromise = null;
+}
+
+async function establishAttestation(): Promise<VerifiedAttestation> {
+  const nonce = toHex(globalThis.crypto.getRandomValues(new Uint8Array(32)));
+  // The relay proxies GET /attestation?nonce=… → the gateway's
+  // GET /v1/aci/attestation?nonce=… (public; no user content).
+  const res = await fetch(`${relayBase()}/attestation?nonce=${nonce}`, { method: "GET" });
+  if (!res.ok) throw new Error(`phala attestation HTTP ${res.status}`);
+  const report = (await res.json()) as AttestationReport;
+
+  const verification = await verifyReportBinding(report, nonce);
+  if (!verification.ok) {
+    const failed = verification.checks.filter((c) => !c.ok).map((c) => c.name).join(", ");
+    throw new Error(`phala attestation binding failed: ${failed}`);
+  }
+  await verifyHardwareQuote(report);
+  return { report, verification };
+}
+
+async function verifyHardwareQuote(report: AttestationReport): Promise<void> {
+  if (!requireQuote()) return;
+
+  const attestation = report.attestation as unknown as {
+    tee_type?: string;
+    report_data?: string;
+    evidence?: { quote?: string; quote_report_data?: string };
+  };
+  const teeType = String(attestation?.tee_type || "");
+  if (teeType !== "tdx") throw new Error(`phala: unsupported/absent tee_type "${teeType}" (only tdx is wired)`);
+  const quoteHex = attestation.evidence?.quote;
+  if (typeof quoteHex !== "string" || !quoteHex) throw new Error("phala: attestation evidence has no TDX quote");
+  const reportDataHex = String(attestation.report_data || "").toLowerCase();
+  if (!reportDataHex) throw new Error("phala: report has no report_data");
+
+  // Verify the quote against fetched Intel/Phala collateral (pure-JS dcap-qvl).
+  const { getCollateralAndVerify } = await import("@phala/dcap-qvl");
+  const verified = await getCollateralAndVerify(fromHex(quoteHex), pccsUrl());
+
+  // 1) Genuine hardware + acceptable TCB status.
+  const status = String(verified.status);
+  if (!acceptableTcb().has(status)) throw new Error(`phala: TDX quote TCB status not accepted: "${status}"`);
+
+  // 2) The genuine quote committed to our attested statement digest.
+  const quoteReportData = extractQuoteReportData(verified.report);
+  if (toHex(quoteReportData.slice(0, 32)) !== reportDataHex) {
+    throw new Error("phala: TDX quote report_data does not bind the attested report_data");
+  }
+
+  // 3) Consistency: the report's declared quote_report_data matches the real quote.
+  const declared = attestation.evidence?.quote_report_data;
+  if (typeof declared === "string" && declared && toHex(quoteReportData) !== declared.toLowerCase()) {
+    throw new Error("phala: evidence.quote_report_data does not match the verified quote");
+  }
+}
+
+// Posture signal: does the attested keyset verify (crypto binding + hardware quote)?
+// A green result is a quote WE checked, bound to the E2EE key we seal to.
+export async function attestPhala(): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await attest();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: (e as Error).message };
+  }
+}
+
+export interface PhalaExchange {
+  res: Response;
+  channel: E2eeChannel;
+  streaming: boolean;
+}
+
+// Run one sealed request for Pi: attest, open a fresh per-call E2EE channel (the
+// channel's request state is single-shot → not safe to share across concurrent
+// calls), seal the request fields, and POST to the relay with the X-E2EE-* headers +
+// the cleartext X-Sealed-Model (relay billing) + Pi's account bearer. Returns the
+// upstream response and the channel so the caller can decrypt it.
+export async function phalaSealedFetch(
+  rawBody: string,
+  authHeader: string | undefined,
+  signal?: AbortSignal,
+): Promise<PhalaExchange> {
+  const { report, verification } = await attest();
+  const channel = await openE2eeChannel(report, verification);
+
+  let request: Record<string, unknown>;
+  try {
+    request = JSON.parse(rawBody) as Record<string, unknown>;
+  } catch {
+    throw new Error("phala: request body is not JSON");
+  }
+  const fullModel = typeof request.model === "string" ? request.model : "unknown";
+  const streaming = request.stream !== false;
+  // Bare model id for the enclave (the `phala/` prefix is app-side only); keep the
+  // full id on the cleartext X-Sealed-Model billing header.
+  request.model = fullModel.replace(/^phala\//, "");
+  request.stream = streaming;
+
+  const { body, headers: e2ee } = await channel.seal(request);
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Sealed-Model": fullModel,
+    ...e2ee,
+  };
+  if (authHeader) headers.Authorization = authHeader;
+
+  const res = await fetch(`${relayBase()}/v1/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal,
+  });
+  return { res, channel, streaming };
+}