@estiva-app/protocol 0.1.0

package/dist/live.js

@@ -0,0 +1,398 @@
+/**
+ * One live relay socket, with NIP-42 AUTH and reconnect (PEE-5).
+ *
+ * A WebSocket that stays open, authenticates as the viewer, and keeps
+ * subscriptions alive across disconnects. Nothing is *interpreted* here: this
+ * delivers frames, and folding them into state is the consuming app's business.
+ *
+ * The socket belongs in the **client**, not in a backend: a request-scoped
+ * server runtime cannot hold one, and more importantly the viewer's own
+ * credential is the only thing that can see the viewer's channels. Buzz gates
+ * reads per channel (`is_member_cached`), so a service identity would need
+ * membership in every conversation — a product decision, not an implementation
+ * detail.
+ *
+ * **This was built inside Peek** (PEE-5, PEE-6) because Gate 2 had not happened
+ * when it was due, and it was Peek-only for two days. SHA-3 is the ticket that
+ * owed the move; `subscriptions.ts` beside this file is PEE-6's half.
+ *
+ * No nostr library. Raw `WebSocket` plus `buildUnsignedRelayAuthEvent` is
+ * enough, and the tag layout stays in one place.
+ *
+ * ## Three things the relay does that shape this file
+ *
+ * All three were read out of `crates/buzz-*` rather than assumed, because each
+ * one fails as a healthy-looking socket that delivers nothing.
+ *
+ * 1. **A second AUTH on an authenticated connection is refused.** `handle_auth`
+ *    matches on `AuthState::{Pending, Authenticated, Failed}` and answers
+ *    anything but `Pending` with `OK … false "auth-required: already
+ *    authenticated"`. So re-authenticating in place is not possible, and
+ *    {@link LiveRelay} never tries.
+ *
+ * 2. **A failed AUTH poisons the connection and leaves it open.** Only a *ban*
+ *    closes the socket; a verification failure sets `AuthState::Failed` and
+ *    returns. Every later REQ is answered `CLOSED … "auth-required:
+ *    authenticate before subscribing"`, forever, on a socket whose readyState
+ *    is OPEN. Treating an AUTH refusal as fatal-for-this-socket and reconnecting
+ *    is the only way out.
+ *
+ * 3. **The `relay` tag is bound to the connection's host**, not the deployment
+ *    URL — see `relayAuthUrl`.
+ *
+ * ## Token rotation needs nothing here, and that is worth stating
+ *
+ * PEE-5 asked for re-authentication when the app renews its access token,
+ * preferring it to a reconnect. Neither is needed, and the first is impossible
+ * (point 1 above).
+ *
+ * The relay authenticates a **pubkey**, by verifying a Schnorr signature. It
+ * never sees the Estiva ID access token and has no idea one exists. Renewal
+ * issues a new token for the *same* keypair, so nothing the relay checked has
+ * changed and the connection stays valid. The token is needed only to *sign* a
+ * fresh 22242, which happens on the next connect.
+ *
+ * What genuinely does not propagate is offboarding: a person whose Estiva ID
+ * access is revoked keeps an already-authenticated socket until it drops. That
+ * is the relay's session model — its own ban gate is the control for it — and
+ * re-authenticating on a timer would not have fixed it either, since a banned
+ * pubkey is caught at connect.
+ *
+ * ## Never logged, never persisted
+ *
+ * The AUTH event and the access token appear in no log line. Buzz refuses to
+ * store kind:22242 for this reason, and Convex surfaces function arguments in
+ * its dashboard logs — which is the entire reason Peek's credential lives in the
+ * browser. {@link LiveRelayOptions.log} receives states and reasons, never
+ * events or credentials, and this module must keep it that way.
+ */
+import { buildUnsignedRelayAuthEvent, } from './events.js';
+/** How many consecutive AUTH refusals before giving up rather than looping. */
+const MAX_AUTH_FAILURES = 3;
+/** `https://` → `wss://`, `http://` → `ws://`; a `ws`-scheme URL is left alone. */
+export function toWebSocketUrl(url) {
+    const trimmed = url.trim().replace(/\/+$/, '');
+    if (trimmed.startsWith('wss://') || trimmed.startsWith('ws://'))
+        return trimmed;
+    if (trimmed.startsWith('https://'))
+        return `wss://${trimmed.slice('https://'.length)}`;
+    if (trimmed.startsWith('http://'))
+        return `ws://${trimmed.slice('http://'.length)}`;
+    return `wss://${trimmed}`;
+}
+export function parseFrame(raw) {
+    if (typeof raw !== 'string')
+        return { type: 'OTHER' };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { type: 'OTHER' };
+    }
+    if (!Array.isArray(parsed) || typeof parsed[0] !== 'string')
+        return { type: 'OTHER' };
+    switch (parsed[0]) {
+        case 'AUTH':
+            return typeof parsed[1] === 'string'
+                ? { type: 'AUTH', challenge: parsed[1] }
+                : { type: 'OTHER' };
+        case 'OK':
+            return typeof parsed[1] === 'string' && typeof parsed[2] === 'boolean'
+                ? {
+                    type: 'OK',
+                    eventId: parsed[1],
+                    accepted: parsed[2],
+                    message: typeof parsed[3] === 'string' ? parsed[3] : '',
+                }
+                : { type: 'OTHER' };
+        case 'EVENT':
+            return typeof parsed[1] === 'string' && parsed[2] && typeof parsed[2] === 'object'
+                ? { type: 'EVENT', subId: parsed[1], event: parsed[2] }
+                : { type: 'OTHER' };
+        case 'EOSE':
+            return typeof parsed[1] === 'string' ? { type: 'EOSE', subId: parsed[1] } : { type: 'OTHER' };
+        case 'CLOSED':
+            return typeof parsed[1] === 'string'
+                ? {
+                    type: 'CLOSED',
+                    subId: parsed[1],
+                    message: typeof parsed[2] === 'string' ? parsed[2] : '',
+                }
+                : { type: 'OTHER' };
+        case 'NOTICE':
+            return typeof parsed[1] === 'string'
+                ? { type: 'NOTICE', message: parsed[1] }
+                : { type: 'OTHER' };
+        default:
+            return { type: 'OTHER' };
+    }
+}
+export function createLiveRelay(options) {
+    const wsUrl = toWebSocketUrl(options.url);
+    const now = options.now ?? (() => Date.now());
+    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+    const makeSocket = options.socketFactory ?? ((url) => new WebSocket(url));
+    const backoff = options.backoff ?? { baseMs: 1_000, maxMs: 30_000, jitter: () => Math.random() };
+    const log = options.log ?? (() => { });
+    const subscriptions = new Map();
+    let socket = null;
+    let state = 'connecting';
+    let attempt = 0;
+    let authFailures = 0;
+    let stopped = false;
+    let reconnectTimer = null;
+    /** The id of the AUTH event in flight, so its `OK` is distinguishable. */
+    let pendingAuthEventId = null;
+    let nextSubId = 0;
+    function setState(next) {
+        if (state === next)
+            return;
+        state = next;
+        options.onState?.(next);
+    }
+    function send(frame) {
+        try {
+            socket?.send(JSON.stringify(frame));
+        }
+        catch (error) {
+            // A send on a socket the browser has already torn down. The close
+            // handler is what recovers; swallowing here keeps that the only path.
+            log('send failed', { reason: error.message });
+        }
+    }
+    function openSubscription(sub) {
+        send(['REQ', sub.id, ...sub.filters]);
+    }
+    /**
+     * Tear the socket down and schedule another attempt.
+     *
+     * `fatal` is for authentication refusals, which reconnecting cannot fix past
+     * a point — see {@link MAX_AUTH_FAILURES}.
+     */
+    function scheduleReconnect(reason) {
+        if (stopped)
+            return;
+        if (socket) {
+            // Drop the handlers before closing so our own `onclose` does not fire and
+            // schedule a second reconnect on top of this one.
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close();
+            }
+            catch {
+                // Already closing. Nothing to recover.
+            }
+            socket = null;
+        }
+        pendingAuthEventId = null;
+        if (authFailures >= MAX_AUTH_FAILURES) {
+            setState('failed');
+            log('giving up after repeated auth refusals', { authFailures, reason });
+            return;
+        }
+        setState('reconnecting');
+        const delay = Math.min(backoff.maxMs, backoff.baseMs * 2 ** attempt) * (0.5 + backoff.jitter() / 2);
+        attempt += 1;
+        log('reconnecting', { reason, delayMs: Math.round(delay), attempt });
+        reconnectTimer = setTimer(() => {
+            reconnectTimer = null;
+            connect();
+        }, delay);
+    }
+    async function answerChallenge(challenge) {
+        const credential = options.getCredential();
+        if (!credential) {
+            // Not signed in. Not an auth *failure* — there is nothing to sign with,
+            // and a session may yet appear, so this does not count toward the cap.
+            log('no credential; deferring auth');
+            scheduleReconnect('no credential');
+            return;
+        }
+        setState('authenticating');
+        try {
+            const unsigned = buildUnsignedRelayAuthEvent({
+                // Left empty deliberately: `/sign` overwrites it with the token's
+                // subject, and `expectedPubkey` below is the check that it matched.
+                pubkey: '',
+                relayUrl: wsUrl,
+                challenge,
+                nowMs: now(),
+            });
+            // `expectedPubkey` is not a request — `/sign` signs as the token's
+            // subject whatever it is handed, so a mismatch returns HTTP 200 with a
+            // valid event authored by somebody else. Passing it is the only thing
+            // that catches that, and `bridge.ts` says not to drop it.
+            const signed = await options.sign(unsigned, credential.accessToken, credential.pubkey);
+            if (stopped || !socket)
+                return;
+            pendingAuthEventId = signed.id;
+            send(['AUTH', signed]);
+        }
+        catch (error) {
+            // Signing failed: an expired token, /sign refusing the kind, the network.
+            // Not counted as an auth refusal — the relay never saw anything, and the
+            // common cause (a token that just expired) fixes itself on reconnect.
+            log('could not sign the auth challenge', { reason: error.message });
+            scheduleReconnect('sign failed');
+        }
+    }
+    function onAuthResult(frame) {
+        pendingAuthEventId = null;
+        if (!frame.accepted) {
+            // The connection is now `AuthState::Failed` relay-side and will refuse
+            // every REQ while staying open. There is no recovery on this socket.
+            authFailures += 1;
+            log('relay refused the auth event', { reason: frame.message, authFailures });
+            scheduleReconnect('auth refused');
+            return;
+        }
+        authFailures = 0;
+        attempt = 0;
+        setState('live');
+        log('authenticated', { subscriptions: subscriptions.size });
+        // Re-issue every live subscription. A reconnect that restores the socket
+        // and not the subscriptions is the silent half of this failure: the app
+        // looks connected and never hears anything again.
+        for (const sub of subscriptions.values())
+            openSubscription(sub);
+    }
+    function onFrame(raw) {
+        const frame = parseFrame(raw);
+        switch (frame.type) {
+            case 'AUTH':
+                void answerChallenge(frame.challenge);
+                return;
+            case 'OK':
+                if (pendingAuthEventId && frame.eventId === pendingAuthEventId)
+                    onAuthResult(frame);
+                return;
+            case 'EVENT':
+                subscriptions.get(frame.subId)?.onEvent(frame.event);
+                return;
+            case 'EOSE':
+                subscriptions.get(frame.subId)?.onEose?.();
+                return;
+            case 'CLOSED': {
+                const sub = subscriptions.get(frame.subId);
+                log('subscription closed by the relay', { subId: frame.subId, reason: frame.message });
+                sub?.onClosed?.(frame.message);
+                // `auth-required` here means the connection is unauthenticated — the
+                // poisoned-but-open state. Reconnecting is the only fix, and dropping
+                // the subscription would hide it.
+                if (frame.message.startsWith('auth-required'))
+                    scheduleReconnect('req refused');
+                return;
+            }
+            case 'NOTICE':
+                log('relay notice', { message: frame.message });
+                return;
+            default:
+                return;
+        }
+    }
+    function connect() {
+        if (stopped)
+            return;
+        setState(attempt === 0 ? 'connecting' : 'reconnecting');
+        let created;
+        try {
+            created = makeSocket(wsUrl);
+        }
+        catch (error) {
+            log('could not open a socket', { reason: error.message });
+            scheduleReconnect('open threw');
+            return;
+        }
+        socket = created;
+        created.onopen = () => {
+            // Nothing to do but wait: Buzz sends `["AUTH", challenge]` immediately on
+            // connect, so authentication starts from the message handler.
+            log('socket open');
+        };
+        created.onmessage = (ev) => {
+            if (socket !== created)
+                return;
+            onFrame(ev.data);
+        };
+        created.onerror = () => {
+            // `onclose` always follows, and that is where recovery lives. Logging
+            // here only helps distinguish a refused connection from a clean drop.
+            log('socket error');
+        };
+        created.onclose = () => {
+            if (socket !== created)
+                return;
+            socket = null;
+            scheduleReconnect('socket closed');
+        };
+    }
+    connect();
+    return {
+        subscribe(filters, onEvent, subOptions) {
+            const id = `${options.subscriptionPrefix ?? 'sub'}-${nextSubId++}`;
+            const sub = {
+                id,
+                filters,
+                onEvent,
+                onEose: subOptions?.onEose,
+                onClosed: subOptions?.onClosed,
+            };
+            subscriptions.set(id, sub);
+            if (state === 'live')
+                openSubscription(sub);
+            return {
+                close() {
+                    if (!subscriptions.delete(id))
+                        return;
+                    if (state === 'live')
+                        send(['CLOSE', id]);
+                },
+            };
+        },
+        reconnect() {
+            if (stopped)
+                return;
+            if (reconnectTimer !== null) {
+                clearTimer(reconnectTimer);
+                reconnectTimer = null;
+            }
+            // Reset the backoff: this is not another failed attempt in a series, it
+            // is new information that the network changed.
+            attempt = 0;
+            if (socket) {
+                socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+                try {
+                    socket.close();
+                }
+                catch {
+                    // Already gone.
+                }
+                socket = null;
+            }
+            pendingAuthEventId = null;
+            connect();
+        },
+        state: () => state,
+        close() {
+            stopped = true;
+            if (reconnectTimer !== null) {
+                clearTimer(reconnectTimer);
+                reconnectTimer = null;
+            }
+            subscriptions.clear();
+            if (socket) {
+                socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+                try {
+                    socket.close();
+                }
+                catch {
+                    // Already gone.
+                }
+                socket = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=live.js.map

package/dist/live.js.map

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

package/dist/nip19.d.ts

@@ -0,0 +1,98 @@
+/** Regroup bytes between bit widths, e.g. 8-bit bytes → 5-bit bech32 symbols. */
+export declare function convertBits(data: ArrayLike<number>, from: number, to: number, pad: boolean): number[];
+/**
+ * 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 declare function bech32Encode(hrp: string, data: number[]): string;
+export declare function bech32Decode(encoded: string): {
+    hrp: string;
+    data: number[];
+};
+/** A decoded `naddr` — everything needed to fetch the event it points at. */
+export interface AddressPointer {
+    /** The `d` tag of the addressable event. */
+    identifier: string;
+    pubkey: string;
+    kind: number;
+    /** Relay hints, in the order they appeared. May be empty. */
+    relays: string[];
+}
+/**
+ * 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 declare function encodeNaddr(pointer: AddressPointer): string;
+/**
+ * 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 declare function decodeNaddr(encoded: string): AddressPointer;
+/** `<kind>:<pubkey>:<d>` — the form used in `a` tags and relay filters. */
+export declare function pointerToAddress(pointer: AddressPointer): string;
+/**
+ * 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 declare function addressToPointer(address: string): AddressPointer;
+/** `<kind>:<pubkey>:<d>` → `naddr1…`. */
+export declare function addrToNaddr(address: string, relays?: string[]): string;
+/** `naddr1…` → `<kind>:<pubkey>:<d>`. */
+export declare function naddrToAddr(encoded: string): string;
+/**
+ * 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 declare function referenceToPointer(input: string): AddressPointer;
+/**
+ * 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 declare const NADDR_RE: RegExp;
+export declare function findNaddrs(text: string): string[];
+/**
+ * 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 declare function stripNaddrs(text: string): string;
+//# sourceMappingURL=nip19.d.ts.map

package/dist/nip19.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nip19.d.ts","sourceRoot":"","sources":["../src/nip19.ts"],"names":[],"mappings":"AAkFA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAqBrG;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAGhE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAgB7E;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAWD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CA8B3D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAyC3D;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAWhE;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,MAAM,CAG1E;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAKhE;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAwD,CAAA;AAE7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBhD"}