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

package/dist/lane.js

@@ -0,0 +1,63 @@
+export const LANES = ['public', 'sheltered', 'direct'];
+/** The fixed meaning of each state, shown wherever the state is. */
+export const LANE_MEANING = {
+    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.',
+};
+/** Short label, readable without colour. */
+export const LANE_LABEL = {
+    public: 'public',
+    sheltered: 'sheltered',
+    direct: 'direct',
+};
+/** A glyph beside the label, so the state is told apart without colour. */
+export const LANE_GLYPH = {
+    public: '○',
+    sheltered: '◐',
+    direct: '●',
+};
+/** Weakest first. A message that touched a public relay is public,
+ *  whatever else it also touched. */
+const RANK = { public: 0, sheltered: 1, direct: 2 };
+export function isLane(value) {
+    return value === 'public' || value === 'sheltered' || value === 'direct';
+}
+/**
+ * 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 function laneOfRelayUrl(url, circle) {
+    if (circle && circle.has(url))
+        return 'sheltered';
+    try {
+        if (circle && circle.has(normaliseRelay(url)))
+            return 'sheltered';
+    }
+    catch {
+        // An unparseable URL is nobody's box.
+    }
+    return 'public';
+}
+function normaliseRelay(url) {
+    const u = new URL(url);
+    u.hostname = u.hostname.toLowerCase();
+    return u.toString().replace(/\/$/, '');
+}
+/** The weakest of several lanes. Undefined when there are none. */
+export function weakestLane(lanes) {
+    let out;
+    for (const lane of lanes)
+        if (out === undefined || RANK[lane] < RANK[out])
+            out = lane;
+    return out;
+}
+/** The lane a message takes when it is published to all of these relays. */
+export function laneOfRelays(urls, circle) {
+    return weakestLane(urls.map((u) => laneOfRelayUrl(u, circle)));
+}
+/** A message went by a weaker lane than the one asked for. */
+export function isDowngrade(requested, actual) {
+    return RANK[actual] < RANK[requested];
+}

package/dist/link.d.ts

@@ -0,0 +1,52 @@
+import type { RoomInvitation } from './invitation.js';
+import type { RoomPolicy } from './types.js';
+export { safeIceUrls, safeRelayUrls } from './network-hints.js';
+/** A normal room link is small enough for a QR code. This generous ceiling
+ * stops a fragment from becoming an unbounded base64/JSON allocation. */
+export declare const MAX_ROOM_LINK_FRAGMENT_LENGTH = 16384;
+/**
+ * Everything a room link carries, whichever version it is.
+ *
+ * The app has always written its own envelope around the library's join
+ * payload - relay hints, ICE hints, a pairing code - and read it back with
+ * a hand of helpers in the page. An agent joining from a Node process needs
+ * to read exactly the same link a person was sent, so the envelope is a
+ * library concern from here on: one parser, shared by the page and by
+ * anything else that is handed a link.
+ *
+ * Exactly one of `invitation` (v2 live rendezvous or v3 stored group) and
+ * `secret` (legacy version 1, the room traffic secret itself) is present.
+ */
+export interface RoomLink {
+    /** V2 meeting invitation or v3 persistent group invitation. */
+    invitation?: RoomInvitation;
+    /** Version 1: the room traffic secret, in the link. Legacy. */
+    secret?: Uint8Array;
+    /** Relay hints. Empty means the reader's defaults. */
+    relays: string[];
+    /** STUN/TURN hints. Empty means the reader's defaults. */
+    iceUrls: string[];
+    /** The room's admission rule, when it has one. */
+    policy?: RoomPolicy;
+    /** A one-off pairing code, on a link that adds a device. Never a key. */
+    pairingCode?: Uint8Array;
+    /**
+     * What the room is called, when whoever made the link gave it a name.
+     *
+     * A label for people, on the same terms as a display name: self-asserted,
+     * bounded by `sanitiseDisplayName`, and never load-bearing. It rides in
+     * the link because the link is the one thing every member of a room was
+     * handed, so a room a person is in on three devices is called the same
+     * thing on all of them. Absent when nobody named it.
+     */
+    name?: string;
+}
+/**
+ * Read a room link. Throws on a link that does not parse, and on one that
+ * carries an admission rule it cannot read - a dropped rule is an open
+ * room, and failing open is the mistake carrying the rule was meant to
+ * prevent.
+ */
+export declare function parseRoomLink(url: string): RoomLink;
+/** Write a room link, in the same envelope the app writes. */
+export declare function encodeRoomLink(base: string, link: RoomLink): string;

package/dist/link.js

@@ -0,0 +1,107 @@
+import { base64urlnopad } from '@scure/base';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { parseRoomPolicy } from './room.js';
+import { roomInvitation } from './invitation.js';
+import { sanitiseDisplayName } from './display-name.js';
+import { assertNetworkHintBounds, safeIceUrls, safeRelayUrls } from './network-hints.js';
+export { safeIceUrls, safeRelayUrls } from './network-hints.js';
+/** A normal room link is small enough for a QR code. This generous ceiling
+ * stops a fragment from becoming an unbounded base64/JSON allocation. */
+export const MAX_ROOM_LINK_FRAGMENT_LENGTH = 16_384;
+/**
+ * Read a room link. Throws on a link that does not parse, and on one that
+ * carries an admission rule it cannot read - a dropped rule is an open
+ * room, and failing open is the mistake carrying the rule was meant to
+ * prevent.
+ */
+export function parseRoomLink(url) {
+    const hash = new URL(url).hash.slice(1);
+    if (!hash)
+        throw new Error('join URL has no fragment');
+    if (hash.length > MAX_ROOM_LINK_FRAGMENT_LENGTH)
+        throw new Error('join URL fragment is too large');
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(base64urlnopad.decode(hash)));
+    }
+    catch {
+        throw new Error('join URL fragment is not valid');
+    }
+    if (typeof payload !== 'object' || payload === null)
+        throw new Error('join URL fragment is not valid');
+    if (payload.v !== undefined && payload.v !== 2 && payload.v !== 3)
+        throw new Error('join URL uses an unsupported version');
+    assertNetworkHintBounds(payload.r, payload.i);
+    const link = {
+        relays: safeRelayUrls(payload.r),
+        iceUrls: safeIceUrls(payload.i),
+    };
+    const policy = parseRoomPolicy(payload.a);
+    if (policy)
+        link.policy = policy;
+    // Sanitised on the way in like a display name, because a link is text a
+    // stranger wrote and a room name lands in the same places a name does.
+    const name = sanitiseDisplayName(typeof payload.n === 'string' ? payload.n : undefined);
+    if (name !== undefined)
+        link.name = name;
+    if (typeof payload.c === 'string') {
+        try {
+            link.pairingCode = hexToBytes(payload.c);
+        }
+        catch {
+            throw new Error('join URL carries a malformed pairing code');
+        }
+    }
+    if (payload.v === 2 || payload.v === 3) {
+        if (typeof payload.j !== 'string' || typeof payload.h !== 'string') {
+            throw new Error('join URL carries a malformed invitation');
+        }
+        let bearer;
+        try {
+            bearer = base64urlnopad.decode(payload.j);
+        }
+        catch {
+            throw new Error('join URL carries a malformed invitation');
+        }
+        link.invitation = roomInvitation(bearer, payload.h, payload.v === 3);
+        return link;
+    }
+    if (typeof payload.s !== 'string')
+        throw new Error('join URL carries neither an invitation nor a secret');
+    let secret;
+    try {
+        secret = base64urlnopad.decode(payload.s);
+    }
+    catch {
+        throw new Error('join URL carries a malformed secret');
+    }
+    if (secret.length !== 32)
+        throw new Error('join URL carries a malformed secret');
+    link.secret = secret;
+    return link;
+}
+/** Write a room link, in the same envelope the app writes. */
+export function encodeRoomLink(base, link) {
+    assertNetworkHintBounds(link.relays, link.iceUrls);
+    const relays = safeRelayUrls(link.relays);
+    const iceUrls = safeIceUrls(link.iceUrls);
+    const payload = link.invitation
+        ? { v: link.invitation.persistent ? 3 : 2, j: base64urlnopad.encode(link.invitation.bearer), h: link.invitation.inviter, r: relays, i: iceUrls }
+        : { s: base64urlnopad.encode(link.secret ?? invalid()), r: relays, i: iceUrls };
+    if (link.policy)
+        payload.a = link.policy;
+    if (link.pairingCode)
+        payload.c = bytesToHex(link.pairingCode);
+    // Written only when there is one, so a link to an unnamed room is
+    // byte-identical to one written before rooms had names.
+    const name = sanitiseDisplayName(link.name);
+    if (name !== undefined)
+        payload.n = name;
+    const fragment = base64urlnopad.encode(new TextEncoder().encode(JSON.stringify(payload)));
+    if (fragment.length > MAX_ROOM_LINK_FRAGMENT_LENGTH)
+        throw new Error('room link fragment is too large');
+    return `${base}#${fragment}`;
+}
+function invalid() {
+    throw new Error('a room link needs an invitation or a secret');
+}

package/dist/network-hints.d.ts

@@ -0,0 +1,16 @@
+/** Hard bounds for network addresses carried by an untrusted room link or
+ * descriptor. A handful of alternatives is useful; hundreds only spend
+ * parser, DNS and connection resources. */
+export declare const MAX_RELAY_HINTS = 8;
+export declare const MAX_ICE_HINTS = 8;
+export declare const MAX_NETWORK_HINT_LENGTH = 2048;
+/** Public relay hints must use encrypted WebSockets. Plain ws is retained
+ * only for loopback development and tests, where TLS adds no transport
+ * boundary. */
+export declare function isSafeRelayUrl(raw: string): boolean;
+export declare function safeRelayUrls(raw: unknown): string[];
+export declare function isSafeIceUrl(raw: string): boolean;
+export declare function safeIceUrls(raw: unknown): string[];
+/** Refuse oversized arrays instead of silently turning an attacker's first
+ * few entries into connection attempts. */
+export declare function assertNetworkHintBounds(relays: unknown, ice: unknown): void;

package/dist/network-hints.js

@@ -0,0 +1,65 @@
+/** Hard bounds for network addresses carried by an untrusted room link or
+ * descriptor. A handful of alternatives is useful; hundreds only spend
+ * parser, DNS and connection resources. */
+export const MAX_RELAY_HINTS = 8;
+export const MAX_ICE_HINTS = 8;
+export const MAX_NETWORK_HINT_LENGTH = 2048;
+const ICE_SCHEMES = ['stun:', 'stuns:', 'turn:', 'turns:'];
+function loopback(hostname) {
+    const host = hostname.toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1';
+}
+/** Public relay hints must use encrypted WebSockets. Plain ws is retained
+ * only for loopback development and tests, where TLS adds no transport
+ * boundary. */
+export function isSafeRelayUrl(raw) {
+    if (raw.length === 0 || raw.length > MAX_NETWORK_HINT_LENGTH)
+        return false;
+    try {
+        const parsed = new URL(raw);
+        return parsed.protocol === 'wss:' || (parsed.protocol === 'ws:' && loopback(parsed.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+export function safeRelayUrls(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== 'string' || !isSafeRelayUrl(value) || out.includes(value))
+            continue;
+        if (out.length === MAX_RELAY_HINTS)
+            break;
+        out.push(value);
+    }
+    return out;
+}
+export function isSafeIceUrl(raw) {
+    if (raw.length === 0 || raw.length > MAX_NETWORK_HINT_LENGTH)
+        return false;
+    const lower = raw.toLowerCase();
+    return ICE_SCHEMES.some((scheme) => lower.startsWith(scheme));
+}
+export function safeIceUrls(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== 'string' || !isSafeIceUrl(value) || out.includes(value))
+            continue;
+        if (out.length === MAX_ICE_HINTS)
+            break;
+        out.push(value);
+    }
+    return out;
+}
+/** Refuse oversized arrays instead of silently turning an attacker's first
+ * few entries into connection attempts. */
+export function assertNetworkHintBounds(relays, ice) {
+    if (Array.isArray(relays) && relays.length > MAX_RELAY_HINTS)
+        throw new Error('join URL carries too many relay hints');
+    if (Array.isArray(ice) && ice.length > MAX_ICE_HINTS)
+        throw new Error('join URL carries too many ICE hints');
+}

package/dist/persistent-invitation.d.ts

@@ -0,0 +1,35 @@
+import { type Event } from 'nostr-tools/pure';
+import { type RoomInvitation } from './invitation.js';
+import type { RelayTransport } from './transport.js';
+/** Durable membership is distinct from temporary permission to admit others.
+ * No inviter or delegated signing key is handed to a group member. */
+export interface PersistentRoomAdmission {
+    secret: Uint8Array;
+    persistent: true;
+    epoch: 0;
+}
+/** Publish once before sharing. The link plus this envelope is a durable
+ * bearer capability: anybody holding both can learn epoch 0. Retirement
+ * tells cooperative clients to stop admitting; it cannot erase copies. */
+export declare function encodePersistentInvitation(opts: {
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+    roomSecret: Uint8Array;
+    now: number;
+}): Event;
+export declare function decodePersistentInvitation(event: Event, invitation: RoomInvitation): PersistentRoomAdmission | null;
+/** Fetch the signed envelope and retirement in ONE stored-event query.
+ * Wait for EOSE even if the welcome arrives first: a tombstone replayed
+ * later in the same result must win. A timeout never admits on partial
+ * results. Relays remain an availability dependency, as they are for chat;
+ * no member or keeper has to answer a live request. */
+export declare function requestPersistentRoomAdmission(opts: {
+    transport: RelayTransport;
+    invitation: RoomInvitation;
+    timeoutMs?: number;
+}): Promise<PersistentRoomAdmission>;
+/** 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 declare const PERSISTENT_INVITATION_LABELS: readonly ["kithmoot/v3/group-invitation-key"];

package/dist/persistent-invitation.js

@@ -0,0 +1,118 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { base64urlnopad } from '@scure/base';
+import { nip44 } from 'nostr-tools';
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { decodeInvitationRetirementNotice, deriveInvitationId, retirementError } from './invitation.js';
+import { KINDS } from './kinds.js';
+import { deriveRoom } from './room.js';
+import { verifyEventUncached } from './verify.js';
+function welcomeKey(invitation) {
+    if (!invitation.persistent)
+        throw new Error('a persistent group invitation is required');
+    if (invitation.bearer.length !== 32)
+        throw new Error('invitation bearer must be 32 bytes');
+    return hkdf(sha256, invitation.bearer, undefined, 'kithmoot/v3/group-invitation-key', 32);
+}
+/** Publish once before sharing. The link plus this envelope is a durable
+ * bearer capability: anybody holding both can learn epoch 0. Retirement
+ * tells cooperative clients to stop admitting; it cannot erase copies. */
+export function encodePersistentInvitation(opts) {
+    if (getPublicKey(opts.inviterSk) !== opts.invitation.inviter)
+        throw new Error('only the inviter can publish a group invitation');
+    const room = deriveRoom(opts.roomSecret).roomId;
+    return finalizeEvent({
+        kind: KINDS.GROUP_INVITATION,
+        created_at: opts.now,
+        tags: [['d', deriveInvitationId(opts.invitation)]],
+        content: nip44.v2.encrypt(JSON.stringify({
+            v: 3, room, secret: base64urlnopad.encode(opts.roomSecret),
+        }), welcomeKey(opts.invitation)),
+    }, opts.inviterSk);
+}
+export function decodePersistentInvitation(event, invitation) {
+    try {
+        if (event.kind !== KINDS.GROUP_INVITATION || event.pubkey !== invitation.inviter)
+            return null;
+        if (!verifyEventUncached(event))
+            return null;
+        if (event.tags.filter(t => t[0] === 'd').length !== 1 ||
+            event.tags.find(t => t[0] === 'd')?.[1] !== deriveInvitationId(invitation))
+            return null;
+        const body = JSON.parse(nip44.v2.decrypt(event.content, welcomeKey(invitation)));
+        if (body.v !== 3 || typeof body.secret !== 'string')
+            return null;
+        const secret = base64urlnopad.decode(body.secret);
+        if (deriveRoom(secret).roomId !== body.room)
+            return null;
+        return { secret, persistent: true, epoch: 0 };
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch the signed envelope and retirement in ONE stored-event query.
+ * Wait for EOSE even if the welcome arrives first: a tombstone replayed
+ * later in the same result must win. A timeout never admits on partial
+ * results. Relays remain an availability dependency, as they are for chat;
+ * no member or keeper has to answer a live request. */
+export function requestPersistentRoomAdmission(opts) {
+    if (!opts.invitation.persistent)
+        return Promise.reject(new Error('a persistent group invitation is required'));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let admission;
+        let unsub = () => { };
+        const timer = setTimeout(() => finish(new Error('the group invitation could not be loaded from its relays')), opts.timeoutMs ?? 15_000);
+        function finish(error) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            unsub();
+            if (error)
+                reject(error);
+            else
+                resolve(admission);
+        }
+        try {
+            unsub = opts.transport.subscribe([{
+                    kinds: [KINDS.GROUP_INVITATION, KINDS.INVITATION_RETIREMENT],
+                    authors: [opts.invitation.inviter], '#d': [deriveInvitationId(opts.invitation)],
+                }], event => {
+                if (settled)
+                    return;
+                const retired = decodeInvitationRetirementNotice(event, opts.invitation);
+                if (retired) {
+                    finish(retirementError(retired));
+                    return;
+                }
+                const decoded = decodePersistentInvitation(event, opts.invitation);
+                if (!decoded)
+                    return;
+                if (admission && deriveRoom(admission.secret).roomId !== deriveRoom(decoded.secret).roomId) {
+                    finish(new Error('the group invitation names conflicting rooms'));
+                    return;
+                }
+                admission = decoded;
+            }, () => {
+                if (admission)
+                    finish();
+                else
+                    finish(new Error('the group invitation is not available on its relays'));
+            });
+            if (settled)
+                unsub();
+        }
+        catch (error) {
+            finish(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+}
+/** 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 PERSISTENT_INVITATION_LABELS = [
+    "kithmoot/v3/group-invitation-key",
+];

package/dist/room.d.ts

@@ -0,0 +1,53 @@
+import type { RoomPolicy } from './types.js';
+/** Generate a fresh 32-byte room traffic secret.
+ *
+ * Legacy v1 links carry this directly. New app links exchange it through
+ * `invitation.ts` and never expose it in the URL. */
+export declare function generateRoomSecret(): Uint8Array;
+/**
+ * Derive the public room identifier and the symmetric room key from the secret.
+ *
+ * The two are derived with separate HKDF info strings so that publishing the
+ * room id (which relays necessarily see) reveals nothing about the room key.
+ */
+export declare function deriveRoom(secret: Uint8Array): {
+    roomId: string;
+    roomKey: Uint8Array;
+};
+/**
+ * Parse an access policy out of a URL fragment, which is untrusted input.
+ *
+ * A policy that does not parse is refused rather than silently dropped: a
+ * dropped policy is an open room, and failing open is exactly the mistake
+ * carrying the policy in the capability is meant to prevent.
+ */
+export declare function parseRoomPolicy(raw: unknown): RoomPolicy | undefined;
+/**
+ * Build a legacy v1 join URL. The secret and relay hints live in the fragment, which
+ * browsers never transmit to the server - the host of kithmoot.com learns
+ * nothing about which room you are joining.
+ *
+ * Encoding uses @scure/base and TextEncoder/TextDecoder rather than a
+ * Node-only global: this library ships to a browser PWA as well as to Node,
+ * and Node-only globals do not exist there.
+ *
+ * The access policy rides here too. It is deliberately NOT a room descriptor
+ * event on a relay: the URL is the capability, so everyone who joins holds
+ * the same policy bytes and agreement is structural, with nothing to fetch
+ * before a member can check another member's tier and no durable artefact of
+ * the room on any relay. The cost is that the policy cannot change mid-room -
+ * a new rule is a new link. See `docs/decisions.md`.
+ */
+export declare function encodeJoinUrl(base: string, secret: Uint8Array, relays: string[], policy?: RoomPolicy): string;
+/** Decode a legacy v1 room-secret link. Version 2 invitation links are
+ * resolved by `invitation.ts` plus the app's URL envelope. */
+export declare function decodeJoinUrl(url: string): {
+    secret: Uint8Array;
+    relays: string[];
+    policy?: RoomPolicy;
+};
+/** 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 declare const ROOM_LABELS: readonly ["kithmoot/v1/room-id", "kithmoot/v1/room-key"];

package/dist/room.js

@@ -0,0 +1,153 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { randomBytes } from '@noble/hashes/utils';
+import { base64urlnopad } from '@scure/base';
+import { normaliseHex } from './hex.js';
+import { MAX_RELAY_HINTS, safeRelayUrls } from './network-hints.js';
+const ROOM_ID_INFO = 'kithmoot/v1/room-id';
+const ROOM_KEY_INFO = 'kithmoot/v1/room-key';
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/** Generate a fresh 32-byte room traffic secret.
+ *
+ * Legacy v1 links carry this directly. New app links exchange it through
+ * `invitation.ts` and never expose it in the URL. */
+export function generateRoomSecret() {
+    return randomBytes(32);
+}
+/**
+ * Derive the public room identifier and the symmetric room key from the secret.
+ *
+ * The two are derived with separate HKDF info strings so that publishing the
+ * room id (which relays necessarily see) reveals nothing about the room key.
+ */
+export function deriveRoom(secret) {
+    if (secret.length !== 32)
+        throw new Error('room secret must be 32 bytes');
+    const idBytes = hkdf(sha256, secret, undefined, ROOM_ID_INFO, 32);
+    const roomKey = hkdf(sha256, secret, undefined, ROOM_KEY_INFO, 32);
+    const roomId = Array.from(idBytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return { roomId, roomKey };
+}
+const TIERS = ['open', 'ken', 'kith', 'kin'];
+const AGENT_RULES = ['owned-by-members'];
+const MAX_POLICY_KEYS = 256;
+/**
+ * Parse an access policy out of a URL fragment, which is untrusted input.
+ *
+ * A policy that does not parse is refused rather than silently dropped: a
+ * dropped policy is an open room, and failing open is exactly the mistake
+ * carrying the policy in the capability is meant to prevent.
+ */
+export function parseRoomPolicy(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object')
+        throw new Error('join URL carries a malformed access policy');
+    const policy = raw;
+    if (!TIERS.includes(policy.tier))
+        throw new Error('join URL carries an access policy at an unknown tier');
+    if (policy.admitted !== undefined) {
+        if (!Array.isArray(policy.admitted) || policy.admitted.length > MAX_POLICY_KEYS ||
+            !policy.admitted.every((a) => typeof a === 'string' && /^[0-9a-fA-F]{64}$/.test(a))) {
+            throw new Error('join URL carries a malformed access policy');
+        }
+    }
+    // A members list is a closed door, so a malformed one is refused rather
+    // than dropped: dropping it would open the room to anybody with the link.
+    if (policy.members !== undefined) {
+        if (!Array.isArray(policy.members) || policy.members.length === 0 || policy.members.length > MAX_POLICY_KEYS ||
+            !policy.members.every((m) => typeof m === 'string' && /^[0-9a-fA-F]{64}$/.test(m))) {
+            throw new Error('join URL carries a malformed members list');
+        }
+    }
+    // An agent rule this reader does not know is refused for the same reason
+    // an unknown tier is: dropping it would admit what the room meant to keep
+    // out.
+    if (policy.agents !== undefined && !AGENT_RULES.includes(policy.agents)) {
+        throw new Error('join URL carries an access policy with an unknown agent rule');
+    }
+    // A quiet room without a members list has nobody to derive keys for, and
+    // a quiet flag in any shape but `true` is a reader that would talk in the
+    // open while the rest of the room talks in drops. Both refused.
+    if (policy.quiet !== undefined && (policy.quiet !== true || policy.members === undefined)) {
+        throw new Error('join URL asks for a quiet room without a members list');
+    }
+    // The allow-list is exactly the case this rule was written for: entries a
+    // person typed or pasted into a link. Canonicalise here, at the point they
+    // enter the system off the URL, rather than relying on every reader to
+    // compare them case-insensitively.
+    const parsed = policy.admitted
+        ? { tier: policy.tier, admitted: policy.admitted.map(normaliseHex) }
+        : { tier: policy.tier };
+    if (policy.agents !== undefined)
+        parsed.agents = policy.agents;
+    if (policy.members !== undefined)
+        parsed.members = [...new Set(policy.members.map(normaliseHex))];
+    if (policy.quiet === true)
+        parsed.quiet = true;
+    return parsed;
+}
+/**
+ * Build a legacy v1 join URL. The secret and relay hints live in the fragment, which
+ * browsers never transmit to the server - the host of kithmoot.com learns
+ * nothing about which room you are joining.
+ *
+ * Encoding uses @scure/base and TextEncoder/TextDecoder rather than a
+ * Node-only global: this library ships to a browser PWA as well as to Node,
+ * and Node-only globals do not exist there.
+ *
+ * The access policy rides here too. It is deliberately NOT a room descriptor
+ * event on a relay: the URL is the capability, so everyone who joins holds
+ * the same policy bytes and agreement is structural, with nothing to fetch
+ * before a member can check another member's tier and no durable artefact of
+ * the room on any relay. The cost is that the policy cannot change mid-room -
+ * a new rule is a new link. See `docs/decisions.md`.
+ */
+export function encodeJoinUrl(base, secret, relays, policy) {
+    if (secret.length !== 32)
+        throw new Error('room secret must be 32 bytes');
+    const payload = { s: base64urlnopad.encode(secret), r: relays };
+    if (policy)
+        payload.a = policy;
+    const encoded = base64urlnopad.encode(utf8Encoder.encode(JSON.stringify(payload)));
+    return `${base}#${encoded}`;
+}
+/** Decode a legacy v1 room-secret link. Version 2 invitation links are
+ * resolved by `invitation.ts` plus the app's URL envelope. */
+export function decodeJoinUrl(url) {
+    const hash = new URL(url).hash.slice(1);
+    if (!hash)
+        throw new Error('join URL has no fragment');
+    if (hash.length > 16_384)
+        throw new Error('join URL fragment is too large');
+    let payload;
+    try {
+        payload = JSON.parse(utf8Decoder.decode(base64urlnopad.decode(hash)));
+    }
+    catch {
+        throw new Error('join URL fragment is not valid');
+    }
+    let secret;
+    try {
+        secret = base64urlnopad.decode(payload.s);
+    }
+    catch {
+        throw new Error('join URL carries a malformed secret');
+    }
+    if (secret.length !== 32)
+        throw new Error('join URL carries a malformed secret');
+    if (Array.isArray(payload.r) && payload.r.length > MAX_RELAY_HINTS)
+        throw new Error('join URL carries too many relay hints');
+    const policy = parseRoomPolicy(payload.a);
+    const relays = safeRelayUrls(payload.r);
+    return policy ? { secret, relays, policy } : { secret, relays };
+}
+/** 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 ROOM_LABELS = [
+    "kithmoot/v1/room-id",
+    "kithmoot/v1/room-key",
+];