@forgesworn/fold-kit 0.0.0-seed.0 → 0.2.0

package/dist/invitation.js

@@ -0,0 +1,484 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { base64urlnopad } from '@scure/base';
+import { nip44 } from 'nostr-tools';
+import { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { hexEquals, normaliseHex } from './hex.js';
+import { KINDS } from './kinds.js';
+import { verifyEventUncached } from './verify.js';
+import { deriveRoom } from './room.js';
+const INVITATION_ID_INFO = 'kithmoot/v2/invitation-id';
+const INVITATION_REQUEST_KEY_INFO = 'kithmoot/v2/invitation-request-key';
+const INVITATION_MAX_AGE_SECONDS = 90;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_RETRY_MS = 2_000;
+/** A delegated responder cannot silently make its authority permanent. */
+export const INVITATION_DELEGATION_TTL_SECONDS = 12 * 60 * 60;
+/** Bounds both verification work and the size of a grant from a hostile peer. */
+export const MAX_INVITATION_DELEGATION_DEPTH = 16;
+function require32(bytes, what) {
+    if (bytes.length !== 32)
+        throw new Error(`${what} must be 32 bytes`);
+}
+function requireHex32(value, what) {
+    if (!/^[0-9a-f]{64}$/i.test(value))
+        throw new Error(`${what} must be 32-byte hex`);
+    return normaliseHex(value);
+}
+function requirePubkey(pubkey) {
+    return requireHex32(pubkey, 'inviter pubkey');
+}
+/** Create a bearer plus a fresh, unlinkable inviter key for one share URL. */
+export function createRoomInvitation(persistent = false) {
+    const inviterSk = generateSecretKey();
+    return {
+        invitation: { bearer: randomBytes(32), inviter: getPublicKey(inviterSk), ...(persistent ? { persistent: true } : {}) },
+        inviterSk,
+    };
+}
+/** Validate and canonicalise an invitation crossing a URL/storage boundary. */
+export function roomInvitation(bearer, inviter, persistent = false) {
+    require32(bearer, 'invitation bearer');
+    return { bearer, inviter: requirePubkey(inviter), ...(persistent ? { persistent: true } : {}) };
+}
+/** Public rendezvous id. Relays see this and timing, but cannot derive the bearer. */
+export function deriveInvitationId(invitation) {
+    require32(invitation.bearer, 'invitation bearer');
+    const bytes = hkdf(sha256, invitation.bearer, undefined, INVITATION_ID_INFO, 32);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function requestKey(invitation) {
+    return hkdf(sha256, invitation.bearer, undefined, INVITATION_REQUEST_KEY_INFO, 32);
+}
+/** How much of a name an admission request carries. The same bound as a
+ *  display name on the roster. */
+const MAX_REQUEST_NAME_LENGTH = 64;
+/** Prove possession of the bearer without putting it, or a traffic key, on a relay. */
+export function encodeInvitationRequest(opts) {
+    require32(opts.requesterSk, 'requester secret key');
+    const device = getPublicKey(opts.requesterSk);
+    const body = { v: 1, device };
+    const name = opts.name?.trim().slice(0, MAX_REQUEST_NAME_LENGTH);
+    if (name)
+        body.name = name;
+    if (opts.participant !== undefined)
+        body.participant = requirePubkey(opts.participant);
+    return finalizeEvent({
+        kind: KINDS.INVITATION_REQUEST,
+        created_at: opts.now,
+        tags: [
+            ['d', deriveInvitationId(opts.invitation)],
+            ['p', requirePubkey(opts.invitation.inviter)],
+        ],
+        content: nip44.v2.encrypt(JSON.stringify(body), requestKey(opts.invitation)),
+    }, opts.requesterSk);
+}
+/** Returns null for all malformed, stale, wrongly addressed, or unauthorised asks. */
+export function decodeInvitationRequest(event, opts) {
+    try {
+        if (event.kind !== KINDS.INVITATION_REQUEST)
+            return null;
+        if (!verifyEventUncached(event))
+            return null;
+        if (Math.abs(opts.now - event.created_at) > (opts.maxAgeSeconds ?? INVITATION_MAX_AGE_SECONDS))
+            return null;
+        if (event.tags.find((t) => t[0] === 'd')?.[1] !== deriveInvitationId(opts.invitation))
+            return null;
+        const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
+        if (addressed === undefined || !hexEquals(addressed, opts.invitation.inviter))
+            return null;
+        const body = JSON.parse(nip44.v2.decrypt(event.content, requestKey(opts.invitation)));
+        if (body.v !== 1 || typeof body.device !== 'string')
+            return null;
+        if (!hexEquals(body.device, event.pubkey))
+            return null;
+        const decoded = { device: requirePubkey(body.device), request: event.id };
+        // Optional, and dropped rather than refused when malformed: a host
+        // that cannot read the name can still let the device in.
+        if (typeof body.name === 'string') {
+            const name = body.name.trim().slice(0, MAX_REQUEST_NAME_LENGTH);
+            if (name)
+                decoded.name = name;
+        }
+        if (typeof body.participant === 'string' && /^[0-9a-f]{64}$/i.test(body.participant))
+            decoded.participant = body.participant.toLowerCase();
+        return decoded;
+    }
+    catch {
+        return null;
+    }
+}
+function delegationMessage(invitation, room, issuer, delegate, expiresAt) {
+    return sha256(new TextEncoder().encode(`kithmoot/v2/invitation-delegation:${invitation}:${room}:${issuer}:${delegate}:${expiresAt}`));
+}
+function issueInvitationDelegation(invitation, room, issuerSk, delegate, expiresAt) {
+    const invitationId = deriveInvitationId(invitation);
+    const canonicalRoom = requireHex32(room, 'room id');
+    const issuer = getPublicKey(issuerSk);
+    const canonicalDelegate = requirePubkey(delegate);
+    if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0)
+        throw new Error('delegation expiry must be unix seconds');
+    return {
+        invitation: invitationId,
+        room: canonicalRoom,
+        issuer,
+        delegate: canonicalDelegate,
+        expiresAt,
+        sig: bytesToHex(schnorr.sign(delegationMessage(invitationId, canonicalRoom, issuer, canonicalDelegate, expiresAt), issuerSk)),
+    };
+}
+/**
+ * Verify a whole chain and return the pubkey authorised by its final hop.
+ * An empty chain names the root inviter itself.
+ */
+export function verifyInvitationDelegation(invitation, chain, now) {
+    try {
+        if (!Array.isArray(chain) || chain.length > MAX_INVITATION_DELEGATION_DEPTH)
+            return null;
+        const invitationId = deriveInvitationId(invitation);
+        let room;
+        let authority = requirePubkey(invitation.inviter);
+        for (const raw of chain) {
+            if (typeof raw !== 'object' || raw === null)
+                return null;
+            const cert = {
+                invitation: normaliseHex(raw.invitation),
+                room: requireHex32(raw.room, 'room id'),
+                issuer: requirePubkey(raw.issuer),
+                delegate: requirePubkey(raw.delegate),
+                expiresAt: raw.expiresAt,
+                sig: normaliseHex(raw.sig),
+            };
+            if (!hexEquals(cert.invitation, invitationId))
+                return null;
+            if (room !== undefined && !hexEquals(cert.room, room))
+                return null;
+            room = cert.room;
+            if (!hexEquals(cert.issuer, authority))
+                return null;
+            if (!Number.isSafeInteger(cert.expiresAt) || cert.expiresAt <= now)
+                return null;
+            if (hexToBytes(cert.sig).length !== 64)
+                return null;
+            if (!schnorr.verify(hexToBytes(cert.sig), delegationMessage(cert.invitation, cert.room, cert.issuer, cert.delegate, cert.expiresAt), hexToBytes(cert.issuer)))
+                return null;
+            authority = cert.delegate;
+        }
+        return authority;
+    }
+    catch {
+        return null;
+    }
+}
+/** Encrypt a room secret only to the requester and authenticate its signer
+ * through the room-bound chain rooted at the inviter pinned in the link. */
+export function encodeInvitationGrant(opts) {
+    require32(opts.inviterSk, 'inviter secret key');
+    require32(opts.roomSecret, 'room secret');
+    const inviter = getPublicKey(opts.inviterSk);
+    const chain = opts.delegation ?? [];
+    const roomId = deriveRoom(opts.roomSecret).roomId;
+    const authorised = verifyInvitationDelegation(opts.invitation, chain, opts.now);
+    if (authorised === null || !hexEquals(inviter, authorised))
+        throw new Error('responder is not delegated for invitation');
+    if (chain.length > 0 && !hexEquals(chain[0].room, roomId))
+        throw new Error('delegation names another room');
+    if (chain.length >= MAX_INVITATION_DELEGATION_DEPTH)
+        throw new Error('invitation delegation is at maximum depth');
+    const requester = requirePubkey(opts.requester);
+    if (!/^[0-9a-f]{64}$/i.test(opts.request))
+        throw new Error('request id must be 32-byte hex');
+    const ownExpiry = chain.length === 0
+        ? Number.POSITIVE_INFINITY
+        : Math.min(...chain.map((cert) => cert.expiresAt));
+    const expiresAt = Math.min(ownExpiry, opts.now + (opts.delegationTtlSeconds ?? INVITATION_DELEGATION_TTL_SECONDS));
+    const next = issueInvitationDelegation(opts.invitation, roomId, opts.inviterSk, requester, expiresAt);
+    const body = {
+        v: 2,
+        request: normaliseHex(opts.request),
+        secret: base64urlnopad.encode(opts.roomSecret),
+        delegation: [...chain, next],
+        ...(opts.epoch !== undefined && Number.isSafeInteger(opts.epoch) && opts.epoch >= 0 ? { epoch: opts.epoch } : {}),
+    };
+    const conversationKey = nip44.v2.utils.getConversationKey(opts.inviterSk, requester);
+    return finalizeEvent({
+        kind: KINDS.INVITATION_GRANT,
+        created_at: opts.now,
+        tags: [
+            ['d', deriveInvitationId(opts.invitation)],
+            ['p', requester],
+        ],
+        content: nip44.v2.encrypt(JSON.stringify(body), conversationKey),
+    }, opts.inviterSk);
+}
+/**
+ * Accept a fresh response whose delegation chain terminates at its event
+ * signer, then retain the final requester hop so this member can become a
+ * responder in turn. The chain always roots at the pubkey pinned in the
+ * link; a bearer holder cannot nominate an authority of their own.
+ */
+export function decodeRoomAdmissionGrant(event, opts) {
+    try {
+        if (event.kind !== KINDS.INVITATION_GRANT)
+            return null;
+        if (!verifyEventUncached(event))
+            return null;
+        if (Math.abs(opts.now - event.created_at) > (opts.maxAgeSeconds ?? INVITATION_MAX_AGE_SECONDS))
+            return null;
+        if (event.tags.find((t) => t[0] === 'd')?.[1] !== deriveInvitationId(opts.invitation))
+            return null;
+        const requester = getPublicKey(opts.requesterSk);
+        const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
+        if (addressed === undefined || !hexEquals(addressed, requester))
+            return null;
+        const conversationKey = nip44.v2.utils.getConversationKey(opts.requesterSk, event.pubkey);
+        const body = JSON.parse(nip44.v2.decrypt(event.content, conversationKey));
+        if (body.v !== 2 || typeof body.request !== 'string' || !hexEquals(body.request, opts.request))
+            return null;
+        if (typeof body.secret !== 'string')
+            return null;
+        const secret = base64urlnopad.decode(body.secret);
+        if (secret.length !== 32)
+            return null;
+        if (!Array.isArray(body.delegation) || body.delegation.length === 0)
+            return null;
+        if (!hexEquals(body.delegation[0].room, deriveRoom(secret).roomId))
+            return null;
+        const authority = verifyInvitationDelegation(opts.invitation, body.delegation, opts.now);
+        if (authority === null || !hexEquals(authority, requester))
+            return null;
+        const issuer = body.delegation.at(-1)?.issuer;
+        if (issuer === undefined || !hexEquals(issuer, event.pubkey))
+            return null;
+        const admission = {
+            secret,
+            delegate: { delegateSk: opts.requesterSk, chain: body.delegation },
+        };
+        if (Number.isSafeInteger(body.epoch) && body.epoch >= 0)
+            admission.epoch = body.epoch;
+        return admission;
+    }
+    catch {
+        return null;
+    }
+}
+/** Backward-compatible convenience for callers that only need the traffic
+ * secret. New interactive clients should retain `decodeRoomAdmissionGrant`'s
+ * delegate capability so the room does not depend on its creator staying. */
+export function decodeInvitationGrant(event, opts) {
+    return decodeRoomAdmissionGrant(event, opts)?.secret ?? null;
+}
+/** What a joiner is told when a link was retired because its room ended. */
+export const ROOM_ENDED_MESSAGE = 'this room was ended by the person who started it';
+/** Make a permanent tombstone for one invitation rendezvous. */
+export function encodeInvitationRetirement(opts) {
+    require32(opts.inviterSk, 'inviter secret key');
+    if (!hexEquals(getPublicKey(opts.inviterSk), opts.invitation.inviter)) {
+        throw new Error('only the root inviter can retire an invitation');
+    }
+    return finalizeEvent({
+        kind: KINDS.INVITATION_RETIREMENT,
+        created_at: opts.now,
+        tags: [['d', deriveInvitationId(opts.invitation)]],
+        content: JSON.stringify(opts.ended ? { v: 1, ended: true } : { v: 1 }),
+    }, opts.inviterSk);
+}
+/** A valid tombstone never expires: invitation ids are random and unique,
+ * and a retired bearer must not become usable again after a timeout. */
+export function decodeInvitationRetirement(event, invitation) {
+    return decodeInvitationRetirementNotice(event, invitation) !== undefined;
+}
+/** A valid retirement, and whether it says the room was ended. Undefined
+ * for anything that is not a valid retirement of this invitation. */
+export function decodeInvitationRetirementNotice(event, invitation) {
+    try {
+        if (event.kind !== KINDS.INVITATION_RETIREMENT)
+            return undefined;
+        if (!verifyEventUncached(event))
+            return undefined;
+        if (!hexEquals(event.pubkey, invitation.inviter))
+            return undefined;
+        if (event.tags.find((tag) => tag[0] === 'd')?.[1] !== deriveInvitationId(invitation))
+            return undefined;
+        const body = JSON.parse(event.content);
+        return body.v === 1 ? { ended: body.ended === true } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The error a joiner rejects with on a retirement. */
+export function retirementError(notice) {
+    return new Error(notice.ended ? ROOM_ENDED_MESSAGE : 'this room invitation has been retired');
+}
+/**
+ * Auto-admit anybody holding this link while this admitted member is online.
+ *
+ * Closing the returned handle stops this responder. People
+ * already admitted necessarily retain the room secret they were given; link
+ * rotation is not member revocation and the UI must never claim that it is.
+ */
+export function hostRoomInvitation(opts) {
+    require32(opts.roomSecret, 'room secret');
+    const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
+    const delegation = opts.delegation ?? [];
+    const authority = verifyInvitationDelegation(opts.invitation, delegation, now());
+    if (authority === null || !hexEquals(getPublicKey(opts.inviterSk), authority)) {
+        throw new Error('responder is not delegated for invitation');
+    }
+    if (delegation.length > 0 && !hexEquals(delegation[0].room, deriveRoom(opts.roomSecret).roomId)) {
+        throw new Error('delegation names another room');
+    }
+    const responder = getPublicKey(opts.inviterSk);
+    const invitationId = deriveInvitationId(opts.invitation);
+    const answered = new Set();
+    let closed = false;
+    let unsubRequests = () => { };
+    let unsubRetirement = () => { };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        unsubRequests();
+        unsubRetirement();
+    };
+    // Subscribe to the durable tombstone before accepting requests. Real
+    // relays replay stored regular events, so a responder returning from an
+    // offline spell retires itself before it can keep an old link alive.
+    unsubRetirement = opts.transport.subscribe([{ kinds: [KINDS.INVITATION_RETIREMENT], '#d': [invitationId], authors: [opts.invitation.inviter] }], (event) => {
+        if (!decodeInvitationRetirement(event, opts.invitation))
+            return;
+        close();
+        opts.onRetired?.();
+    });
+    if (closed) {
+        unsubRetirement();
+        return { close };
+    }
+    unsubRequests = opts.transport.subscribe([{ kinds: [KINDS.INVITATION_REQUEST], '#d': [invitationId], '#p': [opts.invitation.inviter] }], (event) => {
+        if (closed)
+            return;
+        const request = decodeInvitationRequest(event, { invitation: opts.invitation, now: now() });
+        // Some relays incorrectly retain and replay ephemeral requests. A newly
+        // admitted delegate must not answer the request that admitted itself.
+        if (!request || hexEquals(request.device, responder) || answered.has(request.request))
+            return;
+        answered.add(request.request);
+        // A long-running public room must not grow this replay guard without
+        // bound. Duplicate requests are harmless after eviction: they only
+        // cause the same encrypted grant to be sent again.
+        if (answered.size > 256)
+            answered.delete(answered.values().next().value);
+        const grantNow = () => {
+            if (closed)
+                return;
+            let grant;
+            try {
+                grant = encodeInvitationGrant({
+                    invitation: opts.invitation,
+                    inviterSk: opts.inviterSk,
+                    requester: request.device,
+                    request: request.request,
+                    roomSecret: opts.roomSecret,
+                    now: now(),
+                    delegation,
+                    ...(opts.epoch ? { epoch: opts.epoch() } : {}),
+                });
+            }
+            catch {
+                // Expired or maximum-depth authority is no authority. Subscription
+                // callbacks must never throw and take the caller's relay loop down.
+                close();
+                return;
+            }
+            opts.transport.publish(grant).catch(() => { });
+            opts.onAdmitted?.(request.device);
+        };
+        if (!opts.admit) {
+            grantNow();
+            return;
+        }
+        // A host that asks first answers later, if at all. Never awaited in
+        // the relay callback, and a hook that throws declines.
+        Promise.resolve()
+            .then(() => opts.admit(request))
+            .then((yes) => { if (yes)
+            grantNow(); })
+            .catch(() => { });
+    });
+    return { close };
+}
+/** Resolve the room and a bounded responder delegation, with no account or
+ * prompt. Retaining the delegation is what removes the creator as an
+ * availability dependency for the next arrival. */
+export function requestRoomAdmissionCapability(opts) {
+    const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
+    const requesterSk = opts.requesterSk ?? generateSecretKey();
+    const requester = getPublicKey(requesterSk);
+    const request = encodeInvitationRequest({
+        invitation: opts.invitation, requesterSk, now: now(),
+        ...(opts.name !== undefined ? { name: opts.name } : {}),
+        ...(opts.participant !== undefined ? { participant: opts.participant } : {}),
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let retry;
+        let expiry;
+        const invitationId = deriveInvitationId(opts.invitation);
+        let unsub = () => { };
+        unsub = opts.transport.subscribe([
+            { kinds: [KINDS.INVITATION_GRANT], '#d': [invitationId], '#p': [requester] },
+            { kinds: [KINDS.INVITATION_RETIREMENT], '#d': [invitationId], authors: [opts.invitation.inviter] },
+        ], (event) => {
+            const retired = decodeInvitationRetirementNotice(event, opts.invitation);
+            if (retired) {
+                finish(() => reject(retirementError(retired)));
+                return;
+            }
+            const admission = decodeRoomAdmissionGrant(event, {
+                invitation: opts.invitation,
+                requesterSk,
+                request: request.id,
+                now: now(),
+            });
+            if (admission)
+                finish(() => resolve(admission));
+        });
+        if (settled)
+            unsub();
+        function finish(settle) {
+            if (settled)
+                return;
+            settled = true;
+            if (retry !== undefined)
+                clearInterval(retry);
+            if (expiry !== undefined)
+                clearTimeout(expiry);
+            unsub();
+            settle();
+        }
+        function ask() {
+            if (!settled)
+                opts.transport.publish(request).catch(() => { });
+        }
+        expiry = setTimeout(() => finish(() => reject(new Error('the room is not answering this invitation'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        retry = setInterval(ask, opts.retryMs ?? DEFAULT_RETRY_MS);
+        ask();
+    });
+}
+/** Compatibility wrapper for non-interactive consumers. It joins correctly,
+ * but discards the ability to keep the link available for somebody else. */
+export async function requestRoomAdmission(opts) {
+    return (await requestRoomAdmissionCapability(opts)).secret;
+}
+/** Every wire-format literal this module owns (each one a kithmoot protocol string), frozen for
+ *  `src/labels.test.ts`, which checks each module against its own exported
+ *  list rather than scanning file text for matching comments. Pure data -
+ *  adding this export changes no runtime behaviour. */
+export const INVITATION_LABELS = [
+    "kithmoot/v2/invitation-delegation:",
+    "kithmoot/v2/invitation-id",
+    "kithmoot/v2/invitation-request-key",
+];

package/dist/kinds.d.ts

@@ -0,0 +1,64 @@
+/** Circle-layer wire kinds: a subset of KithMoot's `src/kinds.ts`, copied
+ * byte-identical per entry from the pinned source commit (see
+ * EXTRACTION.md in this repository). KithMoot's own `kinds.ts` spreads
+ * these into its wider `KINDS` object and keeps the rest (roster,
+ * signalling, descriptor, pairing, call bell, and so on) itself.
+ *
+ * `CHAT` (1460) is included because a downstream app's own board events
+ * are designed to share KithMoot's chat kind, so a relay cannot tell a
+ * board from a chat (see docs/extraction-plan-excerpt.md). */
+export declare const KINDS: {
+    /** Device credential. Signed by the participant key; never published to a
+     *  relay - it travels inside the encrypted roster, so relays never see the
+     *  participant pubkey. */
+    readonly CREDENTIAL: 20460;
+    /** Chat message, encrypted to the room key and published once, exactly
+     *  like the roster. Unlike the roster this is a DURABLE kind (regular
+     *  event range, not ephemeral) - chat history is the point, so it must
+     *  survive a relay restart and be there for late joiners. */
+    readonly CHAT: 1460;
+    /** A prospective member proving possession of a room invitation.
+     *
+     * Ephemeral deliberately: it is a live rendezvous with an inviter, not a
+     * request a relay should retain. The public `d` tag is derived from the
+     * bearer capability; the request body is encrypted under a separate key
+     * derived from that capability. */
+    readonly INVITATION_REQUEST: 20466;
+    /** A delegated responder's encrypted response carrying the room traffic
+     * secret and its root-authenticated, room-bound delegation chain. Addressed
+     * to the requester's one-use pubkey; knowing the bearer does not let
+     * somebody nominate a responder or substitute a room. Ephemeral for the
+     * same reason as the request. */
+    readonly INVITATION_GRANT: 20467;
+    /** A durable, creator-authenticated tombstone for one invitation.
+     *
+     * Unlike the live request/grant exchange this MUST be a regular stored
+     * event: a delegated responder that was offline when the creator rotated
+     * the link has to learn that fact before it starts answering the old link
+     * again. The invitation id is unique, so one valid retirement is final. */
+    readonly INVITATION_RETIREMENT: 1461;
+    /** A persistent group's invitation, signed by the pinned inviter and
+     * encrypted under a separate bearer-derived key. Regular stored event:
+     * newcomers can enter with every member offline. Contains epoch 0 only;
+     * it never grants authority to rekey or bypass a later removal. */
+    readonly GROUP_INVITATION: 1463;
+    /** A room moving to a new epoch: a fresh traffic secret, sealed per
+     * remaining device, with the participants removed at this step named.
+     *
+     * Durable, and addressed by the public room id, so a client can find the
+     * room's current epoch from the id alone and know it is behind before it
+     * says anything under a key that is dead. The body is encrypted to the
+     * previous epoch's key, so a relay sees the room id, the epoch number,
+     * the authority's pubkey and a size, and nothing about who was kept or
+     * removed. Signed only by the room's authority, the root inviter pinned
+     * in the link. See `epoch.ts`. */
+    readonly ROOM_REKEY: 1462;
+    /** A member that missed a rekey - it was offline, or it is arriving now -
+     * asking the authority for the current epoch, proving which participant it
+     * speaks for with its device credential. Encrypted to the authority and
+     * ephemeral: it is a live handshake, not a record. */
+    readonly EPOCH_REQUEST: 20468;
+    /** The authority's answer, sealed to the asking device: the current epoch's
+     * secret and the removed set, or a refusal. Ephemeral for the same reason. */
+    readonly EPOCH_GRANT: 20469;
+};

package/dist/kinds.js

@@ -0,0 +1,64 @@
+/** Circle-layer wire kinds: a subset of KithMoot's `src/kinds.ts`, copied
+ * byte-identical per entry from the pinned source commit (see
+ * EXTRACTION.md in this repository). KithMoot's own `kinds.ts` spreads
+ * these into its wider `KINDS` object and keeps the rest (roster,
+ * signalling, descriptor, pairing, call bell, and so on) itself.
+ *
+ * `CHAT` (1460) is included because a downstream app's own board events
+ * are designed to share KithMoot's chat kind, so a relay cannot tell a
+ * board from a chat (see docs/extraction-plan-excerpt.md). */
+export const KINDS = {
+    /** Device credential. Signed by the participant key; never published to a
+     *  relay - it travels inside the encrypted roster, so relays never see the
+     *  participant pubkey. */
+    CREDENTIAL: 20460,
+    /** Chat message, encrypted to the room key and published once, exactly
+     *  like the roster. Unlike the roster this is a DURABLE kind (regular
+     *  event range, not ephemeral) - chat history is the point, so it must
+     *  survive a relay restart and be there for late joiners. */
+    CHAT: 1460,
+    /** A prospective member proving possession of a room invitation.
+     *
+     * Ephemeral deliberately: it is a live rendezvous with an inviter, not a
+     * request a relay should retain. The public `d` tag is derived from the
+     * bearer capability; the request body is encrypted under a separate key
+     * derived from that capability. */
+    INVITATION_REQUEST: 20466,
+    /** A delegated responder's encrypted response carrying the room traffic
+     * secret and its root-authenticated, room-bound delegation chain. Addressed
+     * to the requester's one-use pubkey; knowing the bearer does not let
+     * somebody nominate a responder or substitute a room. Ephemeral for the
+     * same reason as the request. */
+    INVITATION_GRANT: 20467,
+    /** A durable, creator-authenticated tombstone for one invitation.
+     *
+     * Unlike the live request/grant exchange this MUST be a regular stored
+     * event: a delegated responder that was offline when the creator rotated
+     * the link has to learn that fact before it starts answering the old link
+     * again. The invitation id is unique, so one valid retirement is final. */
+    INVITATION_RETIREMENT: 1461,
+    /** A persistent group's invitation, signed by the pinned inviter and
+     * encrypted under a separate bearer-derived key. Regular stored event:
+     * newcomers can enter with every member offline. Contains epoch 0 only;
+     * it never grants authority to rekey or bypass a later removal. */
+    GROUP_INVITATION: 1463,
+    /** A room moving to a new epoch: a fresh traffic secret, sealed per
+     * remaining device, with the participants removed at this step named.
+     *
+     * Durable, and addressed by the public room id, so a client can find the
+     * room's current epoch from the id alone and know it is behind before it
+     * says anything under a key that is dead. The body is encrypted to the
+     * previous epoch's key, so a relay sees the room id, the epoch number,
+     * the authority's pubkey and a size, and nothing about who was kept or
+     * removed. Signed only by the room's authority, the root inviter pinned
+     * in the link. See `epoch.ts`. */
+    ROOM_REKEY: 1462,
+    /** A member that missed a rekey - it was offline, or it is arriving now -
+     * asking the authority for the current epoch, proving which participant it
+     * speaks for with its device credential. Encrypted to the authority and
+     * ephemeral: it is a live handshake, not a record. */
+    EPOCH_REQUEST: 20468,
+    /** The authority's answer, sealed to the asking device: the current epoch's
+     * secret and the removed set, or a refusal. Ephemeral for the same reason. */
+    EPOCH_GRANT: 20469,
+};

package/dist/lane.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The lane a message actually travelled, and what that lane delivers.
+ *
+ * Three states, fixed in meaning. A client shows the lane a message took,
+ * never the lane it asked for, and never claims more than the lane gives.
+ * The state is worked out from where the bytes went, so nothing on the
+ * wire can assert it: a message that says it was sheltered is not.
+ *
+ * - public: a relay operator could see who this was for and when.
+ * - sheltered: no operator outside your circle saw this.
+ * - direct: only the two devices were involved.
+ *
+ * Today a room's traffic rides ordinary relays, so almost everything is
+ * public. That is the honest answer and it is shown. Sheltered means the
+ * relay is a box the person's own circle runs, known from a contact card
+ * or the keeper's claim; an onion address on its own hides the client's
+ * address and says nothing about who runs the relay, so it stays public.
+ * A data channel is direct. As more carriers arrive they classify here,
+ * and nowhere else.
+ */
+export type Lane = 'public' | 'sheltered' | 'direct';
+export declare const LANES: readonly Lane[];
+/** The fixed meaning of each state, shown wherever the state is. */
+export declare const LANE_MEANING: Readonly<Record<Lane, string>>;
+/** Short label, readable without colour. */
+export declare const LANE_LABEL: Readonly<Record<Lane, string>>;
+/** A glyph beside the label, so the state is told apart without colour. */
+export declare const LANE_GLYPH: Readonly<Record<Lane, string>>;
+export declare function isLane(value: unknown): value is Lane;
+/**
+ * The lane one relay URL puts a message on. `circle` is the set of relay
+ * URLs the client knows to be boxes of the person's circle; a relay in it
+ * is sheltered and every other relay, onion or not, is public.
+ */
+export declare function laneOfRelayUrl(url: string, circle?: ReadonlySet<string>): Lane;
+/** The weakest of several lanes. Undefined when there are none. */
+export declare function weakestLane(lanes: readonly Lane[]): Lane | undefined;
+/** The lane a message takes when it is published to all of these relays. */
+export declare function laneOfRelays(urls: readonly string[], circle?: ReadonlySet<string>): Lane | undefined;
+/** A message went by a weaker lane than the one asked for. */
+export declare function isDowngrade(requested: Lane, actual: Lane): boolean;