privateer-agent 0.9.2 → 0.10.0

package/src/channels/whatsapp.ts

@@ -87,14 +87,50 @@ export class WhatsAppAdapter implements ChannelAdapter {
 
   async start(onMessage: (m: InboundMessage) => void): Promise<void> {
     this.onMessage = onMessage;
-    this.server = createServer((req, res) => this.handle(req, res));
-    await new Promise<void>((resolve) => this.server!.listen(this.port, () => resolve()));
+    const server = createServer((req, res) => this.handle(req, res));
+    this.server = server;
+    // Bind with a bounded retry. A restart of THIS platform (config change) may race
+    // the previous listener's last keep-alive socket draining; stop() destroys those,
+    // but the kernel can still hold the port for a beat. Retrying turns a lost
+    // platform into a sub-second delay. Anything other than EADDRINUSE fails fast.
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const onError = (e: NodeJS.ErrnoException) => reject(e);
+          server.once("error", onError);
+          server.listen(this.port, () => {
+            server.off("error", onError);
+            resolve();
+          });
+        });
+        break;
+      } catch (e) {
+        const code = (e as NodeJS.ErrnoException)?.code;
+        if (code !== "EADDRINUSE" || attempt >= 2) {
+          this.server = undefined;
+          throw e;
+        }
+        this.log(`port ${this.port} still in use — retrying in 500ms`);
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    }
     this.log(`webhook listening on :${this.port}${this.path} — expose it publicly for Meta to reach.`);
   }
 
-  stop(): void {
-    this.server?.close();
+  // Async, and it DESTROYS live connections. `server.close()` alone stops accepting
+  // new connections but resolves only once every existing keep-alive socket drains —
+  // Meta holds those open, so a plain close() can leave the port bound for a long
+  // time and the next listen() fails. Awaiting this is what makes a targeted
+  // per-platform restart safe.
+  async stop(): Promise<void> {
+    const server = this.server;
     this.server = undefined;
+    this.onMessage = undefined;
+    if (!server) return;
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    });
   }
 
   async sendText(chatId: string, text: string): Promise<void> {

package/src/cli/chat.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url"; // builtin, safe pre-boot
 import { cliPalette } from "../ui/palette.ts"; // no Pi deps → safe pre-boot
 import { noQuarterActive, setNoQuarter } from "../permissions/noQuarter.ts"; // no Pi deps → safe pre-boot
 import type { GateController } from "../ext/permissionGate.ts"; // type-only → erased, safe pre-boot
+import { createUIContext } from "../ext/headlessUi.ts"; // no Pi deps → safe pre-boot
 
 // This lean REPL has no Pi TUI (and so no Theme), so it detects the terminal background
 // itself (COLORFGBG) and picks a palette — on a light terminal the standard "\x1b[33m"
@@ -447,7 +448,7 @@ async function main() {
   // is correct: this REPL is interactive. The abort signal Pi passes (to dismiss a
   // dialog on interrupt) is threaded through so a cancelled turn doesn't wedge.
   const driven = (): boolean => bridge.getRemote() && bridge.isConnected();
-  const uiContext = {
+  const uiContext = createUIContext({
     // Pick one of `options`. Returns the chosen string, or undefined if cancelled.
     async select(title: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined> {
       if (!options.length) return undefined;
@@ -492,7 +493,7 @@ async function main() {
       console.log(`${color}${message}${RESET}`);
       if (driven()) bridge.sendNotice(message);
     },
-  };
+  });
   await (session as any).bindExtensions({ uiContext });
 
   // Stream the turn as EngineEvents — printed locally AND forwarded to the app

package/src/config/inlineMoat.ts

@@ -0,0 +1,67 @@
+// "Did this process already build its own permission gate in code?" — a process-level
+// marker, set by every non-TUI entry that passes makePermissionGate() as an inline
+// extension factory, and read by the shipped gate extension so it doesn't install a
+// SECOND one on top.
+//
+// The problem it solves: ~/.privateer/agent/extensions holds discovery shims for the
+// interactive TUI's extensions (installed by bin/privateer-launch.mjs). Pi discovers
+// them into every session built against that agentDir, and merges them with inline
+// factories — discovered FIRST, factories appended after (core/resource-loader.js).
+// extensions/privateer-gate.ts is one of those shims and it installs its own gate,
+// wired to the module-level RemoteBridge that only `/remote-access` ever attaches a
+// relay to. In a harbor / channels process that bridge is permanently unattached, so
+// the discovered copy believes every turn is LOCAL — and its cwd is process.cwd()
+// (the daemon's, not the session's) with a module-level allowlist shared across
+// concurrent sessions. What that costs depends on whether `session_start` fired,
+// which in Pi only happens if something calls bindExtensions():
+//   • a live task spawn DOES bind (for the relayed select/confirm), so the copy sees
+//     ctx.mode "print", flips itself to bypass, and only intervenes on dangerous
+//     shell / destructive / secret-exfil actions — where it asks through ctx.ui,
+//     which the spawn relays to the app as a SECOND dialog on top of the session
+//     gate's own approval for the same call;
+//   • the harbor's headless runs (routines, workflows, submitted tasks) and the
+//     channels runner never bind, so session_start never fires, the copy stays in
+//     "default" mode with no UI, and defaultLocalAsk fails closed — DENYING every
+//     gated tool before the session's real approver is ever consulted.
+// Neither is what these entries want: they each wire a gate that knows their cwd and
+// their approver.
+//
+// INVARIANT: set this ONLY from a path that installs makePermissionGate() itself.
+// Marking a process that doesn't would leave its sessions ungated.
+//
+// `privateer acp` solves the same collision differently — `noExtensions: true`, so
+// nothing is discovered at all (see src/acp/run.ts) — and needs no marker.
+//
+// An env var rather than a module singleton on purpose: discovered extensions load
+// through jiti with its module cache off, so they may hold a SEPARATE copy of our
+// modules. process.env is the one piece of state both copies are guaranteed to share.
+// It is inherited by child processes, which is why the shim pairs this check with
+// isSubagentChild() — a subagent child loads the moat explicitly (`-e`) and must keep
+// its own gate. See bin/privateer-subagent.mjs.
+//
+// IMPORT-SAFETY: no Pi imports, no node builtins — safe to load from anywhere.
+
+const ENV = "PRIVATEER_INLINE_MOAT";
+
+/** Called once by an entry that loads the moat as an in-code factory. Idempotent. */
+export function markInlineMoat(): void {
+  process.env[ENV] = "1";
+}
+
+/** True in a process whose sessions already carry their own in-code permission gate. */
+export function inlineMoat(): boolean {
+  return process.env[ENV] === "1";
+}
+
+/**
+ * Should a DISCOVERED gate extension install its permission gate in this process?
+ *
+ * No when the session already has one from an inline factory — EXCEPT in a subagent
+ * child, which inherits the parent's environment but loads this extension explicitly
+ * (`-e`, bin/privateer-subagent.mjs) as its ONLY moat. Getting that carve-out wrong
+ * runs a harbor task's children with no gate at all, so it is a parameter rather than
+ * an env read here: the caller passes isSubagentChild() and the matrix is testable.
+ */
+export function discoveredGateApplies(isSubagentChild: boolean): boolean {
+  return !inlineMoat() || isSubagentChild;
+}

package/src/ext/headlessUi.ts

@@ -0,0 +1,116 @@
+/**
+ * A COMPLETE ExtensionUIContext for surfaces that have no terminal UI.
+ *
+ * Pi decides `ctx.hasUI` by identity — `hasUI() { return this.uiContext !== noOpUIContext }`
+ * (pi-coding-agent core/extensions/runner.js). So binding ANY object flips hasUI to true,
+ * and every extension that guards on `ctx.hasUI` then calls the FULL ExtensionUIContext
+ * surface on it. Our callers only ever implemented the four dialog methods they cared
+ * about (select/confirm/input/notify), which is how a harbor session ended up throwing
+ *
+ *     MCP initialization failed: ui.setStatus is not a function
+ *
+ * — pi-mcp-adapter saw hasUI true, called ctx.ui.setStatus() to draw its status bar, and
+ * the whole MCP init aborted, taking every connector's tools with it. The session still
+ * ran; it just silently had no MCP tools.
+ *
+ * The fix is to always hand Pi a complete context: no-op defaults for the presentational
+ * surface (status bars, widgets, footers, editor manipulation — none of which mean
+ * anything without a terminal), the caller's real implementations for the dialogs that
+ * relay to the app, and a Proxy backstop so a method added by a future Pi release
+ * degrades to a no-op instead of crashing extension init all over again.
+ *
+ * Deliberately NOT a security boundary: hasUI stays true for these callers exactly as
+ * before. The permission gate (ext/permissionGate.ts) makes its own hasUI/ui check and
+ * fails closed on its own terms — nothing here loosens that.
+ */
+
+// The presentational half of ExtensionUIContext, mirroring pi-coding-agent's private
+// noOpUIContext. Kept as data (not a class) so `createUIContext` can spread it.
+const NO_OP_UI = {
+  select: async () => undefined,
+  confirm: async () => false,
+  input: async () => undefined,
+  notify: () => {},
+  onTerminalInput: () => () => {},
+  setStatus: () => {},
+  setWorkingMessage: () => {},
+  setWorkingVisible: () => {},
+  setWorkingIndicator: () => {},
+  setHiddenThinkingLabel: () => {},
+  setWidget: () => {},
+  setFooter: () => {},
+  setHeader: () => {},
+  setTitle: () => {},
+  custom: async () => undefined,
+  pasteToEditor: () => {},
+  setEditorText: () => {},
+  getEditorText: () => "",
+  editor: async () => undefined,
+  addAutocompleteProvider: () => {},
+  setEditorComponent: () => {},
+  getEditorComponent: () => undefined,
+  getAllThemes: () => [],
+  getTheme: () => undefined,
+  setTheme: () => ({ success: false, error: "UI not available" }),
+  getToolsExpanded: () => false,
+  setToolsExpanded: () => {},
+};
+
+/**
+ * A passthrough stand-in for Pi's Theme singleton, which lives behind a deep path the
+ * package's `exports` map doesn't expose (and `initTheme()` returns void — it only
+ * initializes that private singleton). Extensions call `ui.theme.fg("accent", text)` to
+ * colorize, so the shape has to exist.
+ *
+ * Returning the text unstyled is the RIGHT answer here rather than a lossy stub: this
+ * context is used where output goes to a log file or across the relay to the app's feed,
+ * and injected ANSI escapes would be noise in the first case and are actively unwanted in
+ * the second (the CLI already redacts/escapes what crosses that wire).
+ */
+export const passthroughTheme = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+  italic: (text: string) => text,
+  underline: (text: string) => text,
+  inverse: (text: string) => text,
+  strikethrough: (text: string) => text,
+  getFgAnsi: () => "",
+  getBgAnsi: () => "",
+  getColorMode: () => "256color" as const,
+  getThinkingBorderColor: () => (s: string) => s,
+  getBashModeBorderColor: () => (s: string) => s,
+};
+
+// Any property we didn't anticipate resolves to a no-op function. Extensions call UI
+// members as methods, so a callable is the shape that keeps them running; the cost of
+// guessing wrong is a missing visual, versus a thrown TypeError that aborts init.
+const unknownMember = () => () => undefined;
+
+/**
+ * Build a full ExtensionUIContext from the dialog methods a caller actually implements.
+ *
+ * `overrides` typically carries select/confirm/input/notify wired to the relay (so an
+ * extension asking a question reaches the app instead of silently cancelling). Everything
+ * else falls back to a no-op, and `theme` to `passthroughTheme`.
+ *
+ * Returns `any` because our overrides are structurally narrower than Pi's interface
+ * (its dialog signatures carry TUI-only option types); the call sites already pass this
+ * through `bindExtensions({ uiContext })` untyped.
+ */
+export function createUIContext(overrides: Record<string, unknown> = {}): any {
+  const target: Record<string, unknown> = { ...NO_OP_UI, theme: passthroughTheme, ...overrides };
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (prop in obj) return Reflect.get(obj, prop, receiver);
+      // `then` must stay undefined or an await on this object would treat it as a
+      // thenable and hang; same for other well-known symbol-ish probes.
+      if (typeof prop === "symbol" || prop === "then") return undefined;
+      return unknownMember();
+    },
+    // Deliberately NO `has` trap. Trapping it to always-true would make `in` claim we
+    // implement things we don't, which silently defeats capability checks of the shape
+    // `if (!("x" in ui)) fallback()`. Leaving it honest means `in` reports what is really
+    // implemented while `get` still guarantees a call never throws — the safe pairing.
+  });
+}

package/src/harbor/buildLock.ts

@@ -0,0 +1,19 @@
+// Session CONSTRUCTION is serialized across the whole process. pi-mcp-adapter decides
+// which MCP tools to register directly at extension-activation time, and the only knob
+// for that is the MCP_DIRECT_TOOLS env var — process-global state we set per run to
+// keep each unattended session to its own connector allow-list. Serializing the
+// (short) build window is what stops two concurrent builds from reading each other's
+// value. Prompting is NOT serialized — only the build.
+//
+// Lifted out of harbor/index.ts so the channels runtime can share the SAME lock once
+// it runs inside the harbor: two owners each with their own lock would serialize
+// against themselves and race against each other, which is exactly the bug the lock
+// exists to prevent.
+
+let buildLock: Promise<unknown> = Promise.resolve();
+
+export function serializeBuild<T>(fn: () => Promise<T>): Promise<T> {
+  const run = buildLock.then(fn, fn);
+  buildLock = run.catch(() => {});
+  return run;
+}

package/src/harbor/index.ts

@@ -59,8 +59,10 @@ import { deliver, type RelayPusher, type CloudPusher } from "../routines/deliver
 import { sealJson, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
+import { serializeBuild } from "./buildLock.ts";
 import { isHosted, publishRelayPub, webEnabled } from "../config/hosted.ts";
 import { markHarborDaemon } from "../config/harborDaemon.ts";
+import { markInlineMoat } from "../config/inlineMoat.ts";
 import { makeWebTools, WEB_TOOL_NAMES } from "../tools/web.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
@@ -157,18 +159,8 @@ function formatResult(routine: Routine, body: string, status: "ok" | "error", er
   return `${head}${body.trim() || "(no output)"}\n${formatNotes(notes)}`;
 }
 
-// Session CONSTRUCTION is serialized across the harbor. pi-mcp-adapter decides which
-// MCP tools to register directly at extension-activation time, and the only knob for
-// that is the MCP_DIRECT_TOOLS env var — process-global state we set per run to keep
-// each unattended session to its own connector allow-list. Serializing the (short)
-// build window is what stops two concurrent routines from reading each other's value.
-// Prompting is NOT serialized — only the build.
-let buildLock: Promise<unknown> = Promise.resolve();
-function serializeBuild<T>(fn: () => Promise<T>): Promise<T> {
-  const run = buildLock.then(fn, fn);
-  buildLock = run.catch(() => {});
-  return run;
-}
+// Session construction is serialized process-wide — see harbor/buildLock.ts for why.
+// Imported rather than defined here so the channels runtime can share the same lock.
 
 // A short human title for an ad-hoc task: the app's explicit title, else the first
 // non-empty line of the prompt, clipped. Exported for the signed-args round-trip test.
@@ -289,6 +281,11 @@ export class Harbor {
     // gate one has to stand its relay file tools down here so a live task's own pair
     // (bound to that task's live relay) isn't shadowed. See config/harborDaemon.ts.
     markHarborDaemon();
+    // Same reason, one step further: every session this process builds (routines,
+    // workflows, submitted tasks, live spawns) wires its own makePermissionGate, so
+    // the discovered gate must not install a second one on top of it. See
+    // config/inlineMoat.ts for what that collision costs.
+    markInlineMoat();
     // Single-instance lock FIRST, before any other side effect: binding the IPC
     // socket is the machine's mutex. If a live harbor already holds it this throws
     // HarborAlreadyRunningError — two harbors under one ~/.privateer share a single

package/src/nostr/bech32.ts

@@ -0,0 +1,117 @@
+// bech32 (BIP-173) — just enough of it for NIP-19's `npub` / `nsec` key encodings.
+//
+// WHY HAND-ROLLED: this repo's channel stack advertises zero new dependencies and
+// means it. bech32 is a fully specified, ~70-line checksum with published test
+// vectors, and we need exactly two human-readable parts and no TLV forms — none of
+// the `nprofile`/`nevent` machinery a general NIP-19 library carries. The tests in
+// tests/nostr.test.ts drive the published vectors both directions.
+//
+// This is bech32, NOT bech32m: NIP-19 predates bech32m and uses the original
+// constant 1. The two differ only in that final XOR, and getting it wrong produces
+// strings that look right and fail everywhere else.
+//
+// BIP-173's 90-character total length cap is deliberately NOT enforced — NIP-19
+// explicitly drops it. `npub` is 63 characters so it makes no difference today, but
+// enforcing it would be a landmine for any longer form added later.
+
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+
+function polymod(values: number[]): number {
+  let chk = 1;
+  for (const v of values) {
+    const top = chk >> 25;
+    chk = ((chk & 0x1ffffff) << 5) ^ v;
+    for (let i = 0; i < 5; i++) if ((top >> i) & 1) chk ^= GENERATOR[i];
+  }
+  return chk;
+}
+
+// The HRP contributes its high bits, then a separator zero, then its low bits.
+function hrpExpand(hrp: string): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < hrp.length; i++) out.push(hrp.charCodeAt(i) >> 5);
+  out.push(0);
+  for (let i = 0; i < hrp.length; i++) out.push(hrp.charCodeAt(i) & 31);
+  return out;
+}
+
+// Regroup a bit stream, e.g. 8-bit bytes → 5-bit symbols and back. When padding is
+// allowed (encoding) a partial final group is zero-padded; when it isn't (decoding)
+// a partial group must be zero or the input is malformed.
+function convertBits(data: ArrayLike<number>, from: number, to: number, pad: boolean): number[] | null {
+  let acc = 0;
+  let bits = 0;
+  const out: number[] = [];
+  const maxv = (1 << to) - 1;
+  for (let i = 0; i < data.length; i++) {
+    const value = data[i];
+    if (value < 0 || value >> from !== 0) return null;
+    acc = (acc << from) | value;
+    bits += from;
+    while (bits >= to) {
+      bits -= to;
+      out.push((acc >> bits) & maxv);
+    }
+  }
+  if (pad) {
+    if (bits > 0) out.push((acc << (to - bits)) & maxv);
+  } else if (bits >= from || ((acc << (to - bits)) & maxv) !== 0) {
+    return null;
+  }
+  return out;
+}
+
+export function bech32Encode(hrp: string, bytes: Uint8Array): string {
+  const words = convertBits(bytes, 8, 5, true);
+  if (!words) throw new Error("bech32: cannot convert payload to 5-bit words");
+  const chk = polymod([...hrpExpand(hrp), ...words, 0, 0, 0, 0, 0, 0]) ^ 1;
+  const checksum: number[] = [];
+  for (let i = 0; i < 6; i++) checksum.push((chk >> (5 * (5 - i))) & 31);
+  return `${hrp}1${[...words, ...checksum].map((w) => CHARSET[w]).join("")}`;
+}
+
+/** Decode, throwing on any malformed input. Never returns partial or truncated data. */
+export function bech32Decode(s: string): { hrp: string; bytes: Uint8Array } {
+  // Mixed case is explicitly invalid — it would make the checksum ambiguous.
+  if (s !== s.toLowerCase() && s !== s.toUpperCase()) throw new Error("bech32: mixed case");
+  const lower = s.toLowerCase();
+  const sep = lower.lastIndexOf("1");
+  if (sep < 1 || sep + 7 > lower.length) throw new Error("bech32: malformed (no separator or too short)");
+  const hrp = lower.slice(0, sep);
+  const words: number[] = [];
+  for (const ch of lower.slice(sep + 1)) {
+    const v = CHARSET.indexOf(ch);
+    if (v === -1) throw new Error(`bech32: invalid character "${ch}"`);
+    words.push(v);
+  }
+  if (polymod([...hrpExpand(hrp), ...words]) !== 1) throw new Error("bech32: bad checksum");
+  const bytes = convertBits(words.slice(0, -6), 5, 8, false);
+  if (!bytes) throw new Error("bech32: bad padding");
+  return { hrp, bytes: Uint8Array.from(bytes) };
+}
+
+// ── NIP-19: the two bare key forms ──────────────────────────────────────────────
+
+function decodeKey(s: string, expectHrp: string): Uint8Array {
+  const { hrp, bytes } = bech32Decode(s);
+  if (hrp !== expectHrp) throw new Error(`expected an ${expectHrp} key, got "${hrp}"`);
+  if (bytes.length !== 32) throw new Error(`expected 32 key bytes, got ${bytes.length}`);
+  return bytes;
+}
+
+export function npubEncode(pubkeyBytes: Uint8Array): string {
+  return bech32Encode("npub", pubkeyBytes);
+}
+
+export function npubDecode(npub: string): Uint8Array {
+  return decodeKey(npub, "npub");
+}
+
+export function nsecEncode(secretBytes: Uint8Array): string {
+  return bech32Encode("nsec", secretBytes);
+}
+
+export function nsecDecode(nsec: string): Uint8Array {
+  return decodeKey(nsec, "nsec");
+}

package/src/nostr/event.ts

@@ -0,0 +1,92 @@
+// NIP-01 event construction, identity and signatures — the whole cryptographic
+// core of the Nostr wire format in one dependency-free file.
+//
+// Nothing here knows about relays, channels, or Buzz. It is pure: same inputs, same
+// bytes out, no clock, no I/O. That's what makes the known-answer tests in
+// tests/nostr.test.ts meaningful — if serializeEvent drifts by a single character,
+// every id in the fixture set stops recomputing.
+//
+// The primitives come from @noble/curves, already a direct dependency: Nostr signs
+// with BIP-340 Schnorr over secp256k1, which is exactly what `schnorr` provides.
+
+import { schnorr } from "@noble/curves/secp256k1";
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+
+// A tag is a positional string array: ["e", <id>, <relay?>, <marker?>].
+export type Tag = string[];
+
+// An event before it has an id or a signature. `pubkey` is the 32-byte x-only
+// public key as lowercase hex (64 chars) — NOT the 33-byte compressed form.
+export interface UnsignedEvent {
+  pubkey: string;
+  created_at: number; // unix SECONDS, not millis
+  kind: number;
+  tags: Tag[];
+  content: string;
+}
+
+export interface NostrEvent extends UnsignedEvent {
+  id: string; // 64-char hex — sha256 of serializeEvent()
+  sig: string; // 128-char hex — BIP-340 Schnorr over the id bytes
+}
+
+/**
+ * The NIP-01 serialization an event's id is computed over: a POSITIONAL array, not
+ * an object. Field order is fixed by the spec and is not negotiable.
+ *
+ * NIP-01 mandates escaping only `\n \" \\ \r \t \b \f` and requires no other
+ * escaping — which is precisely what JSON.stringify does for ordinary text. The two
+ * diverge only on exotic control characters and lone surrogates, where every real
+ * implementation follows JSON.stringify anyway. We do the same, deliberately.
+ */
+export function serializeEvent(u: UnsignedEvent): string {
+  return JSON.stringify([0, u.pubkey, u.created_at, u.kind, u.tags, u.content]);
+}
+
+/** The event id: sha256 of the canonical serialization, lowercase hex. */
+export function eventId(u: UnsignedEvent): string {
+  return bytesToHex(sha256(utf8ToBytes(serializeEvent(u))));
+}
+
+/**
+ * Compute the id and sign it.
+ *
+ * `auxRand` exists ONLY so tests can reproduce the published BIP-340 vectors —
+ * schnorr.sign is randomized by default, so without it a signature is unpredictable
+ * (which is correct and desirable in production). Never pass it outside tests.
+ */
+export function signEvent(u: UnsignedEvent, secretKeyHex: string, auxRand?: Uint8Array): NostrEvent {
+  const id = eventId(u);
+  const sig = bytesToHex(schnorr.sign(hexToBytes(id), hexToBytes(secretKeyHex), auxRand));
+  return { ...u, id, sig };
+}
+
+/**
+ * Verify an event end to end, fail-closed on anything malformed.
+ *
+ * BOTH checks matter and the order is deliberate: recompute the id first, so a
+ * tampered `content` or `tags` is caught even when the signature over the ORIGINAL
+ * id is still perfectly valid. Verifying only the signature would happily accept an
+ * event whose body had been swapped out from under its id.
+ */
+export function verifyEvent(ev: NostrEvent): boolean {
+  try {
+    if (
+      typeof ev?.id !== "string" ||
+      typeof ev.sig !== "string" ||
+      typeof ev.pubkey !== "string" ||
+      typeof ev.content !== "string" ||
+      typeof ev.kind !== "number" ||
+      typeof ev.created_at !== "number" ||
+      !Array.isArray(ev.tags)
+    ) {
+      return false;
+    }
+    if (ev.id.length !== 64 || ev.sig.length !== 128 || ev.pubkey.length !== 64) return false;
+    if (eventId(ev) !== ev.id) return false;
+    return schnorr.verify(hexToBytes(ev.sig), hexToBytes(ev.id), hexToBytes(ev.pubkey));
+  } catch {
+    return false;
+  }
+}