privateer-agent 0.7.0 → 0.8.2

package/src/harbor/ipc.ts

@@ -33,44 +33,82 @@ export interface IpcResponse {
 
 export type IpcHandler = (req: IpcRequest) => Promise<IpcResponse> | IpcResponse;
 
-// Start the harbor-side socket server. Returns the Server so the caller can close it.
-export function startIpcServer(handler: IpcHandler): Server {
+// Probe whether a LIVE process is listening on the socket at `path`. Used as the
+// single-instance test: a successful connect (or a slow-to-answer one) means a real
+// harbor holds the lock; ECONNREFUSED/ENOENT means the socket file is stale (no
+// listener behind it) and is safe to reclaim. Conservative — any ambiguous error
+// resolves `true` so we never steal a path that might still be owned.
+function probeExistingListener(path: string, timeoutMs = 1000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createConnection(path);
+    const done = (live: boolean) => {
+      clearTimeout(timer);
+      try { sock.destroy(); } catch { /* already gone */ }
+      resolve(live);
+    };
+    const timer = setTimeout(() => done(true), timeoutMs); // slow to answer ⇒ assume live
+    sock.on("connect", () => done(true));
+    sock.on("error", (err: NodeJS.ErrnoException) => {
+      done(!(err.code === "ECONNREFUSED" || err.code === "ENOENT"));
+    });
+  });
+}
+
+// Start the harbor-side socket server. Resolves with the Server (so the caller can
+// close it), or REJECTS with HarborAlreadyRunningError if a live harbor already owns
+// the socket — the bind is the machine's single-instance lock. Two harbors under one
+// ~/.privateer share a single routineRelayId(), so a second instance would collide on
+// the relay and double-fire routines; refusing to start is the fix. A stale socket
+// file (crash with no live listener) is detected and reclaimed, so recovery still works.
+export function startIpcServer(handler: IpcHandler): Promise<Server> {
   const path = harborSocketPath();
-  // A stale socket file from a previous crash would block bind; remove it first.
-  if (existsSync(path)) {
-    try {
-      unlinkSync(path);
-    } catch {
-      /* ignore — bind will surface a clearer error */
-    }
-  }
-  const server = createServer((sock: Socket) => {
-    let buf = "";
-    sock.on("data", (chunk) => {
-      buf += chunk.toString("utf8");
-      const nl = buf.indexOf("\n");
-      if (nl < 0) return; // wait for the full line
-      const line = buf.slice(0, nl);
-      void (async () => {
-        let res: IpcResponse;
+  const build = (): Server =>
+    createServer((sock: Socket) => {
+      let buf = "";
+      sock.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        const nl = buf.indexOf("\n");
+        if (nl < 0) return; // wait for the full line
+        const line = buf.slice(0, nl);
+        void (async () => {
+          let res: IpcResponse;
+          try {
+            res = await handler(JSON.parse(line) as IpcRequest);
+          } catch (err) {
+            res = { ok: false, message: err instanceof Error ? err.message : String(err) };
+          }
+          sock.end(JSON.stringify(res) + "\n");
+        })();
+      });
+      sock.on("error", () => sock.destroy());
+    });
+
+  return new Promise<Server>((resolve, reject) => {
+    // `reclaimed` guards a single stale-socket reclaim so a persistent bind failure
+    // can't loop. On EADDRINUSE we probe for a live listener rather than unlinking
+    // blindly (the old behavior, which let a second harbor silently steal the path).
+    const attempt = (reclaimed: boolean) => {
+      const server = build();
+      server.once("error", (err: NodeJS.ErrnoException) => {
+        if (err.code !== "EADDRINUSE") { reject(err); return; }
+        void probeExistingListener(path).then((live) => {
+          if (live) { reject(new HarborAlreadyRunningError()); return; }
+          if (reclaimed) { reject(err); return; } // already reclaimed once — give up
+          try { unlinkSync(path); } catch { /* ignore — retry surfaces a clearer error */ }
+          attempt(true);
+        });
+      });
+      server.listen(path, () => {
         try {
-          res = await handler(JSON.parse(line) as IpcRequest);
-        } catch (err) {
-          res = { ok: false, message: err instanceof Error ? err.message : String(err) };
+          chmodSync(path, 0o600); // owner-only IPC endpoint
+        } catch {
+          /* non-POSIX — best effort */
         }
-        sock.end(JSON.stringify(res) + "\n");
-      })();
-    });
-    sock.on("error", () => sock.destroy());
-  });
-  server.listen(path, () => {
-    try {
-      chmodSync(path, 0o600); // owner-only IPC endpoint
-    } catch {
-      /* non-POSIX — best effort */
-    }
+        resolve(server);
+      });
+    };
+    attempt(false);
   });
-  return server;
 }
 
 // Client side: send one request, resolve with the response. Rejects if the harbor
@@ -116,6 +154,16 @@ export class HarborNotRunningError extends Error {
   }
 }
 
+// Thrown by startIpcServer when a live harbor already holds this machine's socket —
+// i.e. a second instance is trying to start under the same ~/.privateer. The caller
+// (runHarbor) treats this as a clean no-op exit, not a crash.
+export class HarborAlreadyRunningError extends Error {
+  constructor() {
+    super("A Harbor is already running on this machine.");
+    this.name = "HarborAlreadyRunningError";
+  }
+}
+
 // Convenience: is the harbor reachable right now?
 export async function harborIsRunning(): Promise<boolean> {
   try {

package/src/mcp/catalog.ts

@@ -130,6 +130,168 @@ export const MCP_CATALOG: CatalogEntry[] = [
     args: ["-y", "@modelcontextprotocol/server-memory"],
     needs: "none",
   },
+
+  // ── Remote, browser-authorized (OAuth) ──────────────────────────────────────
+  {
+    id: "sentry",
+    name: "sentry",
+    label: "Sentry",
+    blurb: "Errors, issues, and releases. Sign in via browser.",
+    transport: "http",
+    url: "https://mcp.sentry.dev/mcp",
+    oauth: true,
+    needs: "oauth",
+  },
+  {
+    id: "atlassian",
+    name: "atlassian",
+    label: "Jira & Confluence",
+    blurb: "Atlassian issues and pages. Sign in via browser.",
+    transport: "http",
+    url: "https://mcp.atlassian.com/v1/sse",
+    oauth: true,
+    needs: "oauth",
+  },
+  {
+    id: "stripe",
+    name: "stripe",
+    label: "Stripe",
+    blurb: "Payments, customers, and invoices. Sign in via browser.",
+    transport: "http",
+    url: "https://mcp.stripe.com",
+    oauth: true,
+    needs: "oauth",
+  },
+  {
+    id: "asana",
+    name: "asana",
+    label: "Asana",
+    blurb: "Tasks and projects. Sign in via browser.",
+    transport: "http",
+    url: "https://mcp.asana.com/sse",
+    oauth: true,
+    needs: "oauth",
+  },
+
+  // ── Local, token-authorized ─────────────────────────────────────────────────
+  {
+    id: "brave-search",
+    name: "brave-search",
+    label: "Brave Search",
+    blurb: "Web and local search results.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-brave-search"],
+    env: { BRAVE_API_KEY: "" },
+    needs: "token",
+    fill: "BRAVE_API_KEY",
+    credUrl: "https://brave.com/search/api/",
+  },
+  {
+    id: "google-maps",
+    name: "google-maps",
+    label: "Google Maps",
+    blurb: "Places, directions, and geocoding.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-google-maps"],
+    env: { GOOGLE_MAPS_API_KEY: "" },
+    needs: "token",
+    fill: "GOOGLE_MAPS_API_KEY",
+    credUrl: "https://console.cloud.google.com/google/maps-apis/credentials",
+  },
+  {
+    id: "supabase",
+    name: "supabase",
+    label: "Supabase",
+    blurb: "Query and manage your Supabase project.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@supabase/mcp-server-supabase@latest"],
+    env: { SUPABASE_ACCESS_TOKEN: "" },
+    needs: "token",
+    fill: "SUPABASE_ACCESS_TOKEN",
+    credUrl: "https://supabase.com/dashboard/account/tokens",
+  },
+  {
+    id: "figma",
+    name: "figma",
+    label: "Figma",
+    blurb: "Read designs, frames, and components.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "figma-developer-mcp", "--stdio"],
+    env: { FIGMA_API_KEY: "" },
+    needs: "token",
+    fill: "FIGMA_API_KEY",
+    credUrl: "https://www.figma.com/developers/api#access-tokens",
+  },
+  // ── Google Workspace (needs a Google Cloud OAuth client, then browser sign-in) ─
+  // One server (workspace-mcp) scoped per service via --tools. Runs on uv (uvx),
+  // not npx. Create an OAuth client in Google Cloud once and paste its ID + secret;
+  // the first request opens Google's consent screen on THIS machine.
+  {
+    id: "gmail",
+    name: "gmail",
+    label: "Gmail",
+    blurb: "Read, search, and send email. Google sign-in.",
+    transport: "stdio",
+    command: "uvx",
+    args: ["workspace-mcp", "--tools", "gmail"],
+    env: { GOOGLE_OAUTH_CLIENT_ID: "", GOOGLE_OAUTH_CLIENT_SECRET: "" },
+    needs: "token",
+    fill: "GOOGLE_OAUTH_CLIENT_ID",
+    credUrl: "https://console.cloud.google.com/apis/credentials",
+  },
+  {
+    id: "google-calendar",
+    name: "google-calendar",
+    label: "Google Calendar",
+    blurb: "Events and scheduling. Google sign-in.",
+    transport: "stdio",
+    command: "uvx",
+    args: ["workspace-mcp", "--tools", "calendar"],
+    env: { GOOGLE_OAUTH_CLIENT_ID: "", GOOGLE_OAUTH_CLIENT_SECRET: "" },
+    needs: "token",
+    fill: "GOOGLE_OAUTH_CLIENT_ID",
+    credUrl: "https://console.cloud.google.com/apis/credentials",
+  },
+  {
+    id: "google-drive",
+    name: "google-drive",
+    label: "Google Drive",
+    blurb: "Files and folders in your Drive. Google sign-in.",
+    transport: "stdio",
+    command: "uvx",
+    args: ["workspace-mcp", "--tools", "drive"],
+    env: { GOOGLE_OAUTH_CLIENT_ID: "", GOOGLE_OAUTH_CLIENT_SECRET: "" },
+    needs: "token",
+    fill: "GOOGLE_OAUTH_CLIENT_ID",
+    credUrl: "https://console.cloud.google.com/apis/credentials",
+  },
+  {
+    id: "google-docs",
+    name: "google-docs",
+    label: "Google Docs",
+    blurb: "Read and edit your documents. Google sign-in.",
+    transport: "stdio",
+    command: "uvx",
+    args: ["workspace-mcp", "--tools", "docs"],
+    env: { GOOGLE_OAUTH_CLIENT_ID: "", GOOGLE_OAUTH_CLIENT_SECRET: "" },
+    needs: "token",
+    fill: "GOOGLE_OAUTH_CLIENT_ID",
+    credUrl: "https://console.cloud.google.com/apis/credentials",
+  },
+  {
+    id: "sequential-thinking",
+    name: "sequential-thinking",
+    label: "Sequential Thinking",
+    blurb: "A step-by-step reasoning scratchpad.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    needs: "none",
+  },
 ];
 
 export function catalogEntry(id: string): CatalogEntry | undefined {

package/src/permissions/noQuarter.ts

@@ -0,0 +1,42 @@
+// No-quarter: the moat fully lowered for a session — every action auto-approves
+// with no prompt (dangerous shell, destructive tools, out-of-cwd, protected files).
+// This is the single source of truth for that state; the gate reads it through
+// ModeGate.getSkipAllPermissions, which sits above every other policy check.
+//
+// Two ways in, one state:
+//   1. `privateer --no-quarter` at launch → PRIVATEER_NO_QUARTER=1 (see
+//      bin/privateer-launch.mjs), which seeds `active` below.
+//   2. shift+tab in a live session → toggleNoQuarter(). This is the "step away from
+//      the keyboard" switch: flip it on and the agent runs to completion instead of
+//      stopping on the next approval prompt.
+//
+// Toggling MIRRORS the env var, because that's how the state reaches subagents: a
+// pi-subagents child is a `pi` subprocess that inherits this process's env and reads
+// PRIVATEER_NO_QUARTER in its own gate. Children spawned after a toggle therefore
+// match the parent; ones already running keep the posture they started with.
+//
+// IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere,
+// including boot-ordered entrypoints (see boot.ts's ORDERING CONTRACT).
+
+const ENV = "PRIVATEER_NO_QUARTER";
+
+// Seeded from the launch flag so `--no-quarter` and the toggle share one state.
+let active = process.env[ENV] === "1";
+
+/** True while the gate is fully lowered for this session. */
+export function noQuarterActive(): boolean {
+  return active;
+}
+
+/** Set the state (and mirror it to the env for future subagent children). Returns the new state. */
+export function setNoQuarter(on: boolean): boolean {
+  active = on;
+  if (on) process.env[ENV] = "1";
+  else delete process.env[ENV];
+  return active;
+}
+
+/** Flip the state. Returns the new state. */
+export function toggleNoQuarter(): boolean {
+  return setNoQuarter(!active);
+}

package/src/providers/account.ts

@@ -22,6 +22,13 @@ import {
 } from "../auth/privateer.ts";
 import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
 import { ACCOUNT_DEFAULT_MODEL_ID, ACCOUNT_NEAR_MODEL_ID, ensurePiDefaultModel } from "./defaultModel.ts";
+import {
+  sealedEnabled,
+  sealedProviderFor,
+  sealedShimBase,
+  ensureSealedShim,
+  attestSealed,
+} from "./sealedShim.ts";
 
 // Seed/fallback catalog: registered synchronously so the account provider has real
 // models the instant it loads (before the live /api/models fetch resolves) — in
@@ -33,8 +40,9 @@ import { ACCOUNT_DEFAULT_MODEL_ID, ACCOUNT_NEAR_MODEL_ID, ensurePiDefaultModel }
 const DEFAULT_MODELS = [
   ACCOUNT_DEFAULT_MODEL_ID,
   ACCOUNT_NEAR_MODEL_ID,
-  "anthropic/claude-sonnet-4.6",
-  "openai/gpt-5.5",
+  "anthropic/claude-opus-5",
+  "anthropic/claude-sonnet-5",
+  "openai/gpt-5.6-sol",
   "deepseek/deepseek-v4-flash",
 ];
 
@@ -73,7 +81,9 @@ const VALID_TIERS = new Set<PrivacyTier>([
 // upgrades it to tee-verified live via attestation (accountPosture). Everything
 // else with no server signal is "standard": we don't assert ZDR we can't back.
 function tierFromPrefix(modelId: string): PrivacyTier {
-  return modelId.startsWith("near/") || modelId.startsWith("tinfoil/") ? "tee-unverified" : "standard";
+  return modelId.startsWith("near/") || modelId.startsWith("tinfoil/") || modelId.startsWith("phala/")
+    ? "tee-unverified"
+    : "standard";
 }
 
 function normalizeTier(tier: string | undefined, modelId: string): PrivacyTier {
@@ -248,13 +258,26 @@ export async function accountPosture(modelId: string): Promise<AccountPosture> {
   if (privateerChannel(modelId) === "zdr") {
     return { tier: "zdr-policy" };
   }
-  // Honest labelling for the non-NEAR enclaves. Tinfoil and Phala publish real
-  // attestations, but the server proxies the inference, 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. A user
-  // who wants the verified shield sets TINFOIL_API_KEY and runs `tinfoil/*` direct,
-  // where pi-privacy attests the enclave client-side.
+  // Sealed (EHBP) path. When sealed mode is on and the model has a Node sealed
+  // client (tinfoil/*), inference goes through the blind relay with the body
+  // HPKE-sealed to the enclave, and we attest that enclave client-side with the SAME
+  // SecureClient that carries the tokens. A green ready() is a quote WE checked,
+  // bound to the HPKE key we seal to — so it earns tee-verified. A failure stays
+  // tee-unverified with the reason surfaced (never a silent green). See
+  // docs/tee-privateer-tinfoil-ehbp.md.
+  const sealedProvider = sealedEnabled() ? sealedProviderFor(modelId) : null;
+  if (sealedProvider) {
+    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).
   if (!modelId.startsWith("near/")) {
     return { tier: "tee-unverified" };
   }
@@ -299,15 +322,40 @@ export function makeAccountProvider() {
     on?: (event: string, handler: (e: unknown, ctx: unknown) => void) => void;
   }): void => {
     if (typeof pi.registerProvider !== "function") return;
-    const register = (ids: string[]): void =>
+    // A model entry, with a per-model baseUrl override for sealed models 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 below. 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).
+    const modelEntry = (id: string) => {
+      const base = seedModel(id);
+      const provider = sealedEnabled() ? sealedProviderFor(id) : null;
+      const shim = sealedShimBase();
+      return provider && shim ? { ...base, baseUrl: `${shim}/${provider}/v1` } : base;
+    };
+    let lastIds: string[] = DEFAULT_MODELS;
+    const register = (ids: string[]): void => {
+      lastIds = ids;
       pi.registerProvider!("privateer", {
         name: "Privateer account",
         baseUrl: `${serverBaseUrl()}/api/agent/v1`,
         api: "openai-completions",
         oauth: privateerOAuthProvider,
-        models: ids.map(seedModel),
+        models: ids.map(modelEntry),
       });
+    };
     register(DEFAULT_MODELS); // immediate: provider exists this tick
+    // Bring up the sealed shim, then re-register so sealed models pick up their shim
+    // baseUrl. Registration re-runs anyway after the catalog fetch; this just makes
+    // sure the switch lands even if the fetch is slow or fails.
+    if (sealedEnabled()) {
+      void ensureSealedShim()
+        .then(() => register(lastIds))
+        .catch(() => {
+          /* shim failed to start → sealed models stay on the cleartext path */
+        });
+    }
     // Refine to the live catalog. fetchAccountCatalog also populates accountTierMap
     // as a side effect, so the /models picker can shield each row without re-fetching.
     void fetchAccountCatalog()

package/src/providers/catalog.ts

@@ -2,9 +2,9 @@
 // becomes reachable under Pi. Written after verifying (2026-07-07) that:
 //   - pi-ai ships STATIC model catalogs for its 14 built-in providers, so they're
 //     selectable once a key is present — privateer emits NO models.json entry for them;
-//   - the `pi-privacy` extension registers the 6 privacy providers (tinfoil, nearai,
-//     venice, ollama, custom, privateer-api) at load — privateer emits NO entry for
-//     them either;
+//   - the `pi-privacy` extension registers the privacy providers (tinfoil, nearai,
+//     venice, ollama, and — since pi-privacy 0.7 — `privateer`, its posture-aware
+//     public dev-key surface) at load — privateer emits NO entry for them either;
 //   - so the ONLY provider this generator must emit is `qwen` (config-only,
 //     non-privacy, no built-in catalog), and `privateer` (the account OAuth channel)
 //     is handled in code, not config (Phase 4).
@@ -66,9 +66,11 @@ export const PROVIDERS: ProviderEntry[] = [
   { id: "tinfoil", source: "pi-privacy" },
   { id: "venice", source: "pi-privacy" },
   { id: "custom", source: "pi-privacy" },
-  // Public developer-API surface (sk-priv-… key). Registered by the pi-privacy
-  // extension like the others; distinct from the in-app `privateer` account channel.
-  { id: "privateer-api", source: "pi-privacy" },
+  // The in-app account OAuth channel. NOTE: since pi-privacy 0.7 the extension ALSO
+  // registers a `privateer` provider (its posture-aware public sk-priv- dev-key surface,
+  // floored to zdr-policy) — but makeAccountProvider runs AFTER pi-privacy in the
+  // extension list and re-registers the same id, so the account channel wins. There is
+  // no longer a separate `privateer-api` id (renamed to `privateer` upstream).
   { id: "privateer", source: "account" },
 ];
 

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

@@ -0,0 +1,23 @@
+# Vendored: `@dstack/aci-verifier`
+
+Faithful copy of the zero-dependency TypeScript ACI verifier from
+[Dstack-TEE/private-ai-gateway](https://github.com/Dstack-TEE/private-ai-gateway)
+(`clients/verifier-ts/src`), Apache-2.0. It is `private: true` upstream (not on
+npm), so it is vendored here rather than installed.
+
+Provides the pieces `PhalaProvider` needs:
+- **`verifyReportBinding`** (`report.ts`) — §10.1 checks 2–6 (crypto binding of the
+  attestation report to the attested keyset for a supplied nonce). NOT the hardware
+  TDX quote (check 1) — that is layered on with `@phala/dcap-qvl` in the provider.
+- **`openE2eeChannel`** (`e2ee-channel.ts`) — the ACI E2EE channel:
+  `x25519-aes-256-gcm-hkdf-sha256`, per-field seal/open, `X-E2EE-*` headers.
+
+## Local adaptation (the only change from upstream)
+- Relative import specifiers had their `.js` extension stripped (`'./jcs.js'` →
+  `'./jcs'`) so Metro + TS (`moduleResolution: bundler`) resolve to the `.ts` files.
+
+Everything else is byte-for-byte upstream. The crypto runs on `globalThis.crypto`
+(Web Crypto: X25519, HKDF, AES-GCM, Ed25519, `getRandomValues`). In privateer-agent
+(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.

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