privateer-agent 0.12.18 → 0.12.20

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

@@ -1,116 +1,52 @@
 /**
- * The ACI digest and canonical-signing-bytes constructions (§4.1, §4.2, §4.3,
- * §4.4, §4.7, §8.5, §9.2). Each returns the exact bytes/strings the spec pins in
- * spec/test-vectors.md, so they double as the byte-for-byte reference.
+ * The ACI digest constructions (Appendix A, §3.1, §3.2). Artifacts the service builds
+ * are hashed as the exact served bytes; the attestation statement is the one
+ * report payload a verifier constructs itself, as a fixed byte template whose
+ * inputs are restricted so no JSON escaping is ever needed.
  */
 
 import { jcsBytes } from './jcs';
-import type { JcsValue } from './jcs';
 import { sha256Hex, sha256Prefixed } from './crypto';
-import type { PublicKey, WorkloadKeyset, Receipt, SessionRecord } from './types';
+import { AciFormatError } from './errors';
 
-/**
- * `workload_id` — the stable name of a workload (§4.1):
- * `"sha256:" || hex(sha256(JCS(public_key)))`.
- */
-export async function computeWorkloadId(publicKey: PublicKey): Promise<string> {
-  return sha256Prefixed(jcsBytes({ algo: publicKey.algo, public_key: publicKey.public_key }));
-}
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const NONCE_RE = /^[0-9a-f]{64}$/;
 
-/**
- * `workload_keyset_digest` (§4.2): `"sha256:" || hex(sha256(JCS(keyset)))`,
- * over the whole keyset object as given.
- */
-export async function computeKeysetDigest(keyset: WorkloadKeyset): Promise<string> {
-  return sha256Prefixed(jcsBytes(keyset as JcsValue));
+/** `workload_keyset_digest` (§3.1): sha256 over the keyset's JCS form. */
+export async function computeKeysetDigest(keyset: unknown): Promise<string> {
+  return sha256Prefixed(jcsBytes(keyset));
 }
 
 /**
- * The attestation statement (§4.4) whose JCS is hashed into `report_data`.
- * `nonce` is the request's decoded value, or JSON `null` when the query
- * parameter was omitted (never the string `"null"`); pass `undefined`/`null` for
- * the omitted case.
+ * The exact attestation-statement bytes (§3.2) for a keyset digest and the
+ * nonce the client sent — `null`/`undefined` when the query parameter was
+ * omitted, which puts the JSON literal `null` in the template. Inputs outside
+ * the spec-pinned formats throw {@link AciFormatError}.
  */
 export function attestationStatement(
-  workloadId: string,
-  workloadKeysetDigest: string,
+  keysetDigest: string,
   nonce: string | null | undefined,
-): JcsValue {
-  return {
-    purpose: 'aci.report_data.v1',
-    workload_id: workloadId,
-    workload_keyset_digest: workloadKeysetDigest,
-    nonce: nonce ?? null,
-  };
+): Uint8Array {
+  if (!DIGEST_RE.test(keysetDigest)) {
+    throw new AciFormatError(`keyset digest is not sha256:<64-hex>: "${keysetDigest}"`);
+  }
+  if (nonce != null && !NONCE_RE.test(nonce)) {
+    throw new AciFormatError('nonce must be exactly 64 lowercase hex characters (§3.2)');
+  }
+  const noncePart = nonce == null ? 'null' : `"${nonce}"`;
+  return new TextEncoder().encode(
+    `{"keyset_digest":"${keysetDigest}","nonce":${noncePart},"purpose":"aci.report_data.v1"}`,
+  );
 }
 
 /**
- * `report_data` (§4.4): `hex(sha256(JCS(attestation_statement)))` — the raw
- * 32-byte digest as lowercase hex, with no `sha256:` prefix (it names a bare
- * report-data slot, not an ACI digest string).
+ * `report_data` (§3.2): SHA-256 of the attestation statement, as bare lowercase
+ * hex (it fills a report-data slot, not an ACI digest string). The TEE places
+ * these 32 bytes zero-padded to 64 in the quote's report-data field.
  */
 export async function computeReportData(
-  workloadId: string,
-  workloadKeysetDigest: string,
+  keysetDigest: string,
   nonce: string | null | undefined,
 ): Promise<string> {
-  return sha256Hex(jcsBytes(attestationStatement(workloadId, workloadKeysetDigest, nonce)));
-}
-
-/** JCS bytes of the keyset endorsement payload (§4.3), signed by the identity key. */
-export function keysetEndorsementPayload(workloadKeysetDigest: string): Uint8Array {
-  return jcsBytes({
-    purpose: 'aci.keyset.endorsement.v1',
-    workload_keyset_digest: workloadKeysetDigest,
-  });
-}
-
-/** JCS bytes of the keyset revocation payload (§4.7), signed by the identity key. */
-export function keysetRevocationPayload(workloadKeysetDigest: string): Uint8Array {
-  return jcsBytes({
-    purpose: 'aci.keyset.revocation.v1',
-    workload_keyset_digest: workloadKeysetDigest,
-  });
-}
-
-/**
- * Canonical bytes a receipt signature covers (§8.5): the JCS of the whole
- * receipt with only `signature.value` removed (`algo` and `key_id`, and any
- * other signature fields, are retained). Unknown top-level fields and events are
- * preserved by canonicalizing the object as given (§3.2).
- */
-export function receiptSigningBytes(receipt: Receipt): Uint8Array {
-  const { value: _omitted, ...signatureWithoutValue } = receipt.signature;
-  const forSigning: JcsValue = {
-    ...(receipt as unknown as { [k: string]: JcsValue }),
-    signature: signatureWithoutValue as unknown as JcsValue,
-  };
-  return jcsBytes(forSigning);
-}
-
-/**
- * The content-addressing material for a session id (§9.2). The wire record omits
- * absent optional fields; the material restores `endpoint`, `identity`, and
- * `evidence.digest` as JSON `null`, and timestamps / raw evidence bytes are
- * excluded entirely.
- */
-export function sessionMaterial(record: SessionRecord): JcsValue {
-  return {
-    upstream_name: record.upstream_name,
-    endpoint: record.endpoint ?? null,
-    verifier_id: record.verifier_id,
-    identity: record.identity ?? null,
-    channel_binding: record.channel_binding,
-    claims: record.claims,
-    evidence_digest: record.evidence?.digest ?? null,
-  };
-}
-
-/**
- * `session_id` (§9.2): `"as_" || hex(sha256(JCS(material)))`. Recomputing this
- * from a fetched record and comparing it to the id the signed receipt committed
- * to is what makes the session tamper-evident — there is no session signature.
- */
-export async function computeSessionId(record: SessionRecord): Promise<string> {
-  return 'as_' + (await sha256Hex(jcsBytes(sessionMaterial(record))));
+  return sha256Hex(attestationStatement(keysetDigest, nonce));
 }

package/src/providers/phala/aci-verifier/e2ee-channel.ts

@@ -41,7 +41,9 @@ export async function openE2eeChannel(
   if (!verification.ok || verification.workloadKeysetDigest !== report.workload_keyset_digest) {
     throw new Error('openE2eeChannel: report is not verified — call verifyReportBinding and check .ok');
   }
-  const keys = (report.attestation.workload_keyset.e2ee_public_keys ?? []) as Array<{
+  // Read the keys off the ESTABLISHED keyset — the object whose JCS the
+  // verifier hashed to the digest the quote signed — not the report's copy.
+  const keys = (verification.keyset?.e2ee_public_keys ?? []) as Array<{
     algo: string;
     public_key: string;
   }>;

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

@@ -2,8 +2,7 @@
  * Errors raised by the verifier for conditions that are *not* ordinary
  * verification failures. A failed check (bad signature, wrong hash) is reported
  * as `ok: false` in the result objects — never thrown — so callers cannot ignore
- * it by forgetting a try/catch. These errors mean "the input is malformed or the
- * algorithm is outside this verifier's Level 1 / Web Crypto scope".
+ * it by forgetting a try/catch. These errors mean "the input is malformed".
  */
 
 /** Base class for every error this package throws. */
@@ -14,28 +13,10 @@ export class AciError extends Error {
   }
 }
 
-/** A JCS input violated the ACI subset (e.g. a non-integer number) or a hex/field value would not parse. */
+/** An input value would not parse (hex, base64, JSON) or violates a spec-pinned format. */
 export class AciFormatError extends AciError {
   constructor(message: string) {
     super(message);
     this.name = 'AciFormatError';
   }
 }
-
-/**
- * A signature or identity algorithm that ACI defines but this Web-Crypto-only
- * verifier cannot check. `ecdsa-secp256k1` is the expected case: the curve is
- * absent from the Web Crypto API, so verify it against the reference
- * implementation or a Level 2 verifier profile instead.
- */
-export class UnsupportedAlgorithmError extends AciError {
-  readonly algorithm: string;
-  constructor(algorithm: string, context: string) {
-    super(
-      `unsupported algorithm "${algorithm}" for ${context}: this verifier supports only ed25519 via the Web Crypto API. ` +
-        `secp256k1 is out of scope — verify it against the reference implementation or a Level 2 profile.`,
-    );
-    this.name = 'UnsupportedAlgorithmError';
-    this.algorithm = algorithm;
-  }
-}

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

@@ -1,43 +1,39 @@
 /**
- * @dstack/aci-verifier — a zero-dependency ACI Level 1 verifier.
+ * @phala/aci-verifier — a zero-dependency ACI verifier for the browser and node.
  *
- * Level 1 (receipt verification, §10.2) is fully implemented against an
- * established keyset. {@link verifyReportBinding} adds the cryptographic-binding
- * checks of Level 2 (§10.1 checks 2–6); the hardware quote, key custody, and
- * provenance checks (§10.1 checks 1, 7–10) are verifier-profile territory and
- * out of scope here. All crypto is Web Crypto (Ed25519, SHA-256); `ecdsa-secp256k1`
- * is unsupported (not in the Web Crypto API) and raises a clear error.
+ * Report binding (§9.1 checks 2–3) establishes the workload keyset: the served
+ * keyset canonicalizes to the digest the attestation statement hashes into
+ * `report_data`, which the hardware quote signs. Everything downstream — the
+ * E2EE key we seal to, receipt signing keys, TLS pins — is a member of that one
+ * quote-bound object, so nothing else needs its own signature. Receipt
+ * verification (§9.3) runs against an established keyset. All crypto here is
+ * Web Crypto (Ed25519, SHA-256/384); the quote itself is ../../phalaSeal.ts.
  */
 
-// Canonicalization (§3)
+// Canonicalization (Appendix A)
 export { canonicalize, jcsBytes } from './jcs';
 export type { JcsValue } from './jcs';
 
 // Crypto primitives (Web Crypto only)
 export {
   sha256,
+  sha384,
   sha256Hex,
   sha256Prefixed,
   verifyEd25519,
-  verifySignature,
   toHex,
   fromHex,
+  toBase64,
+  fromBase64,
 } from './crypto';
 
-// Digest & canonical-signing-bytes constructions (§4, §8.5, §9.2)
-export {
-  computeWorkloadId,
-  computeKeysetDigest,
-  attestationStatement,
-  computeReportData,
-  keysetEndorsementPayload,
-  keysetRevocationPayload,
-  receiptSigningBytes,
-  sessionMaterial,
-  computeSessionId,
-} from './digest';
+// Digest constructions (Appendix A, §3.1, §3.2)
+export { computeKeysetDigest, attestationStatement, computeReportData } from './digest';
+
+// Attested sessions: content addressing and evidence (§8, §9.3)
+export { computeSessionId, checkSessionApiVersion, checkSessionEvidence } from './session';
 
-// E2EE AAD builders (§7.3)
+// E2EE v2 AAD builders (spec/e2ee-v2.md §6)
 export {
   requestAad,
   requestAadString,
@@ -46,39 +42,37 @@ export {
 } from './e2ee';
 export type { AadCommon } from './e2ee';
 
-// E2EE channel to a verified workload — encrypt requests, decrypt replies (§7)
+// E2EE v2 channel to a verified workload — encrypt requests, decrypt replies
 export { openE2eeChannel } from './e2ee-channel';
 export type { E2eeChannel } from './e2ee-channel';
 
-// Level 1 receipt verification (§10.2)
+// Receipt verification (§9.3)
 export {
   verifyReceipt,
   findEvent,
   hashBody,
   checkRequestBodyHash,
-  checkResponseWireHash,
-  checkResponseCleartextHash,
+  checkResponseBodyHash,
 } from './receipt';
 
-// Level 2 report-binding checks (§10.1 checks 2–6, no hardware quote)
+// Report binding (§9.1 checks 2–3)
 export { verifyReportBinding } from './report';
 export type { ReportBindingOptions } from './report';
 
 // Errors
-export { AciError, AciFormatError, UnsupportedAlgorithmError } from './errors';
+export { AciError, AciFormatError } from './errors';
 
 // Wire & result types
 export type {
-  PublicKey,
-  WorkloadIdentity,
-  ReceiptSigningKey,
+  KeysetKey,
+  TlsKeyPin,
   WorkloadKeyset,
-  ReceiptSignature,
-  ReceiptEvent,
-  Receipt,
-  Endorsement,
+  SourceProvenance,
   Attestation,
   AttestationReport,
+  ReceiptEnvelope,
+  ReceiptEvent,
+  ReceiptPayload,
   SessionEvidence,
   SessionRecord,
   Check,

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

@@ -63,7 +63,12 @@ function serializeObject(obj: { [key: string]: JcsValue | undefined }): string {
   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));
+/**
+ * Canonicalize and encode to UTF-8 bytes — the form fed to SHA-256 and
+ * signatures. Takes `unknown` because the values that get canonicalized are
+ * parsed server JSON (a keyset, a receipt document); anything outside the ACI
+ * subset is rejected by {@link canonicalize} rather than mis-serialized.
+ */
+export function jcsBytes(value: unknown): Uint8Array {
+  return new TextEncoder().encode(canonicalize(value as JcsValue));
 }

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