privateer-agent 0.7.0 → 0.8.0

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

@@ -0,0 +1,95 @@
+/**
+ * Cryptographic primitives, all via the Web Crypto API (`globalThis.crypto`) so
+ * the same code runs in browsers and in Node 20+ with no third-party deps.
+ * Only SHA-256 and Ed25519 verification are needed for Level 1.
+ */
+
+import { AciFormatError, UnsupportedAlgorithmError } from './errors';
+
+const subtle = globalThis.crypto.subtle;
+
+/** Lowercase-hex encode bytes. */
+export function toHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+/** Decode hex (optionally `0x`-prefixed) to bytes. */
+export function fromHex(hex: string): Uint8Array {
+  const h = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+  if (h.length % 2 !== 0) {
+    throw new AciFormatError(`hex string has odd length: ${hex.length} chars`);
+  }
+  const out = new Uint8Array(h.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = Number.parseInt(h.substr(i * 2, 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new AciFormatError(`invalid hex at offset ${i * 2}: "${h.substr(i * 2, 2)}"`);
+    }
+    out[i] = byte;
+  }
+  return out;
+}
+
+/** SHA-256 of the given bytes. */
+export async function sha256(bytes: Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await subtle.digest('SHA-256', bytes as BufferSource));
+}
+
+/** Lowercase-hex SHA-256 of the given bytes. */
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  return toHex(await sha256(bytes));
+}
+
+/**
+ * `sha256:<lowercase-hex>` digest string of the given bytes — the ACI digest
+ * form (§3) used for `workload_id`, keyset digests, and body hashes.
+ */
+export async function sha256Prefixed(bytes: Uint8Array): Promise<string> {
+  return 'sha256:' + (await sha256Hex(bytes));
+}
+
+/**
+ * Verify an Ed25519 signature (RFC 8032, §4.3/§8.5) over `message`.
+ * `publicKeyRaw` is the 32-byte raw key; `signature` the 64-byte value.
+ * Returns false on a bad signature or malformed key — never throws for those.
+ */
+export async function verifyEd25519(
+  publicKeyRaw: Uint8Array,
+  signature: Uint8Array,
+  message: Uint8Array,
+): Promise<boolean> {
+  let key: CryptoKey;
+  try {
+    key = await subtle.importKey('raw', publicKeyRaw as BufferSource, { name: 'Ed25519' }, false, [
+      'verify',
+    ]);
+  } catch {
+    // A key that will not import cannot verify anything.
+    return false;
+  }
+  try {
+    return await subtle.verify({ name: 'Ed25519' }, key, signature as BufferSource, message as BufferSource);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify a signature by ACI signature `algo`, dispatching on the algorithm the
+ * attested keyset entry declares. Only `ed25519` is verifiable here; every other
+ * algorithm (including `ecdsa-secp256k1`) raises {@link UnsupportedAlgorithmError}.
+ */
+export async function verifySignature(
+  algo: string,
+  publicKeyRaw: Uint8Array,
+  signature: Uint8Array,
+  message: Uint8Array,
+  context: string,
+): Promise<boolean> {
+  if (algo === 'ed25519') {
+    return verifyEd25519(publicKeyRaw, signature, message);
+  }
+  throw new UnsupportedAlgorithmError(algo, context);
+}

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

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+
+import { jcsBytes } from './jcs';
+import type { JcsValue } from './jcs';
+import { sha256Hex, sha256Prefixed } from './crypto';
+import type { PublicKey, WorkloadKeyset, Receipt, SessionRecord } from './types';
+
+/**
+ * `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 }));
+}
+
+/**
+ * `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));
+}
+
+/**
+ * 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.
+ */
+export function attestationStatement(
+  workloadId: string,
+  workloadKeysetDigest: string,
+  nonce: string | null | undefined,
+): JcsValue {
+  return {
+    purpose: 'aci.report_data.v1',
+    workload_id: workloadId,
+    workload_keyset_digest: workloadKeysetDigest,
+    nonce: nonce ?? null,
+  };
+}
+
+/**
+ * `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).
+ */
+export async function computeReportData(
+  workloadId: string,
+  workloadKeysetDigest: 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))));
+}

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

@@ -0,0 +1,242 @@
+/**
+ * E2EE channel to a *verified* workload (§7). `openE2eeChannel` refuses unless
+ * the report passed {@link verifyReportBinding} — you cannot encrypt to a key
+ * that is not in a verified, endorsed keyset. `seal` encrypts the request's
+ * content fields to the attested X25519 key and returns the `X-E2EE-*` headers;
+ * `open` decrypts a buffered response and `openChunk` decrypts one streamed SSE
+ * chunk. All crypto is Web Crypto (X25519, HKDF, AES-GCM) — no dependencies,
+ * runs in the browser. secp256k1 is a separate extension (not in Web Crypto).
+ */
+
+import { requestAad, responseAad } from './e2ee';
+import { toHex, fromHex } from './crypto';
+import type { AttestationReport, ReportVerification } from './types';
+
+const ALGO = 'x25519-aes-256-gcm-hkdf-sha256';
+const subtle = globalThis.crypto.subtle;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const HKDF_INFO = enc.encode('aci.e2ee.v2.x25519');
+
+type Json = Record<string, unknown>;
+
+/** An encrypted channel bound to one verified workload. */
+export interface E2eeChannel {
+  /** Encrypt a request's content fields; returns the body and `X-E2EE-*` headers. */
+  seal(request: Json): Promise<{ body: Json; headers: Record<string, string> }>;
+  /** Decrypt a buffered response produced for the most recent `seal`. */
+  open(response: Json): Promise<Json>;
+  /** Decrypt one streamed SSE chunk (a `chat.completion.chunk` / completion chunk). */
+  openChunk(chunk: Json): Promise<Json>;
+}
+
+/**
+ * Open an E2EE channel to the workload `report` describes, once `verification`
+ * (from {@link verifyReportBinding} for that report) has passed.
+ */
+export async function openE2eeChannel(
+  report: AttestationReport,
+  verification: ReportVerification,
+): Promise<E2eeChannel> {
+  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<{
+    algo: string;
+    public_key: string;
+  }>;
+  const service = keys.find((k) => k?.algo === ALGO);
+  if (!service) throw new Error(`openE2eeChannel: no attested ${ALGO} key in the keyset`);
+  const serviceRaw = fromHex(service.public_key);
+
+  // Static client key: responses are encrypted to it, and we decrypt with its private half.
+  const client = (await subtle.generateKey({ name: 'X25519' }, true, ['deriveBits'])) as CryptoKeyPair;
+  const clientPubHex = toHex(new Uint8Array(await subtle.exportKey('raw', client.publicKey)));
+
+  let sent: { model: string; nonce: string; ts: number } | undefined;
+
+  return {
+    async seal(request) {
+      const model = request.model;
+      if (typeof model !== 'string') throw new Error('seal: request.model must be a string');
+      const nonce = toHex(crypto.getRandomValues(new Uint8Array(32)));
+      const ts = Math.floor(Date.now() / 1000);
+      sent = { model, nonce, ts };
+      const encField = (text: string, field: string) =>
+        sealField(serviceRaw, enc.encode(text), requestAad({ algo: ALGO, model, field, nonce, ts }));
+
+      const body: Json = { ...request };
+      if (Array.isArray(request.messages)) {
+        // Whole-content encryption (§7.2) — the universal form for any modality.
+        body.messages = await Promise.all(
+          (request.messages as Json[]).map(async (m, i) => {
+            if (m?.content == null) return m;
+            const text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+            return { ...m, content: await encField(text, `messages.${i}.content`) };
+          }),
+        );
+      } else if (request.prompt !== undefined) {
+        body.prompt = await sealStringOrArray(request.prompt, 'prompt', encField); // completions
+      } else if (request.input !== undefined) {
+        body.input = await sealStringOrArray(request.input, 'input', encField); // embeddings
+      }
+      return {
+        body,
+        headers: {
+          'X-E2EE-Version': '2',
+          'X-Client-Pub-Key': clientPubHex,
+          'X-Model-Pub-Key': service.public_key,
+          'X-E2EE-Nonce': nonce,
+          'X-E2EE-Timestamp': String(ts),
+        },
+      };
+    },
+
+    async open(response) {
+      const decField = responseDecryptor(client.privateKey, sent, textFrom(response.id));
+      const body: Json = { ...response };
+      if (Array.isArray(response.choices)) {
+        body.choices = await Promise.all(
+          (response.choices as Json[]).map(async (c, pos) => {
+            const i = indexOf(c, pos);
+            const out: Json = { ...c };
+            if (out.message && typeof out.message === 'object') {
+              const m: Json = { ...(out.message as Json) };
+              await openStr(m, 'content', `choices.${i}.message.content`, decField);
+              await openStr(m, 'reasoning_content', `choices.${i}.message.reasoning_content`, decField);
+              if (m.audio && typeof m.audio === 'object') {
+                const a: Json = { ...(m.audio as Json) };
+                await openStr(a, 'data', `choices.${i}.message.audio.data`, decField);
+                m.audio = a;
+              }
+              out.message = m;
+            } else {
+              await openStr(out, 'text', `choices.${i}.text`, decField); // completions
+            }
+            return out;
+          }),
+        );
+      }
+      if (Array.isArray(response.data)) {
+        // Embeddings: the value is serialized compactly then encrypted (§7.2).
+        body.data = await Promise.all(
+          (response.data as Json[]).map(async (d, pos) => {
+            const i = indexOf(d, pos);
+            const out: Json = { ...d };
+            if (typeof out.embedding === 'string') {
+              out.embedding = JSON.parse(await decField(out.embedding, `data.${i}.embedding`));
+            }
+            return out;
+          }),
+        );
+      }
+      return body;
+    },
+
+    async openChunk(chunk) {
+      const decField = responseDecryptor(client.privateKey, sent, textFrom(chunk.id));
+      const body: Json = { ...chunk };
+      if (Array.isArray(chunk.choices)) {
+        body.choices = await Promise.all(
+          (chunk.choices as Json[]).map(async (c, pos) => {
+            const i = indexOf(c, pos);
+            const out: Json = { ...c };
+            if (out.delta && typeof out.delta === 'object') {
+              const d: Json = { ...(out.delta as Json) };
+              await openStr(d, 'content', `choices.${i}.delta.content`, decField);
+              await openStr(d, 'reasoning_content', `choices.${i}.delta.reasoning_content`, decField);
+              out.delta = d;
+            } else {
+              await openStr(out, 'text', `choices.${i}.text`, decField); // completions stream
+            }
+            return out;
+          }),
+        );
+      }
+      return body;
+    },
+  };
+}
+
+/** A field decryptor bound to the request context (§7.3) and the response `id`. */
+function responseDecryptor(
+  clientPriv: CryptoKey,
+  sent: { model: string; nonce: string; ts: number } | undefined,
+  id: string,
+): (blobHex: string, field: string) => Promise<string> {
+  if (!sent) throw new Error('open: call seal first');
+  const { model, nonce, ts } = sent;
+  return async (blobHex, field) =>
+    dec.decode(await openField(clientPriv, blobHex, responseAad({ algo: ALGO, model, id, field, nonce, ts })));
+}
+
+/** `choices`/`data` index is the entry's `index` member, else its array position (§7.2). */
+function indexOf(entry: Json, position: number): number {
+  return typeof entry.index === 'number' ? entry.index : position;
+}
+
+function textFrom(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+/** Decrypt string member `key` of `obj` at `field`, in place; leave non-strings untouched. */
+async function openStr(
+  obj: Json,
+  key: string,
+  field: string,
+  decField: (blobHex: string, field: string) => Promise<string>,
+): Promise<void> {
+  if (typeof obj[key] === 'string') obj[key] = await decField(obj[key] as string, field);
+}
+
+/** Encrypt a string, or each string element of an array at `name.{i}` (§7.2). */
+async function sealStringOrArray(
+  value: unknown,
+  name: string,
+  encField: (text: string, field: string) => Promise<string>,
+): Promise<unknown> {
+  if (typeof value === 'string') return encField(value, name);
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((v, i) => (typeof v === 'string' ? encField(v, `${name}.${i}`) : v)));
+  }
+  return value;
+}
+
+// `Uint8Array` → `BufferSource` (Web Crypto typings friction; see crypto.ts).
+const bs = (u: Uint8Array): BufferSource => u as BufferSource;
+
+/** Derive the AES-256-GCM key from a raw X25519 shared secret (spec §7.1). */
+async function aesKey(shared: Uint8Array, usage: KeyUsage): Promise<CryptoKey> {
+  const hk = await subtle.importKey('raw', bs(shared), 'HKDF', false, ['deriveKey']);
+  return subtle.deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: bs(new Uint8Array(0)), info: bs(HKDF_INFO) },
+    hk,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    [usage],
+  );
+}
+
+/** Encrypt one field to `serviceRaw` with a fresh ephemeral key → wire hex. */
+async function sealField(serviceRaw: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<string> {
+  const eph = (await subtle.generateKey({ name: 'X25519' }, true, ['deriveBits'])) as CryptoKeyPair;
+  const ephPub = new Uint8Array(await subtle.exportKey('raw', eph.publicKey));
+  const service = await subtle.importKey('raw', bs(serviceRaw), { name: 'X25519' }, false, []);
+  const shared = new Uint8Array(await subtle.deriveBits({ name: 'X25519', public: service }, eph.privateKey, 256));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv: bs(iv), additionalData: bs(aad) }, await aesKey(shared, 'encrypt'), bs(plaintext)));
+  const blob = new Uint8Array(ephPub.length + iv.length + ct.length);
+  blob.set(ephPub);
+  blob.set(iv, ephPub.length);
+  blob.set(ct, ephPub.length + iv.length);
+  return toHex(blob);
+}
+
+/** Decrypt one field addressed to the client static key. */
+async function openField(clientPriv: CryptoKey, blobHex: string, aad: Uint8Array): Promise<Uint8Array> {
+  const blob = fromHex(blobHex);
+  const ephPub = await subtle.importKey('raw', bs(blob.slice(0, 32)), { name: 'X25519' }, false, []);
+  const shared = new Uint8Array(await subtle.deriveBits({ name: 'X25519', public: ephPub }, clientPriv, 256));
+  const pt = await subtle.decrypt({ name: 'AES-GCM', iv: bs(blob.slice(32, 44)), additionalData: bs(aad) }, await aesKey(shared, 'decrypt'), bs(blob.slice(44)));
+  return new Uint8Array(pt);
+}

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

@@ -0,0 +1,73 @@
+/**
+ * E2EE associated-data (AAD) builders (§7.3). The AAD binds each ciphertext to
+ * its field path and request context; it is the JCS of a purpose-tagged object,
+ * so no component needs bespoke escaping. Provided here because clients that
+ * encrypt fields need the exact bytes — the verifier itself does not decrypt.
+ * The X25519 and secp256k1 suites share these builders; `algo` is just a field.
+ */
+
+import { canonicalize, jcsBytes } from './jcs';
+
+/** Inputs shared by request and response AAD (§7.3). */
+export interface AadCommon {
+  /** `algo` of the selected service E2EE key. */
+  algo: string;
+  /** The request's top-level `model`, byte-exact. */
+  model: string;
+  /** The encrypted location's field path, e.g. `messages.0.content` (§7.2). */
+  field: string;
+  /** The request's `X-E2EE-Nonce` (string). */
+  nonce: string;
+  /** The request's `X-E2EE-Timestamp` (Unix seconds, integer). */
+  ts: number;
+}
+
+/** Request AAD (§7.3), tag `aci.e2ee.request.v2`. Returns the canonical JCS string. */
+export function requestAadString(params: AadCommon): string {
+  return canonicalize({
+    purpose: 'aci.e2ee.request.v2',
+    algo: params.algo,
+    model: params.model,
+    field: params.field,
+    nonce: params.nonce,
+    ts: params.ts,
+  });
+}
+
+/** Request AAD as UTF-8 bytes — the value passed to AES-GCM. */
+export function requestAad(params: AadCommon): Uint8Array {
+  return jcsBytes({
+    purpose: 'aci.e2ee.request.v2',
+    algo: params.algo,
+    model: params.model,
+    field: params.field,
+    nonce: params.nonce,
+    ts: params.ts,
+  });
+}
+
+/** Response AAD (§7.3), tag `aci.e2ee.response.v2`. Adds the response `id` (`""` when none). */
+export function responseAadString(params: AadCommon & { id: string }): string {
+  return canonicalize({
+    purpose: 'aci.e2ee.response.v2',
+    algo: params.algo,
+    model: params.model,
+    id: params.id,
+    field: params.field,
+    nonce: params.nonce,
+    ts: params.ts,
+  });
+}
+
+/** Response AAD as UTF-8 bytes — the value passed to AES-GCM. */
+export function responseAad(params: AadCommon & { id: string }): Uint8Array {
+  return jcsBytes({
+    purpose: 'aci.e2ee.response.v2',
+    algo: params.algo,
+    model: params.model,
+    id: params.id,
+    field: params.field,
+    nonce: params.nonce,
+    ts: params.ts,
+  });
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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".
+ */
+
+/** Base class for every error this package throws. */
+export class AciError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AciError';
+  }
+}
+
+/** A JCS input violated the ACI subset (e.g. a non-integer number) or a hex/field value would not parse. */
+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

@@ -0,0 +1,87 @@
+/**
+ * @dstack/aci-verifier — a zero-dependency ACI Level 1 verifier.
+ *
+ * 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.
+ */
+
+// Canonicalization (§3)
+export { canonicalize, jcsBytes } from './jcs';
+export type { JcsValue } from './jcs';
+
+// Crypto primitives (Web Crypto only)
+export {
+  sha256,
+  sha256Hex,
+  sha256Prefixed,
+  verifyEd25519,
+  verifySignature,
+  toHex,
+  fromHex,
+} from './crypto';
+
+// Digest & canonical-signing-bytes constructions (§4, §8.5, §9.2)
+export {
+  computeWorkloadId,
+  computeKeysetDigest,
+  attestationStatement,
+  computeReportData,
+  keysetEndorsementPayload,
+  keysetRevocationPayload,
+  receiptSigningBytes,
+  sessionMaterial,
+  computeSessionId,
+} from './digest';
+
+// E2EE AAD builders (§7.3)
+export {
+  requestAad,
+  requestAadString,
+  responseAad,
+  responseAadString,
+} from './e2ee';
+export type { AadCommon } from './e2ee';
+
+// E2EE channel to a verified workload — encrypt requests, decrypt replies (§7)
+export { openE2eeChannel } from './e2ee-channel';
+export type { E2eeChannel } from './e2ee-channel';
+
+// Level 1 receipt verification (§10.2)
+export {
+  verifyReceipt,
+  findEvent,
+  hashBody,
+  checkRequestBodyHash,
+  checkResponseWireHash,
+  checkResponseCleartextHash,
+} from './receipt';
+
+// Level 2 report-binding checks (§10.1 checks 2–6, no hardware quote)
+export { verifyReportBinding } from './report';
+export type { ReportBindingOptions } from './report';
+
+// Errors
+export { AciError, AciFormatError, UnsupportedAlgorithmError } from './errors';
+
+// Wire & result types
+export type {
+  PublicKey,
+  WorkloadIdentity,
+  ReceiptSigningKey,
+  WorkloadKeyset,
+  ReceiptSignature,
+  ReceiptEvent,
+  Receipt,
+  Endorsement,
+  Attestation,
+  AttestationReport,
+  SessionEvidence,
+  SessionRecord,
+  Check,
+  ReceiptVerification,
+  ReportVerification,
+} from './types';