@estiva-app/protocol 0.1.0

package/dist/sign.js

@@ -0,0 +1,58 @@
+/**
+ * BIP-340 Schnorr signing, and the signer seam every publish path goes through.
+ *
+ * Signing needs entropy (`@noble/curves` draws auxiliary randomness per
+ * signature), so `signEvent` only works where a CSPRNG is available — a browser,
+ * Node, Convex's Node runtime. That is a *runtime* requirement rather than a type
+ * one: nothing here reads a global, and importing this module is safe anywhere.
+ *
+ * ## What is deliberately not here
+ *
+ * `estivaIdSigner` — the signer that posts to Estiva ID's `/sign` and holds no
+ * key at all — is **identity**, and belongs to `@estiva-app/identity` (SHA-4).
+ * This package defines the {@link Signer} interface it will implement, because
+ * the relay clients need something to sign with and the interface is the seam
+ * between "the bytes" and "who is allowed to sign them". Keeping the interface
+ * here and the implementations there is what stops `protocol` growing a
+ * dependency on an identity service.
+ */
+import { schnorr } from '@noble/curves/secp256k1';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { computeEventId } from './events.js';
+/** Derive the 64-char hex x-only public key for a secret key. */
+export function publicKeyFromSecret(secretKeyHex) {
+    return bytesToHex(schnorr.getPublicKey(hexToBytes(secretKeyHex)));
+}
+/**
+ * Compute the event id and sign it, producing a relay-submittable event.
+ *
+ * Throws if `unsigned.pubkey` does not match the secret key — a mismatch would
+ * produce an event the relay silently rejects as an invalid signature, which is
+ * painful to debug from the other side.
+ */
+export function signEvent(unsigned, secretKeyHex) {
+    const derived = publicKeyFromSecret(secretKeyHex);
+    if (derived !== unsigned.pubkey) {
+        throw new Error(`pubkey mismatch: event declares ${unsigned.pubkey.slice(0, 16)}… but the secret key derives ${derived.slice(0, 16)}…`);
+    }
+    const id = computeEventId(unsigned);
+    const sig = bytesToHex(schnorr.sign(id, hexToBytes(secretKeyHex)));
+    return { ...unsigned, id, sig };
+}
+/**
+ * A signer holding a raw secret key.
+ *
+ * The honest name for what a script has always done. Used directly by scripts,
+ * which have no `localStorage`, and underneath an app's per-browser identity.
+ */
+export function secretKeySigner(secretKeyHex, kind = 'local') {
+    const pubkey = publicKeyFromSecret(secretKeyHex);
+    return {
+        pubkey,
+        kind,
+        async sign(unsigned) {
+            return signEvent({ ...unsigned, pubkey }, secretKeyHex);
+        },
+    };
+}
+//# sourceMappingURL=sign.js.map

package/dist/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAwC,MAAM,aAAa,CAAA;AAElF,iEAAiE;AACjE,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,OAAO,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAuB,EAAE,YAAoB;IACrE,MAAM,OAAO,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAA;IACjD,IAAI,OAAO,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,mCAAmC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,gCAAgC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CACvH,CAAA;IACH,CAAC;IACD,MAAM,EAAE,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IACnC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IAClE,OAAO,EAAE,GAAG,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,CAAA;AACjC,CAAC;AAqDD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB,EAAE,OAAmB,OAAO;IAC9E,MAAM,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAA;IAChD,OAAO;QACL,MAAM;QACN,IAAI;QACJ,KAAK,CAAC,IAAI,CAAC,QAAQ;YACjB,OAAO,SAAS,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,CAAA;QACzD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/subscriptions.d.ts

@@ -0,0 +1,120 @@
+/**
+ * One REQ per channel, refcounted (PEE-6).
+ *
+ * Two components can be looking at the same channel — the conversation and the
+ * sidebar — and the last one to unmount is the one that should close the REQ.
+ * This sits over `liveRelay` and owns exactly that: one relay subscription per
+ * channel uuid, shared by every consumer, closed when the last releases.
+ *
+ * Reconnection is deliberately **not** handled here. `createLiveRelay` re-issues
+ * every registered subscription after it re-authenticates, so a channel with a
+ * live refcount comes back on its own. Duplicating that logic would give two
+ * places to get it wrong.
+ *
+ * **Built inside Peek** (PEE-6) because Gate 2 had not happened when it was due.
+ * SHA-3 is the ticket that owed the move.
+ *
+ * ## The trap: one subscription per channel, always
+ *
+ * **Never build one subscription covering several channels.** Depending on the
+ * filter it either fails loudly or, worse, returns correct history and then
+ * receives **zero live events** — EOSE right, live empty, nothing to
+ * distinguish it from working until somebody notices nothing ever arrives.
+ *
+ * Verified in Buzz rather than taken on trust, because the whole point is that
+ * it is invisible:
+ *
+ *   1. `extract_channel_id_from_filters` (`handlers/req.rs`) returns `None` the
+ *      moment two distinct `#h` values appear, or any filter lacks `#h`.
+ *   2. With `channel_id: None` the subscription registers in the **global**
+ *      indexes (`subscription.rs`).
+ *   3. `fan_out_scoped` handles a channel-scoped event by consulting only
+ *      `channel_kind_index` and `channel_wildcard_index`. A global subscription
+ *      is in neither.
+ *   4. The file states it outright: *"Global subscriptions (channel_id = None)
+ *      do NOT receive channel-scoped events."*
+ *
+ * Historical delivery at REQ time takes a different path (`per_filter_channel`)
+ * which handles multi-`#h` correctly. That asymmetry is the whole illusion.
+ *
+ * **Which of the two failures you get depends on whether the filter names
+ * kinds**, and this was measured against production rather than reasoned about.
+ * A global subscription must clear `p_gated_filters_authorized`
+ * (`handlers/req.rs`), whose first test is:
+ *
+ *     let can_match_p_gated = filter.kinds.as_ref().is_none_or(|ks| …);
+ *     if !can_match_p_gated { return true; }
+ *
+ * So a **kindless** multi-`#h` filter *could* match a p-gated kind, has no
+ * `#p`, and is refused outright — a live probe against
+ * `wss://estiva.estiva.app` got `CLOSED … "restricted: p-gated events require
+ * #p matching your pubkey"` immediately. But a filter naming only ordinary
+ * kinds — `{"#h":[a,b],"kinds":[9]}` — returns early as authorized, registers
+ * globally, and dies **silently**.
+ *
+ * That is the dangerous one, and it is the shape somebody optimising "one
+ * subscription for messages across all my channels" would naturally write. The
+ * ticket describes this variant; the loud one is a newer gate sitting in front
+ * of it.
+ *
+ * **There is a second entrance to the same trap, and it is the likelier one.**
+ * `extract_channel_id_from_filters` only counts an `#h` value it can
+ * `parse::<uuid::Uuid>()`; anything else leaves `filter_has_channel` false and
+ * falls through to the same global registration. So passing a **topic id**
+ * where a channel uuid belongs produces the same broken subscription — and
+ * Peek's topic ids are Convex ids, which are not uuids. Because this module
+ * always builds a kindless filter, that lands on the loud arm above rather than
+ * the silent one; it is still a subscription that never delivers, and it still
+ * fails asynchronously as a `CLOSED` frame the app would have to interpret.
+ * Throwing at the call site names the cause instead. RFC 0.3's note on this ticket
+ * asks specifically that a topic id never become the subscription key; that is
+ * why {@link createChannelSubscriptions} validates the shape and throws rather
+ * than letting a bad key reach the relay. In Peek `topics.channelUuid` is also
+ * `v.optional`, so "absent on older topics" is a real case, not a theoretical
+ * one, and it must not arrive here as `undefined`.
+ *
+ * ## One kindless filter is enough
+ *
+ * `{"#h":[uuid]}` with no `kinds` registers in the channel **wildcard** index
+ * and therefore receives every kind in the channel. Reactions (kind:7) and
+ * deletions (kind:5) carry no `h` tag of their own, but `filters_match`
+ * (`buzz-core/src/filter.rs`) falls back to `StoredEvent.channel_id` for `#h`
+ * when an event has no `h` tags at all — the channel is derived from the target
+ * at ingest. So messages, reactions, deletions and assertions all arrive on this
+ * one subscription.
+ *
+ * That is strictly better than the HTTP path it replaces, which needs four
+ * sequential round trips and caps reactions to the newest 100 messages per
+ * topic. The cap is deliberately not ported.
+ *
+ * `kinds: []` would be worse than useless — Buzz indexes such a subscription
+ * *nowhere* and it silently receives nothing — which is another reason this
+ * builds the filter itself rather than accepting one.
+ */
+import type { SignedEvent } from './events.js';
+import type { LiveRelay } from './live.js';
+export type ChannelEventHandler = (event: SignedEvent) => void;
+export interface ChannelSubscription {
+    /** Idempotent. Closes the REQ only when the last consumer releases. */
+    release(): void;
+}
+export interface ChannelSubscriptions {
+    /**
+     * Watch one channel. Safe to call many times for the same channel — the
+     * relay sees one REQ, and every consumer sees every event.
+     *
+     * @throws if `channelUuid` is not a uuid. See the trap above: a topic id here
+     * would be accepted by the relay and then silently deliver nothing.
+     */
+    subscribe(channelUuid: string, onEvent: ChannelEventHandler): ChannelSubscription;
+    /** Channels with at least one live consumer. Test and diagnostic seam. */
+    activeChannels(): string[];
+    /** How many consumers hold `channelUuid`. Test and diagnostic seam. */
+    subscriberCount(channelUuid: string): number;
+    /** Release everything. Does not close the underlying relay connection. */
+    close(): void;
+}
+export declare function createChannelSubscriptions(relay: Pick<LiveRelay, 'subscribe'>, options?: {
+    onListenerError?: (error: unknown) => void;
+}): ChannelSubscriptions;
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,WAAW,CAAA;AAKxD,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;AAE9D,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAAA;IACjF,0EAA0E;IAC1E,cAAc,IAAI,MAAM,EAAE,CAAA;IAC1B,uEAAuE;IACvE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5C,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAAA;CACd;AAOD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EACnC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GAC3D,oBAAoB,CAoEtB"}

package/dist/subscriptions.js

@@ -0,0 +1,68 @@
+/** Canonical v4-shaped uuid, as `crypto.randomUUID()` produces. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function createChannelSubscriptions(relay, options = {}) {
+    const channels = new Map();
+    function dispatch(channelUuid, event) {
+        const entry = channels.get(channelUuid);
+        if (!entry)
+            return;
+        // A copy, because a listener is allowed to release during dispatch — and
+        // one that throws must not stop the others from being told. A single
+        // component's bug should not silently stop the whole channel updating.
+        for (const listener of [...entry.listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                options.onListenerError?.(error);
+            }
+        }
+    }
+    return {
+        subscribe(channelUuid, onEvent) {
+            if (!UUID.test(channelUuid)) {
+                throw new Error(`channelSubscriptions: "${channelUuid}" is not a channel uuid. ` +
+                    'Buzz can only scope a subscription by an #h it can parse as a uuid; ' +
+                    'anything else registers globally and then receives no channel events at all. ' +
+                    "Pass the channel's uuid, never an application id for the thing " +
+                    'rendered in it — Peek\'s topic ids are Convex ids, which are not uuids.');
+            }
+            let entry = channels.get(channelUuid);
+            if (!entry) {
+                const listeners = new Set();
+                // One channel, one filter, no `kinds` — see the header. Built here
+                // rather than accepted from the caller so neither half of the trap is
+                // reachable through this API.
+                const relaySub = relay.subscribe([{ '#h': [channelUuid] }], (event) => dispatch(channelUuid, event));
+                entry = { relaySub, listeners };
+                channels.set(channelUuid, entry);
+            }
+            entry.listeners.add(onEvent);
+            let released = false;
+            return {
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    const current = channels.get(channelUuid);
+                    if (!current)
+                        return;
+                    current.listeners.delete(onEvent);
+                    if (current.listeners.size > 0)
+                        return;
+                    // Last one out closes the REQ.
+                    channels.delete(channelUuid);
+                    current.relaySub.close();
+                },
+            };
+        },
+        activeChannels: () => [...channels.keys()],
+        subscriberCount: (channelUuid) => channels.get(channelUuid)?.listeners.size ?? 0,
+        close() {
+            for (const entry of channels.values())
+                entry.relaySub.close();
+            channels.clear();
+        },
+    };
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAgGA,mEAAmE;AACnE,MAAM,IAAI,GAAG,iEAAiE,CAAA;AA+B9E,MAAM,UAAU,0BAA0B,CACxC,KAAmC,EACnC,UAA0D,EAAE;IAE5D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAA;IAEhD,SAAS,QAAQ,CAAC,WAAmB,EAAE,KAAkB;QACvD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QACvC,IAAI,CAAC,KAAK;YAAE,OAAM;QAClB,yEAAyE;QACzE,qEAAqE;QACrE,uEAAuE;QACvE,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAA;YACjB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,CAAA;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS,CAAC,WAAW,EAAE,OAAO;YAC5B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,0BAA0B,WAAW,2BAA2B;oBAC9D,sEAAsE;oBACtE,+EAA+E;oBAC/E,iEAAiE;oBACjE,yEAAyE,CAC5E,CAAA;YACH,CAAC;YAED,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAA;gBAChD,mEAAmE;gBACnE,sEAAsE;gBACtE,8BAA8B;gBAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CACpE,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,CAC7B,CAAA;gBACD,KAAK,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;gBAC/B,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;YAClC,CAAC;YACD,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAE5B,IAAI,QAAQ,GAAG,KAAK,CAAA;YACpB,OAAO;gBACL,OAAO;oBACL,IAAI,QAAQ;wBAAE,OAAM;oBACpB,QAAQ,GAAG,IAAI,CAAA;oBACf,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;oBACzC,IAAI,CAAC,OAAO;wBAAE,OAAM;oBACpB,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;oBACjC,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC;wBAAE,OAAM;oBACtC,+BAA+B;oBAC/B,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;oBAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;gBAC1B,CAAC;aACF,CAAA;QACH,CAAC;QAED,cAAc,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC1C,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC;QAEhF,KAAK;YACH,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE;gBAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;YAC7D,QAAQ,CAAC,KAAK,EAAE,CAAA;QAClB,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@estiva-app/protocol",
+  "version": "0.1.0",
+  "description": "The Estiva wire format: Buzz-shaped Nostr event builders, NIP-01 ids, NIP-19 naddr, NIP-98 HTTP auth, and the relay clients. Speaks the protocol; interprets nothing.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/estiva-app/estiva-foundation.git",
+    "directory": "packages/protocol"
+  },
+  "keywords": [
+    "nostr",
+    "nip-01",
+    "nip-19",
+    "nip-98",
+    "buzz",
+    "estiva"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run build",
+    "verify:live": "node scripts/verify-live.mjs"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.2",
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "nostr-tools": "^2.25.0",
+    "typescript": "~5.9.3",
+    "@types/node": "^24.13.3"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,198 @@
+/**
+ * Buzz's HTTP bridge — `POST /events`, `POST /query` — with NIP-98 auth.
+ *
+ * Behaviours here were established against a running relay, not inferred. Three
+ * that bite, and the first is the one that makes a green deploy lie:
+ *
+ *  - **HTTP 200 does not mean accepted.** A duplicate channel create returns
+ *    `200 {"accepted":false,"message":"duplicate: channel already exists"}`.
+ *    The `accepted` field is authoritative and the status code alone would read
+ *    rejections as successes. This is SPEC §5's C3 conformance check.
+ *  - **`/query` takes a bare ARRAY of filters**, not a single filter object.
+ *    Sending one object gets `invalid type: map, expected a sequence`.
+ *  - **A non-member read is answered `403 relay_membership_required`.** There is
+ *    no backend identity that can see anything, which is why reads are
+ *    viewer-driven.
+ *
+ * ## The parsers are exported separately, and that is the point
+ *
+ * {@link parsePublishResponse} and {@link parseQueryResponse} existed twice
+ * before SHA-3 — once in Peek's browser bridge, once in Ship's `Relay` — with
+ * the same `accepted` handling written out both times. They are exported on
+ * their own so an app with its own transport (Peek signs its auth event through
+ * Estiva ID, which is `@estiva-app/identity`'s job, not this package's) still
+ * shares the *interpretation of the answer*. Getting the bytes right and then
+ * reading `200` as success is a way to fail that no test notices.
+ */
+import { authorizationHeader } from './nip98.js'
+import type { SignedEvent } from './events.js'
+import type { Signer } from './sign.js'
+
+export interface PublishResult {
+  ok: boolean
+  eventId?: string
+  reason?: string
+  /** The relay already had this state — not a failure. */
+  duplicate?: boolean
+  /** The HTTP status, for a caller that wants to distinguish 403 from 500. */
+  httpStatus?: number
+}
+
+/**
+ * The relay's answer to `POST /events`, interpreted.
+ *
+ * `duplicate` is reported as `ok`: "already exists" is the desired end state, so
+ * a caller creating a channel that is already there has succeeded. Every other
+ * `accepted: false` is a failure the caller must surface — SPEC §9's C9, which
+ * is not decoration: once no app can sign locally, an identity-service outage
+ * looks exactly like nothing happening.
+ */
+export function parsePublishResponse(status: number, text: string): PublishResult {
+  let parsed: { accepted?: boolean; event_id?: string; message?: string; error?: string }
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return { ok: false, reason: `unparseable response: ${text.slice(0, 200)}`, httpStatus: status }
+  }
+  if (status < 200 || status >= 300) {
+    return { ok: false, reason: parsed.error ?? text.slice(0, 200), httpStatus: status }
+  }
+  if (parsed.accepted === false) {
+    const duplicate = (parsed.message ?? '').startsWith('duplicate:')
+    return { ok: duplicate, duplicate, eventId: parsed.event_id, reason: parsed.message, httpStatus: status }
+  }
+  return { ok: true, eventId: parsed.event_id, httpStatus: status }
+}
+
+export interface QueryResult {
+  ok: boolean
+  events: SignedEvent[]
+  reason?: string
+  httpStatus?: number
+}
+
+/** The relay's answer to `POST /query`, interpreted. */
+export function parseQueryResponse(status: number, text: string): QueryResult {
+  if (status < 200 || status >= 300) {
+    let reason = text.slice(0, 200)
+    try {
+      reason = JSON.parse(text).error ?? reason
+    } catch {
+      // keep the raw text
+    }
+    return { ok: false, events: [], reason, httpStatus: status }
+  }
+  try {
+    const parsed = JSON.parse(text)
+    return { ok: true, events: Array.isArray(parsed) ? parsed : [], httpStatus: status }
+  } catch {
+    return { ok: false, events: [], reason: `unparseable response: ${text.slice(0, 200)}`, httpStatus: status }
+  }
+}
+
+/**
+ * Just enough of `fetch` to post a body and read the answer.
+ *
+ * A parameter rather than an ambient global, per ADR 0002 §4a — `fetch` is in
+ * neither `lib.es2022` nor a package that may assume `lib.dom`. The default
+ * below reads the runtime's own, so no consumer has to pass one.
+ */
+export type FetchLike = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ status: number; text(): Promise<string> }>
+
+/** See {@link FetchLike}. Read inside a method, so importing touches no global. */
+declare const fetch: FetchLike
+
+/** Extra headers to send with every relay request, resolved per request. */
+export type RelayHeaders = () => Record<string, string> | Promise<Record<string, string>>
+
+export interface RelayOptions {
+  /**
+   * ## Why `headers` is a callback
+   *
+   * Buzz reads more than NIP-98 off a request. A NIP-OA owner attestation travels
+   * in `x-auth-tag`, and on a closed relay it is what admits an agent whose
+   * *owner* is a member — so it is required on **every** call, `/query` included,
+   * not just on writes.
+   *
+   * A callback rather than a fixed object because what it carries can expire: an
+   * agent's attestation is minted with its token and replaced when that token is
+   * renewed. A snapshot taken at construction would work for one TTL and then
+   * fail as a `403 relay_membership_required` that looks nothing like an expiry.
+   *
+   * Empty by default, so an app with no such credential is unaffected.
+   */
+  headers?: RelayHeaders
+  /** Override the transport. Defaults to the runtime's `fetch`. */
+  fetch?: FetchLike
+}
+
+/**
+ * A relay client that signs its own NIP-98 auth.
+ *
+ * Takes a {@link Signer} rather than a key or a token, which is what lets the
+ * same class serve a script holding a secret key and a browser signing through a
+ * remote service.
+ */
+export class Relay {
+  private readonly url: string
+  private readonly signer: Signer
+  private readonly headers: RelayHeaders
+  private readonly transport: FetchLike | undefined
+
+  constructor(url: string, signer: Signer, options: RelayOptions | RelayHeaders = {}) {
+    this.url = url.replace(/\/+$/, '')
+    this.signer = signer
+    // A bare callback was the old second argument in Ship's client; accepting
+    // both keeps that call site working rather than making a behavioural change
+    // ride along with an extraction.
+    const opts: RelayOptions = typeof options === 'function' ? { headers: options } : options
+    this.headers = opts.headers ?? (() => ({}))
+    this.transport = opts.fetch
+  }
+
+  private async post(path: string, payload: unknown): Promise<{ status: number; text: string }> {
+    const url = `${this.url}${path}`
+    const body = JSON.stringify(payload)
+    const auth = await authorizationHeader(this.signer, { url, method: 'POST', body })
+    const send = this.transport ?? fetch
+    const res = await send(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(await this.headers()),
+        // Rebuilt per request AND unique per request — identical requests in the
+        // same second would otherwise collide on the auth event id and the relay
+        // rejects the second as a replay. See nip98.ts on the nonce.
+        //
+        // Listed after the spread so a caller's headers cannot displace it:
+        // authorization is this client's own contract with the relay, not
+        // something an ambient credential gets to override.
+        authorization: auth,
+      },
+      body,
+    })
+    return { status: res.status, text: await res.text() }
+  }
+
+  async publish(event: SignedEvent): Promise<PublishResult> {
+    const { status, text } = await this.post('/events', event)
+    return parsePublishResponse(status, text)
+  }
+
+  /**
+   * `filters` is an array — the bridge expects `Vec<Value>`.
+   *
+   * Throws on a transport-level failure rather than returning an empty array,
+   * because "no events" and "the relay refused you" are not the same answer and
+   * a caller that cannot tell them apart renders an empty screen either way.
+   */
+  async query(filters: Record<string, unknown>[]): Promise<SignedEvent[]> {
+    const { status, text } = await this.post('/query', filters)
+    const result = parseQueryResponse(status, text)
+    if (!result.ok) throw new Error(`query failed: ${result.reason}`)
+    return result.events
+  }
+}