@estiva-app/protocol 0.1.0

package/dist/nip19.js

@@ -0,0 +1,320 @@
+/**
+ * NIP-19 `naddr` — bech32-encoded pointers to addressable events.
+ *
+ * This is how an object gets *out of* the app that owns it and *into* another:
+ * Ship encodes an issue as `nostr:naddr1…`, somebody pastes it into a Peek
+ * message (NIP-21 for the URI scheme, NIP-27 for the convention of embedding one
+ * in a text body), and Peek resolves it back to an address.
+ *
+ * ## Two implementations, and they already agreed
+ *
+ * Before SHA-3 this existed twice: Ship wrote an encoder, Peek wrote a decoder,
+ * and each grew the other half later. Their outputs were checked byte for byte
+ * during the extraction and were **identical** for the same pointer — so this
+ * merge is a deduplication and not a reconciliation. What each copy had that the
+ * other lacked is all kept: Ship's generic bech32 primitives and
+ * `addrToNaddr`/`naddrToAddr`, Peek's `pointerToAddress`/`addressToPointer`,
+ * `referenceToPointer` and `stripNaddrs`.
+ *
+ * ## Three things about the format that are easy to get wrong
+ *
+ * **Not bech32m.** NIP-19 predates bech32m and uses the original constant
+ * (`^ 1`). Encoding with bech32m produces a string that looks right, passes a
+ * casual eyeball, and fails every other implementation's checksum. A round-trip
+ * test cannot catch it — it would be wrong in both directions — which is why
+ * `bech32Encode`/`bech32Decode` are exported and pinned against the canonical
+ * NIP-19 `npub` vector from the specification itself.
+ *
+ * **The 90-character limit does not apply.** BIP-173 caps a bech32 string at 90
+ * characters for QR-code reasons; an `naddr` carrying a UUID `d` tag, a 32-byte
+ * pubkey and a relay hint runs to ~180. NIP-19 explicitly lifts the cap, so no
+ * length check appears here.
+ *
+ * **TLV order is not normative, and other implementations differ.** This encoder
+ * emits identifier, relays, author, kind. `nostr-tools` emits a different order,
+ * so the same pointer encodes to a *different string* — measured. Every decoder
+ * involved (this one, Ship's old one, Peek's old one, `nostr-tools`) reads TLVs
+ * by type and is order-tolerant, so the strings interoperate; but they are not
+ * comparable as strings, and nothing here should ever compare two naddrs for
+ * equality. Compare the addresses they decode to.
+ */
+import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+function polymod(values) {
+    let chk = 1;
+    for (const value of values) {
+        const top = chk >>> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ value;
+        for (let i = 0; i < 5; i++) {
+            if ((top >>> i) & 1)
+                chk ^= GENERATOR[i];
+        }
+    }
+    return chk >>> 0;
+}
+function hrpExpand(hrp) {
+    const high = [];
+    const low = [];
+    for (const char of hrp) {
+        high.push(char.charCodeAt(0) >>> 5);
+        low.push(char.charCodeAt(0) & 31);
+    }
+    return [...high, 0, ...low];
+}
+function checksum(hrp, data) {
+    const values = [...hrpExpand(hrp), ...data, 0, 0, 0, 0, 0, 0];
+    // `^ 1` is bech32. bech32m would use `^ 0x2bc830a3` — see the note above.
+    const mod = polymod(values) ^ 1;
+    return [0, 1, 2, 3, 4, 5].map((i) => (mod >>> (5 * (5 - i))) & 31);
+}
+/** Regroup bytes between bit widths, e.g. 8-bit bytes → 5-bit bech32 symbols. */
+export function convertBits(data, from, to, pad) {
+    let acc = 0;
+    let bits = 0;
+    const out = [];
+    const maxv = (1 << to) - 1;
+    for (let i = 0; i < data.length; i++) {
+        const value = data[i];
+        if (value < 0 || value >> from !== 0)
+            throw new Error(`value out of range: ${value}`);
+        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) {
+        throw new Error('invalid padding');
+    }
+    return out;
+}
+/**
+ * Exported for the bare NIP-19 types (`npub`, `note`) and for tests.
+ *
+ * The checksum layer is the part worth testing directly: a wrong constant still
+ * round-trips against itself, so only an external vector catches it.
+ *
+ * Strict about case, deliberately — BIP-173 forbids mixing. `decodeNaddr` is the
+ * forgiving entry point, because what reaches it was typed or pasted by a person.
+ */
+export function bech32Encode(hrp, data) {
+    const combined = [...data, ...checksum(hrp, data)];
+    return `${hrp}1${combined.map((d) => CHARSET[d]).join('')}`;
+}
+export function bech32Decode(encoded) {
+    const lower = encoded.toLowerCase();
+    if (lower !== encoded && encoded.toUpperCase() !== encoded) {
+        throw new Error('mixed case bech32 string');
+    }
+    const split = lower.lastIndexOf('1');
+    if (split < 1 || split + 7 > lower.length)
+        throw new Error('malformed bech32 string');
+    const hrp = lower.slice(0, split);
+    const data = [];
+    for (const char of lower.slice(split + 1)) {
+        const index = CHARSET.indexOf(char);
+        if (index === -1)
+            throw new Error(`invalid bech32 character: ${char}`);
+        data.push(index);
+    }
+    if (polymod([...hrpExpand(hrp), ...data]) !== 1)
+        throw new Error('bad bech32 checksum');
+    return { hrp, data: data.slice(0, -6) };
+}
+/**
+ * TLV types for `naddr` (NIP-19 §"Shareable identifiers with extra metadata").
+ * The numbers are the protocol; the names are ours.
+ */
+const TLV_IDENTIFIER = 0;
+const TLV_RELAY = 1;
+const TLV_AUTHOR = 2;
+const TLV_KIND = 3;
+/**
+ * Encode an address as `naddr1…`.
+ *
+ * TLV order is identifier, relays, author, kind — see the header on why that is
+ * a choice rather than a rule.
+ */
+export function encodeNaddr(pointer) {
+    const bytes = [];
+    const push = (type, value) => {
+        if (value.length > 255)
+            throw new Error(`TLV value too long for type ${type}`);
+        bytes.push(type, value.length, ...value);
+    };
+    push(TLV_IDENTIFIER, utf8ToBytes(pointer.identifier));
+    for (const relay of pointer.relays)
+        push(TLV_RELAY, utf8ToBytes(relay));
+    // Peek's encoder checked the author's length and Ship's did not, and the
+    // difference is not cosmetic: `hexToBytes` is happy with any even-length hex,
+    // so a 20-byte author encoded into a *valid* naddr that every decoder then
+    // refused as "author must be 32 bytes". A pointer that cannot be read back is
+    // worse than an error, because it is produced silently and only fails at
+    // whoever pastes it. Peek's guard is the one that ships.
+    const author = hexToBytes(pointer.pubkey);
+    if (author.length !== 32)
+        throw new Error(`author must be 32 bytes, got ${author.length}`);
+    push(TLV_AUTHOR, author);
+    // Kind is a 4-byte big-endian integer, not a decimal string.
+    push(TLV_KIND, new Uint8Array([
+        (pointer.kind >>> 24) & 0xff,
+        (pointer.kind >>> 16) & 0xff,
+        (pointer.kind >>> 8) & 0xff,
+        pointer.kind & 0xff,
+    ]));
+    return bech32Encode('naddr', convertBits(bytes, 8, 5, true));
+}
+/**
+ * Decode `naddr1…`, with or without a `nostr:` prefix, in any case.
+ *
+ * Forgiving on purpose: what arrives here was pasted by a person, sometimes out
+ * of an email client that capitalised the first letter. `bech32Decode` is the
+ * strict primitive underneath — this lowercases first, so a mixed-case string
+ * that would be refused there is accepted here.
+ */
+export function decodeNaddr(encoded) {
+    const { hrp, data } = bech32Decode(encoded.replace(/^nostr:/i, '').toLowerCase());
+    if (hrp !== 'naddr')
+        throw new Error(`expected an naddr, got ${hrp}`);
+    const bytes = convertBits(data, 5, 8, false);
+    let identifier;
+    let pubkey;
+    let kind;
+    const relays = [];
+    for (let i = 0; i < bytes.length;) {
+        const type = bytes[i];
+        const length = bytes[i + 1];
+        const value = bytes.slice(i + 2, i + 2 + length);
+        if (value.length !== length)
+            throw new Error('truncated TLV');
+        i += 2 + length;
+        switch (type) {
+            case TLV_IDENTIFIER:
+                identifier = new TextDecoder().decode(new Uint8Array(value));
+                break;
+            case TLV_RELAY:
+                relays.push(new TextDecoder().decode(new Uint8Array(value)));
+                break;
+            case TLV_AUTHOR:
+                if (length !== 32)
+                    throw new Error(`author must be 32 bytes, got ${length}`);
+                pubkey = bytesToHex(new Uint8Array(value));
+                break;
+            case TLV_KIND:
+                if (length !== 4)
+                    throw new Error(`kind must be 4 bytes, got ${length}`);
+                kind = ((value[0] << 24) | (value[1] << 16) | (value[2] << 8) | value[3]) >>> 0;
+                break;
+            // Unknown TLV types are skipped, not rejected — that is what lets the
+            // format gain fields without breaking existing decoders.
+        }
+    }
+    if (identifier === undefined || pubkey === undefined || kind === undefined) {
+        throw new Error('naddr is missing identifier, author or kind');
+    }
+    return { identifier, pubkey, kind, relays };
+}
+/** `<kind>:<pubkey>:<d>` — the form used in `a` tags and relay filters. */
+export function pointerToAddress(pointer) {
+    return `${pointer.kind}:${pointer.pubkey}:${pointer.identifier}`;
+}
+/**
+ * The inverse: `<kind>:<pubkey>:<d>` back to a pointer.
+ *
+ * An address carries no relay hints — `naddr` has a TLV for them and an `a` tag
+ * does not — so the relays come back empty. That is a real loss of information,
+ * not an oversight: it is why the two forms are not interchangeable and why the
+ * encoder is not simply run in reverse.
+ *
+ * The `d` identifier may itself contain colons, so only the first two are
+ * separators.
+ */
+export function addressToPointer(address) {
+    const first = address.indexOf(':');
+    const second = address.indexOf(':', first + 1);
+    if (first < 1 || second < 0)
+        throw new Error(`not an address: ${address.slice(0, 40)}`);
+    const kind = Number(address.slice(0, first));
+    const pubkey = address.slice(first + 1, second);
+    const identifier = address.slice(second + 1);
+    if (!Number.isInteger(kind) || !/^[0-9a-f]{64}$/i.test(pubkey)) {
+        throw new Error(`not an address: ${address.slice(0, 40)}`);
+    }
+    return { kind, pubkey: pubkey.toLowerCase(), identifier, relays: [] };
+}
+/** `<kind>:<pubkey>:<d>` → `naddr1…`. */
+export function addrToNaddr(address, relays = []) {
+    const [kind, pubkey, ...rest] = address.split(':');
+    return encodeNaddr({ kind: Number(kind), pubkey, identifier: rest.join(':'), relays });
+}
+/** `naddr1…` → `<kind>:<pubkey>:<d>`. */
+export function naddrToAddr(encoded) {
+    return pointerToAddress(decodeNaddr(encoded));
+}
+/**
+ * A pointer from *either* form a reference arrives in.
+ *
+ * A message composed in an app carries `nostr:naddr1…` in its body. The same
+ * message read back off the relay carries the same reference as an `a` tag,
+ * which is a plain `<kind>:<pubkey>:<d>` address — that is what the NIP says a
+ * tag holds.
+ *
+ * Both name one object. Accepting only the first is what made a reference stop
+ * rendering the moment its own message came back from the relay (FEE-2).
+ */
+export function referenceToPointer(input) {
+    const trimmed = input.replace(/^nostr:/i, '');
+    return trimmed.toLowerCase().startsWith('naddr1')
+        ? decodeNaddr(trimmed)
+        : addressToPointer(trimmed);
+}
+/**
+ * Every `nostr:naddr1…` in a body of text (NIP-27).
+ *
+ * The character class is bech32's own alphabet, which excludes `1`, `b`, `i`
+ * and `o`, so a match ends cleanly at punctuation without a lookahead.
+ */
+export const NADDR_RE = /nostr:(naddr1[023456789acdefghjklmnpqrstuvwxyz]+)/gi;
+export function findNaddrs(text) {
+    return [...text.matchAll(NADDR_RE)].map((m) => m[1]);
+}
+/**
+ * The same text with every `nostr:naddr1…` taken out (PEEK-18).
+ *
+ * A reference that resolves into a widget should not also sit in the prose as
+ * sixty characters of bech32: the widget *is* the reference, rendered. Ship
+ * appends one to every thread it starts about an issue, so leaving it in means
+ * most cross-app messages open with a wall of noise nobody reads.
+ *
+ * Whitespace is repaired rather than merely removed. A pointer is usually
+ * trailing or on a line of its own, and deleting it in place otherwise leaves a
+ * double space mid-sentence or a hole between paragraphs — both of which look
+ * like the message itself is broken. Runs of blanks collapse *within* a line
+ * only, so indentation and paragraph breaks survive.
+ *
+ * Display-only. The stored body keeps the pointer, which is what lets the
+ * reference still be found, resolved and followed.
+ */
+export function stripNaddrs(text) {
+    // Text with no pointer comes back byte-identical. The repairs below are only
+    // ever justified by a removal, and a display helper that reflows somebody's
+    // indentation for free would be a bug wearing a tidy-up's clothes.
+    if (findNaddrs(text).length === 0)
+        return text;
+    return (text
+        // Take the blanks on either side along with the pointer, then put a single
+        // space back only when it stood between words on one line. Doing it in one
+        // pass is what keeps the repair local to the hole.
+        .replace(new RegExp(`([^\\S\\n]*)${NADDR_RE.source}([^\\S\\n]*)`, 'gi'), (_match, before, _addr, after) => (before && after ? ' ' : ''))
+        // A pointer alone on its line leaves the line's newlines behind on both
+        // sides, which reads as an unexplained gap.
+        .replace(/\n{3,}/g, '\n\n')
+        .trim());
+}
+//# sourceMappingURL=nip19.js.map

package/dist/nip19.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nip19.js","sourceRoot":"","sources":["../src/nip19.ts"],"names":[],"mappings":"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"}

package/dist/nip98.d.ts

@@ -0,0 +1,61 @@
+import { type SignedEvent, type UnsignedEvent } from './events.js';
+import type { Signer } from './sign.js';
+/** The relay rejects auth events outside ±60s (`TIMESTAMP_TOLERANCE_SECS`). */
+export declare const TIMESTAMP_TOLERANCE_SECS = 60;
+/**
+ * Buzz's `normalize_url` (nip98.rs:145): parse, strip trailing slashes from the
+ * path, re-serialize. We only need it to keep our own `u` tag canonical.
+ */
+export declare function normalizeUrl(raw: string): string;
+/** What `buildUnsignedAuthEvent` needs. Named so callers can pass it around. */
+export interface AuthEventArgs {
+    /** Left empty when a remote signer will overwrite it with the token's subject. */
+    pubkey: string;
+    url: string;
+    method: string;
+    /** Request body, when there is one — adds the `payload` tag. */
+    body?: string;
+    /** Override for tests; defaults to now. */
+    nowMs?: number;
+    /** Override for tests; defaults to random. Must differ per request. */
+    nonce?: string;
+}
+/**
+ * Build the unsigned kind:27235 event backing an `Authorization: Nostr …` header.
+ *
+ * `url` must be the full request URL with the same host the relay will see —
+ * `nip98_expected_url` (bridge.rs:195) reconstructs it as
+ * `{http|https}://{host}{path}` from the request's own Host header.
+ */
+export declare function buildUnsignedAuthEvent(args: AuthEventArgs): UnsignedEvent;
+/**
+ * Base64 without Node's `Buffer`, so this works in a browser, in Convex's
+ * default runtime and under Node from one build.
+ */
+export declare function base64(input: string): string;
+/**
+ * The full header value: `Nostr <base64(signed kind-27235 event JSON)>`
+ * (bridge.rs:81-93 strips the `Nostr ` prefix and base64-decodes the rest).
+ *
+ * Uses the utf8-aware `base64` above rather than a bare `btoa`, which throws on
+ * any code point above U+00FF.
+ */
+export declare function authorizationHeaderFor(signed: SignedEvent): string;
+/**
+ * Build, sign and encode the header in one step.
+ *
+ * **The auth event is signed by the same signer as the content**, which is what
+ * makes a keyless signer work at all: Buzz's bridge authenticates with NIP-98,
+ * so an app holding a perfectly signed issue and no way to sign a `27235` can
+ * still publish nothing. Signing content but not auth leaves the seam
+ * half-built, and it looks finished (PEEK-44).
+ *
+ * That rule has exactly one definition, here, and {@link Relay} uses it rather
+ * than inlining it — because an app with its own transport needs the same rule
+ * and would otherwise write it out again.
+ *
+ * Async for the same reason `Signer.sign` is: a remote signer or a browser
+ * extension cannot answer synchronously.
+ */
+export declare function authorizationHeader(signer: Signer, args: Omit<AuthEventArgs, 'pubkey'>): Promise<string>;
+//# sourceMappingURL=nip98.d.ts.map

package/dist/nip98.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nip98.d.ts","sourceRoot":"","sources":["../src/nip98.ts"],"names":[],"mappings":"AAgDA,OAAO,EAAuB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAW1C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAoBzE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAClC,OAAO,CAAC,MAAM,CAAC,CAEjB"}

package/dist/nip98.js

@@ -0,0 +1,134 @@
+/**
+ * NIP-98 HTTP auth for Buzz's REST bridge.
+ *
+ * Buzz's bridge (`POST /events`, `POST /query`) authenticates with NIP-98, **not**
+ * NIP-42 — no challenge/response and no persistent connection, which is what
+ * makes it usable from a request-scoped server runtime that cannot hold a socket,
+ * and from a plain `fetch` in a browser.
+ *
+ * Written against the relay's actual verifier, `verify_nip98_event`
+ * (crates/buzz-auth/src/nip98.rs:55). Its rules, in order:
+ *
+ *   1. kind must be 27235
+ *   2. valid Schnorr signature + id hash
+ *   3. `created_at` within ±60s of the relay's clock
+ *   4. `u` tag must equal the expected URL after normalization
+ *   5. `method` tag must match (case-insensitive)
+ *   6. if a `payload` tag is present AND a body was sent, sha256(body) must match
+ *
+ * Two things that bite in practice:
+ *
+ * - **No loopback aliasing.** `localhost`, `127.0.0.1` and `::1` are distinct
+ *   hosts to the verifier (deliberately — it is the row-zero community binding).
+ *   The `u` tag must use the same host string as the request's Host header.
+ * - **Single use, and "fresh" is not enough.** Each auth event id is recorded in
+ *   a Redis seen-set (`check_nip98_replay`, bridge.rs:135). Rebuilding the header
+ *   per request does *not* guarantee a new id: `created_at` has one-second
+ *   resolution, so two requests with the same URL, method and body inside the
+ *   same second produce a byte-identical event and the second is rejected with
+ *   `NIP-98: replay detected`. Verified against the live relay. Hence the
+ *   `nonce` tag below — it is what makes each auth event unique.
+ *
+ * ## Why the builder is unsigned, and the signer is somebody else's problem
+ *
+ * Before SHA-3 this existed twice with a real divergence: Peek had split the
+ * builder into `buildUnsignedAuthEvent` plus a signing step, because Peek holds
+ * no keys and must sign through Estiva ID; Ship still had the combined
+ * build-and-sign form. **Peek's shape is what ships**, because it is the one that
+ * works for a keyless app — and a keyed app composes it with `signEvent` in one
+ * line. The tag layout then has exactly one definition, which is the point: it is
+ * part of the event id preimage, and two copies drifting would produce ids the
+ * relay computes differently.
+ *
+ * `nostr-tools/nip98` was evaluated and does **not** fit: its `getToken` emits
+ * `u`, `method` and `payload` and no nonce, so identical requests in one second
+ * collide on Buzz's replay set. Measured, not assumed — see the README.
+ */
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, randomBytes, utf8ToBytes } from '@noble/hashes/utils';
+import { KIND } from './events.js';
+/** The relay rejects auth events outside ±60s (`TIMESTAMP_TOLERANCE_SECS`). */
+export const TIMESTAMP_TOLERANCE_SECS = 60;
+/**
+ * Buzz's `normalize_url` (nip98.rs:145): parse, strip trailing slashes from the
+ * path, re-serialize. We only need it to keep our own `u` tag canonical.
+ */
+export function normalizeUrl(raw) {
+    try {
+        const parsed = new URL(raw);
+        parsed.pathname = parsed.pathname.replace(/\/+$/, '');
+        return parsed.toString();
+    }
+    catch {
+        return raw.toLowerCase();
+    }
+}
+/**
+ * Build the unsigned kind:27235 event backing an `Authorization: Nostr …` header.
+ *
+ * `url` must be the full request URL with the same host the relay will see —
+ * `nip98_expected_url` (bridge.rs:195) reconstructs it as
+ * `{http|https}://{host}{path}` from the request's own Host header.
+ */
+export function buildUnsignedAuthEvent(args) {
+    const tags = [
+        ['u', normalizeUrl(args.url)],
+        ['method', args.method.toUpperCase()],
+        // Uniqueness, not security: without it, two identical requests in the same
+        // second collide on the event id and the relay rejects the second as a
+        // replay. The verifier ignores tags it does not know (it looks up `u`,
+        // `method` and `payload` by name), so this is safe to add.
+        ['nonce', args.nonce ?? bytesToHex(randomBytes(16))],
+    ];
+    if (args.body !== undefined) {
+        tags.push(['payload', bytesToHex(sha256(utf8ToBytes(args.body)))]);
+    }
+    return {
+        pubkey: args.pubkey,
+        created_at: Math.floor((args.nowMs ?? Date.now()) / 1000),
+        kind: KIND.HTTP_AUTH,
+        tags,
+        content: '',
+    };
+}
+/**
+ * Base64 without Node's `Buffer`, so this works in a browser, in Convex's
+ * default runtime and under Node from one build.
+ */
+export function base64(input) {
+    const bytes = utf8ToBytes(input);
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+/**
+ * The full header value: `Nostr <base64(signed kind-27235 event JSON)>`
+ * (bridge.rs:81-93 strips the `Nostr ` prefix and base64-decodes the rest).
+ *
+ * Uses the utf8-aware `base64` above rather than a bare `btoa`, which throws on
+ * any code point above U+00FF.
+ */
+export function authorizationHeaderFor(signed) {
+    return `Nostr ${base64(JSON.stringify(signed))}`;
+}
+/**
+ * Build, sign and encode the header in one step.
+ *
+ * **The auth event is signed by the same signer as the content**, which is what
+ * makes a keyless signer work at all: Buzz's bridge authenticates with NIP-98,
+ * so an app holding a perfectly signed issue and no way to sign a `27235` can
+ * still publish nothing. Signing content but not auth leaves the seam
+ * half-built, and it looks finished (PEEK-44).
+ *
+ * That rule has exactly one definition, here, and {@link Relay} uses it rather
+ * than inlining it — because an app with its own transport needs the same rule
+ * and would otherwise write it out again.
+ *
+ * Async for the same reason `Signer.sign` is: a remote signer or a browser
+ * extension cannot answer synchronously.
+ */
+export async function authorizationHeader(signer, args) {
+    return authorizationHeaderFor(await signer.sign(buildUnsignedAuthEvent({ ...args, pubkey: signer.pubkey })));
+}
+//# sourceMappingURL=nip98.js.map

package/dist/nip98.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nip98.js","sourceRoot":"","sources":["../src/nip98.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC1E,OAAO,EAAE,IAAI,EAAuD,MAAM,aAAa,CAAA;AAGvF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAA;AAW1C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QACrD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC,WAAW,EAAE,CAAA;IAC1B,CAAC;AACH,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmB;IACxD,MAAM,IAAI,GAAe;QACvB,CAAC,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACrC,2EAA2E;QAC3E,uEAAuE;QACvE,uEAAuE;QACvE,2DAA2D;QAC3D,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;KACrD,CAAA;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,CAAC;IACD,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,EAAE,IAAI,CAAC,SAAS;QACpB,IAAI;QACJ,OAAO,EAAE,EAAE;KACZ,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;IAChC,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IACvD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAA;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAmB;IACxD,OAAO,SAAS,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;AAClD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAc,EACd,IAAmC;IAEnC,OAAO,sBAAsB,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;AAC9G,CAAC"}

package/dist/sign.d.ts

@@ -0,0 +1,67 @@
+import { type SignedEvent, type UnsignedEvent } from './events.js';
+/** Derive the 64-char hex x-only public key for a secret key. */
+export declare function publicKeyFromSecret(secretKeyHex: string): string;
+/**
+ * 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 declare function signEvent(unsigned: UnsignedEvent, secretKeyHex: string): SignedEvent;
+/**
+ * Who signs, decided once and injected everywhere (PEEK-44).
+ *
+ * ## Why this exists at all
+ *
+ * The suite claims apps built by different people, sharing no code and no
+ * database, can work on the same data. Wiring an app directly to one login
+ * service would quietly undercut that — it would only work for people with an
+ * Estiva account.
+ *
+ * Depending on a *signer* does not. Separating the signer from the client is
+ * ordinary Nostr architecture (NIP-07, NIP-46), so an app stays honest for
+ * anyone who wants to point their own signer at it, and "sign in with Estiva ID"
+ * becomes one implementation among several rather than an assumption baked into
+ * the data layer. It is also the seam that lets this package stay ignorant of
+ * identity: `@estiva-app/identity` implements this interface, and nothing here
+ * knows that it exists.
+ *
+ * ## The two decisions in the interface
+ *
+ * **`pubkey` is synchronous.** Every event builder needs it before there is
+ * anything to sign — `buildMessage(pubkey, …)` — so making it a promise would
+ * put an `await` in front of every construction site for no benefit. You know
+ * who you are before you sign; implementations that must ask (NIP-07) resolve it
+ * once, at construction.
+ *
+ * **`sign` is asynchronous**, because two of the three implementations are: a
+ * remote call to `/sign` and a round trip to a browser extension. The local key
+ * is the odd one out, and it is cheaper for it to return a resolved promise than
+ * for the interface to pretend signing is always instant.
+ *
+ * ## What a signer deliberately cannot do
+ *
+ * Sign as somebody else. Every implementation attributes the event to its own
+ * `pubkey` and ignores whatever the caller put there, which is the same
+ * guarantee `/sign` makes server-side. Code that genuinely needs to produce a
+ * mismatched event — Ship's `scripts/verify.ts` forges one to prove the relay
+ * rejects it — uses {@link signEvent} directly and holds a raw key to do it.
+ */
+/** How the current signer authenticates, for anything that needs to say so. */
+export type SignerKind = 'local' | 'estiva-id' | 'nip07';
+export interface Signer {
+    /** The pubkey every event from this signer is attributed to. */
+    readonly pubkey: string;
+    readonly kind: SignerKind;
+    /** Attributes the event to {@link pubkey}, whatever the caller supplied. */
+    sign(unsigned: UnsignedEvent): Promise<SignedEvent>;
+}
+/**
+ * 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 declare function secretKeySigner(secretKeyHex: string, kind?: SignerKind): Signer;
+//# sourceMappingURL=sign.d.ts.map

package/dist/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAElF,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,CAUpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAA;AAExD,MAAM,WAAW,MAAM;IACrB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,4EAA4E;IAC5E,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE,UAAoB,GAAG,MAAM,CASxF"}