privateer-agent 0.12.19 → 0.12.21

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

@@ -1,92 +1,110 @@
 /**
- * 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.
+ * Receipt verification (§7, §9.3). A receipt is one JSON document; its
+ * `signature` is Ed25519 over JCS(document minus `signature`) under a key
+ * the established keyset lists. "Established" means a keyset whose digest
+ * the caller verified — through {@link verifyReportBinding}, or published
+ * by a party the client trusts (§9.3).
  */
 
-import { receiptSigningBytes, computeWorkloadId, computeKeysetDigest } from './digest';
-import { verifySignature, sha256Prefixed } from './crypto';
-import { fromHex } from './crypto';
-import type { Receipt, ReceiptEvent, WorkloadKeyset, Check, ReceiptVerification } from './types';
+import { verifyEd25519, sha256Prefixed, fromHex } from './crypto';
+import { jcsBytes } from './jcs';
+import type {
+  Check,
+  ReceiptEnvelope,
+  ReceiptEvent,
+  ReceiptPayload,
+  ReceiptVerification,
+  WorkloadKeyset,
+} from './types';
 
 /**
- * Verify a receipt against an established keyset — §10.2 checks 1 and 2:
+ * §9.3 checks 1–2: the `signature` member verifies over JCS(document minus
+ * `signature`) under the keyset entry `key_id` names, and the document's
+ * `workload_keyset_digest` equals the established digest. Documents whose
+ * `api_version` is not `aci/1` are rejected (Appendix B).
  *
- * 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`).
+ * Returns per-check results plus the document for the body-hash checks; a
+ * failed check is `ok: false`, never thrown.
  */
 export async function verifyReceipt(
-  receipt: Receipt,
+  document: ReceiptEnvelope,
   keyset: WorkloadKeyset,
+  establishedDigest: string,
 ): 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);
+  // §9.3 check 1: Ed25519 over JCS(document minus `signature`).
+  const signingKeys = Array.isArray(keyset.receipt_signing_keys)
+    ? keyset.receipt_signing_keys
+    : [];
+  const keyEntry = signingKeys.find((k) => k.key_id === document.key_id);
   if (!keyEntry) {
     checks.push({
       name: 'signature',
       ok: false,
-      detail: `signature.key_id "${receipt.signature.key_id}" not in receipt_signing_keys`,
+      detail: `key_id "${document.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.
+  } else if (keyEntry.algo !== 'ed25519') {
+    // Appendix B: ed25519 is the only defined signature algorithm; reject others.
     checks.push({
       name: 'signature',
       ok: false,
-      detail: `signature.algo "${receipt.signature.algo}" != keyset entry algo "${keyEntry.algo}"`,
+      detail: `unsupported signature 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' }) });
+    const { signature, ...unsigned } = document;
+    let ok = false;
+    try {
+      ok = await verifyEd25519(
+        fromHex(keyEntry.public_key),
+        fromHex(signature),
+        jcsBytes(unsigned),
+      );
+    } catch {
+      // Malformed hex is a failed verification, not a thrown one.
+    }
+    checks.push({
+      name: 'signature',
+      ok,
+      ...(ok ? {} : { detail: `ed25519 verification failed under "${document.key_id}"` }),
+    });
   }
 
-  return { ok: checks.every((c) => c.ok), checks };
+  const payload = document as unknown as ReceiptPayload;
+  // Appendix B: reject receipts with a foreign api_version.
+  const versionOk = payload.api_version === 'aci/1';
+  checks.push({
+    name: 'api_version',
+    ok: versionOk,
+    ...(versionOk ? {} : { detail: `api_version "${payload.api_version}" is not "aci/1"` }),
+  });
+  // §9.3 check 2: the document binds back to the established keyset.
+  const ok = payload.workload_keyset_digest === establishedDigest;
+  checks.push({
+    name: 'workload_keyset_digest',
+    ok,
+    ...(ok
+      ? {}
+      : { detail: `document ${payload.workload_keyset_digest} != established ${establishedDigest}` }),
+  });
+
+  return {
+    ok: checks.every((c) => c.ok),
+    checks,
+    payload,
+  };
 }
 
-/** 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);
+/** Find the first event of a given type in a receipt payload's event log. */
+export function findEvent(payload: ReceiptPayload, type: string): ReceiptEvent | undefined {
+  // Server-supplied JSON: a malformed document is a failed lookup, not a throw.
+  if (!Array.isArray(payload.event_log)) return undefined;
+  return payload.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.
+ * `sha256:<hex>` of raw body bytes — the form ACI body hashes use (Appendix A). 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;
@@ -94,46 +112,36 @@ export async function hashBody(body: Uint8Array | string): Promise<string> {
 }
 
 /**
- * §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.
+ * §9.3 check 3: `request.received.body_hash` matches the plaintext wire body,
+ * or the compact post-decryption JSON body for E2EE (§7.4). Returns false when
+ * the event or its hash is absent.
  */
 export async function checkRequestBodyHash(
-  receipt: Receipt,
+  payload: ReceiptPayload,
   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;
+  return eventHashMatches(payload, 'request.received', requestBody);
 }
 
 /**
- * §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.
+ * §9.3 check 4: `response.returned.body_hash` matches the response bytes this
+ * client received off the wire — the in-order raw SSE bytes for a stream,
+ * including encrypted E2EE field values (§7.4). Returns false when the event
+ * or its hash is absent.
  */
-export async function checkResponseWireHash(
-  receipt: Receipt,
+export async function checkResponseBodyHash(
+  payload: ReceiptPayload,
   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;
+  return eventHashMatches(payload, 'response.returned', responseBody);
 }
 
-/**
- * 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,
+async function eventHashMatches(
+  payload: ReceiptPayload,
+  type: string,
+  body: Uint8Array | string,
 ): Promise<boolean> {
-  const event = findEvent(receipt, 'response.returned');
-  const expected = event?.cleartext_hash;
+  const expected = findEvent(payload, type)?.body_hash;
   if (typeof expected !== 'string') return false;
-  return (await hashBody(cleartextBody)) === expected;
+  return (await hashBody(body)) === expected;
 }

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

@@ -1,49 +1,41 @@
 /**
- * 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.
+ * Report binding checks a verifier can run with pure Web Crypto — §9.1 check 2
+ * (binding and freshness: keyset bytes → digest → statement → `report_data`)
+ * and check 3 (expiry), plus the aci/1 protocol gate. Check 1 (the hardware
+ * quote verifies to the vendor root and binds `report_data`) is done by
+ * ../../phalaSeal.ts with @phala/dcap-qvl; checks 5–6 (custody, channel) stay
+ * policy / caller territory.
+ *
+ * Local omission (see VENDORED.md): upstream's `verifyQuote` and
+ * `verifyComposeMeasurement` live in this file too. They are not carried here —
+ * phalaSeal.ts owns the quote (it also gates TCB status and pins measurements)
+ * and measurements.ts owns the event-log replay across all four RTMRs. Leaving
+ * them out keeps this tree dependency-free and @phala/dcap-qvl off the import
+ * path of every startup.
  */
 
-import {
-  computeWorkloadId,
-  computeKeysetDigest,
-  computeReportData,
-  keysetEndorsementPayload,
-} from './digest';
-import { verifySignature, fromHex } from './crypto';
-import type { AttestationReport, Check, ReportVerification } from './types';
+import { computeKeysetDigest, computeReportData } from './digest';
+import type { AttestationReport, Check, ReportVerification, WorkloadKeyset } 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.
+   * Current time in Unix seconds for the expiry check (§9.1 check 3).
+   * 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).
+ * Verify the report's cryptographic bindings for `nonce` — the value this
+ * client sent to `GET /v1/aci/attestation`, or `null`/`undefined` when it sent
+ * none (§3.2). One recomputation establishes that the keyset is exactly what
+ * the quote bound and that the quote postdates the challenge (§9.1 check 2).
  *
- * 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`).
+ * Returns per-check results plus the established keyset (digest, exact bytes,
+ * parsed form); a failed check on the served report is `ok: false`, never
+ * thrown. The one exception is the caller's own input: a nonce that is not
+ * 64 lowercase hex throws {@link AciFormatError} (§3.2).
  */
 export async function verifyReportBinding(
   report: AttestationReport,
@@ -53,71 +45,56 @@ export async function verifyReportBinding(
   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);
+  // Protocol gate (Appendix B): artifacts with another version are rejected.
+  const versionOk = report.api_version === 'aci/1';
+  checks.push({
+    name: 'api_version',
+    ok: versionOk,
+    ...(versionOk ? {} : { detail: `api_version "${report.api_version}" is not "aci/1"` }),
+  });
 
-  // 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);
+  const keysetValue = report.attestation.workload_keyset;
+  if (keysetValue === null || typeof keysetValue !== 'object' || Array.isArray(keysetValue)) {
+    const detail = 'workload_keyset is not a JSON object';
+    for (const name of ['workload_keyset_digest', 'report_data', 'not_after']) {
+      checks.push({ name, ok: false, detail });
+    }
+    return { ok: false, checks };
+  }
 
-  // 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);
+  // §9.1 check 2: recompute the whole chain from the served keyset object —
+  // canonicalize exactly what was parsed, unknown members included. The
+  // recomputed digest is authoritative (Appendix A) — the report's restated copy is
+  // checked for consistency but never feeds the statement.
+  const digest = await computeKeysetDigest(keysetValue);
+  pushEqual(checks, 'workload_keyset_digest', report.workload_keyset_digest, digest);
+  const expectedReportData = await computeReportData(digest, 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) {
+  const keyset = keysetValue as WorkloadKeyset;
+
+  // §9.1 check 3: now < not_after in the decoded keyset.
+  if (typeof keyset.not_after !== 'number') {
     checks.push({
-      name: 'keyset_endorsement',
+      name: 'not_after',
       ok: false,
-      detail: `endorsement.algo "${endorsement.algo}" != identity key algo "${identityKey.algo}"`,
+      detail: 'keyset has no numeric not_after',
     });
   } else {
-    const ok = await verifySignature(
-      identityKey.algo,
-      fromHex(identityKey.public_key),
-      fromHex(endorsement.value),
-      keysetEndorsementPayload(workloadKeysetDigest),
-      'keyset endorsement (§4.3)',
-    );
+    const ok = now < keyset.not_after;
     checks.push({
-      name: 'keyset_endorsement',
+      name: 'not_after',
       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})` }),
+      ...(ok ? {} : { detail: `now ${now} >= not_after ${keyset.not_after}` }),
     });
   }
 
-  return { ok: checks.every((c) => c.ok), checks, workloadId, workloadKeysetDigest };
+  return {
+    ok: checks.every((c) => c.ok),
+    checks,
+    workloadKeysetDigest: digest,
+    keyset,
+  };
 }
 
 function pushEqual(checks: Check[], name: string, actual: string, expected: string): void {

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

@@ -0,0 +1,40 @@
+/**
+ * Attested-session helpers (§8, §9.3). A session is content-addressed: its id
+ * is the SHA-256 of the exact served document bytes, and the signed receipt
+ * commits to that id — there is no session signature.
+ */
+
+import { sha256Hex, sha256Prefixed, fromBase64 } from './crypto';
+import { jcsBytes } from './jcs';
+import type { SessionRecord, SessionEvidence } from './types';
+
+/** `session_id` (§8): bare 64-hex sha256 of the JCS form of the parsed document. */
+export async function computeSessionId(record: unknown): Promise<string> {
+  return sha256Hex(jcsBytes(record));
+}
+
+/** Appendix B: reject session documents whose `api_version` is not `aci/1`. */
+export function checkSessionApiVersion(record: Pick<SessionRecord, 'api_version'>): boolean {
+  return record.api_version === 'aci/1';
+}
+
+/**
+ * §9.2(2): `evidence.data` decodes and hashes to `evidence.digest`.
+ * Returns false when the data URI is absent, malformed, or does not hash.
+ */
+export async function checkSessionEvidence(evidence: SessionEvidence): Promise<boolean> {
+  if (evidence == null || typeof evidence !== 'object') return false;
+  const { digest, data } = evidence;
+  if (typeof digest !== 'string' || typeof data !== 'string') return false;
+  const comma = data.indexOf(',');
+  if (!data.startsWith('data:') || comma < 0 || !data.slice(0, comma).endsWith(';base64')) {
+    return false;
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = fromBase64(data.slice(comma + 1));
+  } catch {
+    return false;
+  }
+  return (await sha256Prefixed(bytes)) === digest;
+}