privateer-agent 0.9.3 → 0.11.0

package/src/nostr/keys.ts

@@ -0,0 +1,172 @@
+/**
+ * The agent's Nostr identity.
+ *
+ * A Nostr secret key is not a bot token. It is a PERMANENT identity: it cannot be
+ * rotated without becoming a different participant, everything it ever signed stays
+ * attributable to it, and there is no issuer to revoke it. So it gets the same
+ * treatment as the terminal identity key — minted locally, written 0600, and never
+ * sent anywhere — rather than living in plaintext config.json beside the revocable
+ * platform bot tokens.
+ *
+ * DEFAULT PATH: the agent generates its own keypair and reports the npub, which the
+ * user pastes into their Buzz workspace so an Owner can add it as a Bot member. The
+ * secret never crosses a wire, not even the sealed app→terminal channel.
+ *
+ * IMPORT PATH: a user who already has a Buzz identity can send an nsec through the
+ * app's sealed-secret flow; importBuzzKey() moves it into the 0600 file so it stops
+ * living in config.json.
+ *
+ * Construction mirrors crypto/terminalKey.ts deliberately, including the 0600
+ * TOCTOU-avoiding write and the process-lifetime cache.
+ */
+
+import { readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { schnorr } from "@noble/curves/secp256k1";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils";
+import { globalDir } from "../config/paths.ts";
+import { npubEncode, npubDecode, nsecEncode, nsecDecode } from "./bech32.ts";
+
+interface BuzzKeyFile {
+  v: 1;
+  secretKey: string; // base64, 32 raw bytes — never leaves this machine
+}
+
+export interface BuzzIdentity {
+  secretHex: string;
+  pubkeyHex: string;
+  npub: string;
+}
+
+function keyPath(): string {
+  return join(globalDir(), "buzz-key.json");
+}
+
+let cached: BuzzIdentity | undefined;
+
+// ── pure ────────────────────────────────────────────────────────────────────────
+
+/** A fresh 32-byte secp256k1 secret key. */
+export function generateSecretKey(): Uint8Array {
+  return schnorr.utils.randomSecretKey();
+}
+
+/** The 32-byte x-only public key for a secret, as lowercase hex — a Nostr pubkey. */
+export function publicKeyHex(secret: Uint8Array | string): string {
+  return bytesToHex(schnorr.getPublicKey(typeof secret === "string" ? hexToBytes(secret) : secret));
+}
+
+/**
+ * Normalize a configured identity to lowercase hex.
+ *
+ * Allowlists are written by humans, who will paste whichever form Buzz showed them —
+ * so accept both npub and raw hex and store one canonical form. Returns undefined
+ * for anything that isn't a valid 32-byte key, so a typo'd entry fails closed
+ * (dropped from the allowlist) rather than silently matching nothing forever.
+ */
+export function toHexPubkey(npubOrHex: string): string | undefined {
+  const s = npubOrHex.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return s.toLowerCase();
+  if (s.startsWith("npub1")) {
+    try {
+      return bytesToHex(npubDecode(s));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Accept either an nsec or raw hex secret; throws on anything else. */
+export function secretFromNsec(nsecOrHex: string): Uint8Array {
+  const s = nsecOrHex.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return hexToBytes(s.toLowerCase());
+  if (s.startsWith("nsec1")) return nsecDecode(s);
+  throw new Error("expected an nsec1… key or 64 hex characters");
+}
+
+function identityFrom(secret: Uint8Array): BuzzIdentity {
+  const pubkeyHex = publicKeyHex(secret);
+  return { secretHex: bytesToHex(secret), pubkeyHex, npub: npubEncode(hexToBytes(pubkeyHex)) };
+}
+
+// ── persisted ───────────────────────────────────────────────────────────────────
+
+function persist(secret: Uint8Array): BuzzIdentity {
+  const file: BuzzKeyFile = { v: 1, secretKey: Buffer.from(secret).toString("base64") };
+  // 0600 from creation — see terminalKey.ts for why `mode` plus a follow-up chmod.
+  writeFileSync(keyPath(), JSON.stringify(file), { mode: 0o600 });
+  try {
+    chmodSync(keyPath(), 0o600);
+  } catch {
+    /* best effort — e.g. non-POSIX FS */
+  }
+  cached = identityFrom(secret);
+  return cached;
+}
+
+/** Load the persisted identity, minting and persisting one on first use. */
+export function loadOrCreateBuzzKey(): BuzzIdentity {
+  if (cached) return cached;
+  try {
+    const parsed = JSON.parse(readFileSync(keyPath(), "utf8")) as BuzzKeyFile;
+    if (parsed?.v === 1 && parsed.secretKey) {
+      const buf = Buffer.from(parsed.secretKey, "base64");
+      if (buf.length === 32) {
+        cached = identityFrom(new Uint8Array(buf));
+        return cached;
+      }
+    }
+  } catch {
+    /* missing or malformed → mint a fresh keypair below */
+  }
+  return persist(generateSecretKey());
+}
+
+/**
+ * Adopt an existing identity, replacing any current one.
+ *
+ * Called when a user supplies an nsec through the app: the value arrives sealed,
+ * lands here, and the caller then deletes it from config.json so the only copy on
+ * disk is the 0600 file.
+ */
+export function importBuzzKey(nsecOrHex: string): BuzzIdentity {
+  return persist(secretFromNsec(nsecOrHex));
+}
+
+/**
+ * Every textual form of the persisted secret, for the outbound redactor.
+ *
+ * The agent can read its own key file — it's a file on the machine it operates —
+ * so without this it could quote its permanent identity into a public channel.
+ * Both encodings are returned because either could plausibly appear in output.
+ * Non-minting: no key file means nothing to redact.
+ */
+export function buzzRedactionSecrets(): string[] {
+  const secretHex = cached?.secretHex ?? readPersistedSecretHex();
+  if (!secretHex) return [];
+  return [secretHex, nsecEncode(hexToBytes(secretHex))];
+}
+
+function readPersistedSecretHex(): string | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(keyPath(), "utf8")) as BuzzKeyFile;
+    const buf = Buffer.from(parsed?.secretKey ?? "", "base64");
+    if (parsed?.v === 1 && buf.length === 32) return bytesToHex(new Uint8Array(buf));
+  } catch {
+    /* not configured yet */
+  }
+  return undefined;
+}
+
+/**
+ * Read the persisted npub WITHOUT minting one.
+ *
+ * Side-effect-free by design: the app lists every platform, configured or not, and
+ * merely rendering an empty Buzz card must not conjure a permanent identity.
+ */
+export function peekBuzzNpub(): string | undefined {
+  if (cached) return cached.npub;
+  const secretHex = readPersistedSecretHex();
+  return secretHex ? identityFrom(hexToBytes(secretHex)).npub : undefined;
+}

package/src/nostr/tags.ts

@@ -0,0 +1,60 @@
+// NIP-10 threading and NIP-27 mention helpers — reading meaning out of an event's
+// positional tag arrays, and building the tags for a reply.
+//
+// Pure and adapter-agnostic: the Buzz adapter uses these, but nothing here is
+// Buzz-specific.
+
+import type { Tag } from "./event.ts";
+
+/**
+ * Extract a reply's thread position from its "e" tags.
+ *
+ * Two encodings exist in the wild and both must be handled:
+ *   MARKERED (current)  ["e", <id>, <relay>, "root"] / [… "reply"]
+ *   POSITIONAL (legacy) the FIRST "e" tag is the root, the LAST is the direct
+ *                       parent; with exactly one, it is both.
+ * A markered tag anywhere wins — mixing the two is malformed, and trusting the
+ * explicit marker is the safer read.
+ */
+export function threadRefs(tags: Tag[]): { root?: string; reply?: string } {
+  const eTags = tags.filter((t) => t[0] === "e" && typeof t[1] === "string" && t[1].length > 0);
+  if (eTags.length === 0) return {};
+
+  const markered = eTags.filter((t) => t[3] === "root" || t[3] === "reply");
+  if (markered.length > 0) {
+    return {
+      root: markered.find((t) => t[3] === "root")?.[1],
+      reply: markered.find((t) => t[3] === "reply")?.[1],
+    };
+  }
+
+  // Legacy positional form.
+  if (eTags.length === 1) return { root: eTags[0][1], reply: eTags[0][1] };
+  return { root: eTags[0][1], reply: eTags[eTags.length - 1][1] };
+}
+
+/** Every pubkey this event tags — i.e. everyone it @-mentions. */
+export function pTags(tags: Tag[]): string[] {
+  return tags.filter((t) => t[0] === "p" && typeof t[1] === "string" && t[1].length > 0).map((t) => t[1]);
+}
+
+/** Blossom content hashes attached to this event (["x", <sha256>]). */
+export function xTags(tags: Tag[]): string[] {
+  return tags.filter((t) => t[0] === "x" && typeof t[1] === "string" && t[1].length > 0).map((t) => t[1]);
+}
+
+/**
+ * Build the tags for a reply.
+ *
+ * `root` is the thread root and `parent` the message being answered; when only one
+ * is known, pass it as both — a reply that marks a root but no parent reads as a
+ * top-level post to most clients. Mentioned pubkeys are deduped, since duplicate "p"
+ * tags inflate relay-side mention indexes for no benefit.
+ */
+export function replyTags(root?: string, parent?: string, mentionPubkeys: string[] = []): Tag[] {
+  const out: Tag[] = [];
+  if (root) out.push(["e", root, "", "root"]);
+  if (parent && parent !== root) out.push(["e", parent, "", "reply"]);
+  for (const pk of [...new Set(mentionPubkeys)]) out.push(["p", pk]);
+  return out;
+}

package/src/permissions/classify.ts

@@ -1,5 +1,7 @@
 import { resolve, isAbsolute, relative, dirname, join, basename } from "node:path";
 import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { isProtectedPath } from "./protected.ts";
 import type { PermissionRequest } from "./gate.ts";
 
@@ -42,8 +44,57 @@ function realBase(abs: string): string {
   }
 }
 
+// ⚠️ SECURITY-CRITICAL: this MUST resolve a path string to exactly the same place
+// Pi's file tools do, or the gate judges one file and the tool touches another.
+//
+// Pi resolves every tool path through `resolveToCwd` → `resolvePath` →
+// `normalizePath` (node_modules/@earendil-works/pi-coding-agent/dist/utils/paths.js
+// and dist/core/tools/path-utils.js), which EXPANDS `~`, STRIPS a leading `@`, and
+// converts `file://` URLs. `node:path` treats all three as RELATIVE, so a classifier
+// using bare resolve() computed `<cwd>/~/.ssh/authorized_keys` — comfortably "inside"
+// the working directory — while `write` truly targeted `$HOME/.ssh/authorized_keys`.
+// That made `outside` false and `protected` false (isProtectedPath matches basenames,
+// and `authorized_keys` isn't one), so:
+//   • reads returned null from classifyToolCall — NO gate at all, in every posture
+//     including plan/readonly, at the default read-only tool ceiling; and
+//   • writes auto-allowed under acceptEdits / bypass / no-quarter.
+// The adversary here is the MODEL (prompt injection), not the user, so "the operator
+// could read that file anyway" does not apply.
+//
+// Pi does not export normalizePath (package exports are "." and "./rpc-entry" only),
+// so it is mirrored here. KEEP IN SYNC — tests/classifyPathParity.test.ts asserts this
+// function agrees with Pi's own resolver, so a Pi upgrade that changes normalization
+// fails the suite instead of silently reopening the hole.
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeLikePi(input: string, opts: { unicodeSpaces?: boolean; stripAt?: boolean } = {}): string {
+  let s = input;
+  if (opts.unicodeSpaces) s = s.replace(UNICODE_SPACES, " ");
+  if (opts.stripAt && s.startsWith("@")) s = s.slice(1);
+  const home = homedir();
+  if (s === "~") return home;
+  if (s.startsWith("~/") || (process.platform === "win32" && s.startsWith("~\\"))) return join(home, s.slice(2));
+  if (/^file:\/\//.test(s)) {
+    // Pi lets fileURLToPath throw here, which fails the tool call. We must not throw
+    // (that would break the gate), so fall back to the raw string: it then resolves
+    // inside cwd, but the tool errors on the same input, so there is no divergence
+    // a caller can exploit.
+    try {
+      return fileURLToPath(s);
+    } catch {
+      return s;
+    }
+  }
+  return s;
+}
+
 function resolveInCwd(cwd: string, p: string): string {
-  return realBase(isAbsolute(p) ? p : resolve(cwd, p));
+  // Mirrors resolvePath(): the TARGET gets the tools' options
+  // ({normalizeUnicodeSpaces, stripAtPrefix}); the BASE gets normalizePath's defaults
+  // (tilde/file:// only), because Pi normalizes baseDir with no options.
+  const target = normalizeLikePi(p, { unicodeSpaces: true, stripAt: true });
+  const base = normalizeLikePi(cwd);
+  return realBase(isAbsolute(target) ? resolve(target) : resolve(base, target));
 }
 
 function isInsideDir(root: string, abs: string): boolean {
@@ -90,8 +141,17 @@ function unknownTarget(toolName: string, kind: "write" | "edit"): PermissionRequ
 // machine: no gate regardless of arguments. Tunable — the conservative default for
 // anything NOT listed here is to ask (see below). TODO(verify) against Pi's full
 // builtin tool catalog as it's enumerated in Phase 5.
+// `ask_user_question` (rpiv-ask-user-question, shimmed by the launcher) is here on
+// purpose: it is a QUESTION PUT TO THE USER — it renders a dialog and returns what the
+// human picked. It touches nothing, sends nothing, and the human is already in the loop
+// by construction. Gating it would fall through to the unknown-tool branch below, which
+// classifies as bash-kind: a pointless "Run ask_user_question" prompt in default mode,
+// and an outright DENY in plan/readonly — the very posture where a model most needs to
+// ask instead of guess. Headless surfaces need no guard either: the tool self-checks
+// ctx.hasUI and returns an error result when there's no one to ask.
 const NON_GATED = new Set([
   "todo", "todowrite", "todo_write", "todoread", "think", "plan_note",
+  "ask_user_question",
 ]);
 
 // Read-ish builtins: gated ONLY when the target resolves outside scope.

package/src/providers/account.ts

@@ -114,10 +114,37 @@ export function loadCachedCatalogIds(): string[] {
   }
 }
 
+// Whether the account channel can actually SERVE a catalog model right now.
+//
+// `phala/*` is sealed-only: it runs through the sealed blind relay and nowhere else.
+// The server's cleartext `/api/agent/v1` has no Phala route and rejects the id
+// outright (verified live 2026-07-31: 400 "phala/… is not a valid model ID"), because
+// Phala models are the Sealed tier by design — the server is not meant to be able to
+// read them. But `/api/models` advertises them to every client regardless of whether
+// that client can reach the sealed path, so they were pickable and then failed on the
+// first prompt. Offering a model we know cannot answer is worse than a shorter list.
+//
+// The condition is the SHIM, not the flag. Sealed mode being enabled only means we
+// intend to seal; `phala/*` is unservable until the loopback shim is actually
+// listening, because that is what its per-model baseUrl points at (see modelEntry).
+// With the flag now defaulting on, "enabled but the shim failed to bind" is a state a
+// user can really land in, and it must not re-offer models that would 400.
+//
+// `tinfoil/*` is deliberately NOT filtered: the cleartext path serves it fine (sealed
+// mode only upgrades the badge from unconfirmed to verified), so it stays either way.
+export function isServableAccountModel(id: string): boolean {
+  if (!id.startsWith("phala/")) return true;
+  return sealedEnabled() && sealedShimBase() !== null;
+}
+
 // The ids to register synchronously at load. DEFAULT_MODELS FIRST and always: the account
 // default has to be index 0 both because it must always resolve and because Pi clones the
 // provider's first/default model when it synthesizes a custom model id
 // (model-resolver.js buildFallbackModel).
+//
+// Returns the server's list as cached, unfiltered — accountProviderConfig decides what
+// is servable at each registration, so a model dropped now (shim not up yet) can be
+// re-offered by a later re-registration without the cache being rewritten.
 export function seedCatalogIds(): string[] {
   const ids = [...DEFAULT_MODELS];
   const seen = new Set(ids);
@@ -202,7 +229,9 @@ export async function fetchAccountCatalog(): Promise<AccountModelInfo[]> {
         .map((m) => (m.modelId ? { id: m.modelId, tier: normalizeTier(m.privacy?.tier, m.modelId) } : null))
         .filter((x): x is AccountModelInfo => !!x);
       // Cache only a real LIVE listing — never the fallback, which would freeze the six
-      // seed ids on disk and read back as though it were the catalog.
+      // seed ids on disk and read back as though it were the catalog. Both the cache and
+      // the returned list are the server's UNFILTERED offer; servability is decided at
+      // registration (accountProviderConfig), which re-evaluates it every time.
       if (parsed.length) saveCachedCatalogIds(parsed.map((p) => p.id));
       infos = parsed.length ? parsed : fallback();
     }
@@ -402,14 +431,15 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
     const att = await attestSealed(sealedProvider);
     return att.ok ? { tier: "tee-verified" } : { tier: "tee-unverified", error: att.error };
   }
-  // Honest labelling for the non-NEAR enclaves without sealed mode. Tinfoil and Phala
-  // publish real attestations, but the server proxies the inference in cleartext, so
-  // from here we cannot bind a quote to the connection actually carrying our tokens —
-  // only the account's word that it did. That's `tee-unverified` (yellow "confidential
-  // compute, unconfirmed"), never the green tee-verified we reserve for a quote we
-  // checked ourselves. Turn on sealed mode (PRIVATEER_SEALED=1) for the verified
-  // shield, or set TINFOIL_API_KEY and run `tinfoil/*` direct (pi-privacy attests
-  // client-side over the TLS binding).
+  // Honest labelling for the non-NEAR enclaves when we are NOT sealing — sealed mode
+  // explicitly disabled (PRIVATEER_SEALED=0), or on but the shim never came up. Tinfoil
+  // and Phala publish real attestations, but the server proxies the inference in
+  // cleartext, so from here we cannot bind a quote to the connection actually carrying
+  // our tokens — only the account's word that it did. That's `tee-unverified` (yellow
+  // "confidential compute, unconfirmed"), never the green tee-verified we reserve for a
+  // quote we checked ourselves. Re-enable sealed mode for the verified shield, or set
+  // TINFOIL_API_KEY and run `tinfoil/*` direct (pi-privacy attests client-side over the
+  // TLS binding).
   if (!modelId.startsWith("near/")) {
     return { tier: "tee-unverified" };
   }
@@ -429,11 +459,13 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
   }
 }
 
-// A model entry, with a per-model baseUrl override once the EHBP shim is listening:
-// `tinfoil/*` then route through the loopback shim (which seals to the blind relay)
-// instead of the cleartext `/api/agent/v1` proxy. Everything else keeps the provider
-// baseUrl. Until the shim is up (or when sealed mode is off) sealed models fall back to
-// the cleartext path — and the badge stays honestly `tee-unverified` (see accountPosture).
+// A model entry, with a per-model baseUrl override once the sealed shim is listening:
+// `tinfoil/*` and `phala/*` then route through the loopback shim (which seals to the
+// blind relay) instead of the cleartext `/api/agent/v1` proxy. Everything else keeps the
+// provider baseUrl. Until the shim is up (or with sealed mode disabled) `tinfoil/*` falls
+// back to the cleartext path and the badge stays honestly `tee-unverified` (see
+// accountPosture); `phala/*` has no cleartext path at all and is not registered in that
+// state (see isServableAccountModel).
 function modelEntry(id: string) {
   const base = seedModel(id);
   const provider = sealedEnabled() ? sealedProviderFor(id) : null;
@@ -448,7 +480,13 @@ export function accountProviderConfig(ids: string[]): Record<string, unknown> {
     baseUrl: `${serverBaseUrl()}/api/agent/v1`,
     api: "openai-completions",
     oauth: privateerOAuthProvider,
-    models: ids.map(modelEntry),
+    // Filter HERE rather than at the catalog, so callers keep passing the server's
+    // full list and every registration re-evaluates servability against the CURRENT
+    // shim state. That is what lets the post-shim re-registration in makeAccountProvider
+    // put `phala/*` back: had the ids been filtered upstream, the sealed-only models
+    // would have been dropped from `lastIds` before the shim ever finished starting and
+    // nothing would have brought them back.
+    models: ids.filter(isServableAccountModel).map(modelEntry),
   };
 }
 

package/src/providers/phala/aci-verifier/VENDORED.md

@@ -21,3 +21,19 @@ Everything else is byte-for-byte upstream. The crypto runs on `globalThis.crypto
 (Node ≥ 22) these are all native — **no polyfills needed** (unlike the treeview RN app,
 which bridges them via `react-native-quick-crypto`). Re-pull from upstream to update;
 re-apply only the `.js`-extension strip.
+
+## What lives OUTSIDE this directory (and why)
+`../reportBinding.ts` — `verifyAciReportBinding`, the algorithm dispatch for §10.1
+checks 2–6. Callers use it instead of importing `verifyReportBinding` from here.
+
+Upstream's verifier is Web-Crypto-only, so it throws `UnsupportedAlgorithmError` on
+an `ecdsa-secp256k1` keyset endorsement — which §4.3 explicitly permits alongside
+ed25519, and which the deployed `inference.phala.com` gateway actually uses. Rather
+than patch this tree (and re-patch it on every re-pull), the dispatch sits outside:
+ed25519 delegates here verbatim, secp256k1 takes a parallel path over `@noble/curves`,
+and any other algorithm still throws. Nothing here changed, so the re-pull recipe
+above stays exactly the `.js`-extension strip.
+
+If upstream ever adds secp256k1 (or a check 7) to `report.ts`, collapse
+`reportBinding.ts` back to a straight re-export — `tests/phalaReportBinding.test.ts`
+pins the behaviour either way.

package/src/providers/phala/reportBinding.ts

@@ -0,0 +1,193 @@
+// Algorithm dispatch for the ACI report-binding checks (§10.1 checks 2–6).
+//
+// The ACI spec (§4.3) allows the keyset endorsement to be signed with EITHER
+// `ed25519` OR `ecdsa-secp256k1` — the former because "every primitive in it is
+// available in the Web Crypto API", the latter for "clients in the EVM/dstack
+// ecosystem". Upstream's reference TS verifier implements only the Web Crypto half:
+// `verifySignature` throws `UnsupportedAlgorithmError` on secp256k1
+// (aci-verifier/crypto.ts), and `verifyReportBinding` propagates that.
+//
+// The deployed gateway (inference.phala.com) signs with `ecdsa-secp256k1`, so the
+// vendored verifier can never attest it — a limit of upstream's CLIENT, not of the
+// spec or the gateway. Verified live 2026-07-31: attestation fetched, endorsement
+// rejected with UnsupportedAlgorithmError.
+//
+// This module owns the dispatch so `aci-verifier/` stays byte-for-byte upstream
+// (see its VENDORED.md — only the `.js`-extension strip diverges, and re-pulls stay
+// mechanical):
+//   ed25519         → delegate to the vendored verifyReportBinding, verbatim
+//   ecdsa-secp256k1 → the same checks 2–6, with check 5 done over @noble/curves
+//   anything else   → still throws (never a silent pass)
+//
+// The secp256k1 path deliberately mirrors report.ts check-for-check, in the same
+// order and with the same check names, so a caller cannot tell which path ran.
+
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import {
+  verifyReportBinding,
+  computeWorkloadId,
+  computeKeysetDigest,
+  computeReportData,
+  keysetEndorsementPayload,
+  sha256,
+  fromHex,
+  UnsupportedAlgorithmError,
+  type AttestationReport,
+  type Check,
+  type ReportVerification,
+  type ReportBindingOptions,
+} from "./aci-verifier/index.ts";
+
+const ED25519 = "ed25519";
+const SECP256K1 = "ecdsa-secp256k1";
+
+/**
+ * Verify a report's cryptographic bindings for `nonce` (§10.1 checks 2–6),
+ * dispatching on the algorithm the attested identity key declares. Drop-in
+ * replacement for the vendored `verifyReportBinding`: same arguments, same result
+ * shape, same "a failed check is `ok: false`, never thrown" contract.
+ *
+ * Like upstream, this is the crypto-binding half only — compose it with a hardware
+ * quote verifier (phalaSeal.ts `verifyHardwareQuote`) for Level 2.
+ */
+export async function verifyAciReportBinding(
+  report: AttestationReport,
+  nonce: string | null | undefined,
+  options: ReportBindingOptions = {},
+): Promise<ReportVerification> {
+  const algo = report.attestation.workload_keyset.workload_identity.public_key.algo;
+  if (algo === ED25519) return verifyReportBinding(report, nonce, options);
+  if (algo !== SECP256K1) {
+    // Same fail-closed posture as upstream: an algorithm we cannot check is a
+    // refusal, not a pass.
+    throw new UnsupportedAlgorithmError(algo, "keyset endorsement (§4.3)");
+  }
+  return verifySecp256k1ReportBinding(report, nonce, options);
+}
+
+async function verifySecp256k1ReportBinding(
+  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 verifyHardwareQuote's job.
+  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 verifySecp256k1(
+      identityKey.public_key,
+      endorsement.value,
+      keysetEndorsementPayload(workloadKeysetDigest),
+    );
+    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
+  // the profile trusts it, 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 };
+}
+
+/**
+ * §4.3 secp256k1 endorsement: a 64-byte `r || s` signature over
+ * `sha256(payload bytes)`. Returns false on malformed input rather than throwing —
+ * a bad signature is a failed check, not an exception.
+ *
+ * NOT the §8.5 *receipt* shape, which is a 65-byte recoverable `r || s || v` and
+ * where the spec says 64-byte signatures MUST be rejected. Different shapes; easy
+ * to conflate if this ever grows a receipt path.
+ */
+async function verifySecp256k1(
+  publicKeyHex: string,
+  signatureHex: string,
+  payload: Uint8Array,
+): Promise<boolean> {
+  try {
+    const sig = fromHex(signatureHex);
+    if (sig.length !== 64) return false; // r||s only; DER / recoverable forms are not §4.3
+    const msgHash = await sha256(payload);
+    return secp256k1.verify(sig, msgHash, publicKey(publicKeyHex), {
+      prehash: false, // we hand it the sha256 digest, per §4.3
+      // Accept high-s as well as low-s. ECDSA malleability is meaningless for a
+      // signature over a FIXED payload — an attacker who can flip s already has a
+      // valid endorsement and still cannot sign a different keyset digest. Leaving
+      // the default on would reject ~half of otherwise-valid endorsements from any
+      // signer that doesn't normalize, as an intermittent attestation failure.
+      lowS: false,
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Identity key bytes. §7.1 pins secp256k1 public keys as 65-byte uncompressed SEC1
+ * and requires that "the 64-byte uncompressed form without the `0x04` prefix MUST be
+ * accepted and treated as the same key" — so restore the prefix when it's absent.
+ * The live gateway sends the 65-byte form; do NOT prefix that one again.
+ */
+function publicKey(hex: string): Uint8Array {
+  const raw = fromHex(hex);
+  if (raw.length === 64) {
+    const sec1 = new Uint8Array(65);
+    sec1[0] = 0x04;
+    sec1.set(raw, 1);
+    return sec1;
+  }
+  return raw;
+}
+
+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}` }) });
+}