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

package/dist/display-name.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Display names.
+ *
+ * A name in this protocol is **self-asserted**: whoever holds a participant
+ * key types whatever they like, and nothing anywhere checks it. That is the
+ * point - joining a room should cost a name and nothing else - but it means
+ * a name is attacker-controlled text arriving off a relay, and every reader
+ * has to treat it as such.
+ *
+ * Two rules follow, and they live in different places:
+ *
+ *   1. **Sanitise it.** Everything below. A name may not carry characters
+ *      that let it take a second row, hide part of itself, or reverse the
+ *      direction the rest of the line renders in, and it may not be long
+ *      enough to push everything else off the row.
+ *
+ *   2. **Never render it alone, and never as HTML.** Both are the caller's
+ *      job, because both are about what a name sits next to. A short pubkey
+ *      always renders beside it, so two people called "Robin" stay
+ *      distinguishable and an impersonation is visible; and it goes in via
+ *      `textContent`, never `innerHTML`, so markup in a name stays text.
+ */
+/**
+ * How long a name may be, in characters.
+ *
+ * Counted in code points rather than UTF-16 units, so one emoji costs one -
+ * a cap in UTF-16 units would let an astral-plane name be twice as wide as
+ * an ASCII one, and could cut a surrogate pair in half.
+ */
+export declare const MAX_DISPLAY_NAME_LENGTH = 32;
+/**
+ * Make a name safe to put next to somebody else's, or return undefined if
+ * there is nothing left worth showing.
+ *
+ * Takes `unknown` because this runs on JSON off a relay as well as on a
+ * field somebody typed, and anything at all can arrive in either.
+ */
+export declare function sanitiseDisplayName(raw: unknown): string | undefined;

package/dist/display-name.js

@@ -0,0 +1,78 @@
+/**
+ * Display names.
+ *
+ * A name in this protocol is **self-asserted**: whoever holds a participant
+ * key types whatever they like, and nothing anywhere checks it. That is the
+ * point - joining a room should cost a name and nothing else - but it means
+ * a name is attacker-controlled text arriving off a relay, and every reader
+ * has to treat it as such.
+ *
+ * Two rules follow, and they live in different places:
+ *
+ *   1. **Sanitise it.** Everything below. A name may not carry characters
+ *      that let it take a second row, hide part of itself, or reverse the
+ *      direction the rest of the line renders in, and it may not be long
+ *      enough to push everything else off the row.
+ *
+ *   2. **Never render it alone, and never as HTML.** Both are the caller's
+ *      job, because both are about what a name sits next to. A short pubkey
+ *      always renders beside it, so two people called "Robin" stay
+ *      distinguishable and an impersonation is visible; and it goes in via
+ *      `textContent`, never `innerHTML`, so markup in a name stays text.
+ */
+/**
+ * How long a name may be, in characters.
+ *
+ * Counted in code points rather than UTF-16 units, so one emoji costs one -
+ * a cap in UTF-16 units would let an astral-plane name be twice as wide as
+ * an ASCII one, and could cut a surrogate pair in half.
+ */
+export const MAX_DISPLAY_NAME_LENGTH = 32;
+/**
+ * Every Unicode "other" character: controls (Cc), format characters (Cf),
+ * surrogates (Cs), private use (Co) and unassigned code points (Cn).
+ *
+ * That single class covers the whole family of tricks a name is used for:
+ * a newline taking a second row, a bidirectional override (U+202E and
+ * friends) making the rest of the line render backwards, a zero-width
+ * space hiding the difference between two names, a byte-order mark padding
+ * one invisibly. Naming the class rather than listing the code points is
+ * deliberate: the list grows with Unicode, and a filter that has to be
+ * updated to stay correct is a filter that will one day be out of date.
+ *
+ * It also removes U+200D ZERO WIDTH JOINER, so a joined emoji sequence
+ * comes apart into its parts. That is a real cost, accepted knowingly: an
+ * invisible character that changes what a name looks like is exactly the
+ * thing being removed, and there is no way to keep one and not the other.
+ */
+const INVISIBLE = /\p{C}/gu;
+/** Any run of whitespace, including the Unicode ones. */
+const WHITESPACE = /\s+/gu;
+/**
+ * Make a name safe to put next to somebody else's, or return undefined if
+ * there is nothing left worth showing.
+ *
+ * Takes `unknown` because this runs on JSON off a relay as well as on a
+ * field somebody typed, and anything at all can arrive in either.
+ */
+export function sanitiseDisplayName(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    // Whitespace first, invisibles second, and the order matters: a newline
+    // is itself a control character, so stripping controls first would turn
+    // "Robin\nadmin" into one word rather than two - hiding the smuggled
+    // line break instead of defusing it.
+    const collapsed = raw.replace(WHITESPACE, ' ').replace(INVISIBLE, '').replace(WHITESPACE, ' ').trim();
+    if (!collapsed)
+        return undefined;
+    // Split into code points before slicing: `String.prototype.slice` counts
+    // UTF-16 units and would cut a surrogate pair in half, leaving a lone
+    // surrogate on the wire.
+    const characters = [...collapsed];
+    if (characters.length <= MAX_DISPLAY_NAME_LENGTH)
+        return collapsed;
+    // Re-trimmed, because the cap can land mid-word and leave a trailing
+    // space that would then render as a name ending in nothing.
+    const capped = characters.slice(0, MAX_DISPLAY_NAME_LENGTH).join('').trim();
+    return capped || undefined;
+}

package/dist/epoch.d.ts

@@ -0,0 +1,387 @@
+import { type Event } from 'nostr-tools/pure';
+import type { RelayTransport } from './transport.js';
+import type { DeviceCredential, KindredProof, RoomPolicy } from './types.js';
+/**
+ * Room epochs: how a member is removed.
+ *
+ * A room's traffic key is derived from its secret, and everybody who was
+ * ever admitted holds it. Link rotation retires the rendezvous and nothing
+ * else: a departed collaborator, or a leaked agent key, reads the room for
+ * as long as the room lives. The only thing that ends that is a new key
+ * that the departed party is not given, and that is an epoch.
+ *
+ * Epoch 0 is the room as it has always been: the id and key `deriveRoom`
+ * produces from the secret in the link, byte for byte. Every later epoch is
+ * a fresh 32-byte secret from which its own id and key are derived, under
+ * info strings that name the epoch number. The roster, the chat and its
+ * channels, the descriptor and the media keys all move to the new epoch's
+ * id and key together; the *room id* - what a credential binds to, what a
+ * signal names, what a forwarder is given - does not move, because it is
+ * the room's identity rather than its key.
+ *
+ * The move is announced by a rekey event: durable, addressed by the public
+ * room id, numbered in a tag, signed by the room's authority (the root
+ * inviter pinned in the link), and carrying the new secret sealed to each
+ * remaining device. Its body is encrypted to the epoch being left, so a
+ * member at that epoch reads it and moves, and a relay reads nothing but a
+ * number. A member that missed one asks the authority for the current
+ * epoch, proving who it is with its device credential and that it was
+ * admitted with a proof under the room key, and the authority answers
+ * everybody except the removed.
+ *
+ * The admission proof is what keeps the desk from being a back door. The
+ * room id and the authority's pubkey are public: both ride in the clear on
+ * every rekey event. A device credential is self-issued by whichever
+ * participant key signs it. So a request carrying only a credential proves
+ * nothing a stranger reading the relay could not produce, and in an open
+ * room the desk would hand that stranger the current epoch's secret, which
+ * opens the roster and the chat. The epoch-0 room key is the one thing the
+ * link hands out and nothing else does, so a MAC under a key derived from
+ * it is proof of having been admitted, and the desk demands one.
+ *
+ * Copies are sealed to the *device* pubkey, not the participant's, because
+ * the device key is the one every session holds in memory: a participant
+ * key may live in a browser extension or a bunker that signs and does
+ * nothing else, and the identity surface is deliberately a pubkey and one
+ * `signEvent` (see `identity.ts`). The participant is what a rekey names -
+ * the removed set, the refusal - and the device credential is how a device
+ * proves which participant it speaks for when it asks.
+ */
+export declare const EPOCH_ID_INFO = "kithmoot/v1/epoch-id";
+export declare const EPOCH_KEY_INFO = "kithmoot/v1/epoch-key";
+/** A room that has been rekeyed more times than this has a problem that is
+ *  not this module's to solve. Bounds the tag a client will parse. */
+export declare const MAX_EPOCH = 1000000;
+/**
+ * HKDF info string for the key an epoch request's admission proof is made
+ * under. Its own domain, like the media key's: a proof key that was the
+ * room key would put the room key itself into a MAC on every request, and
+ * a key that is only the epoch-request key opens nothing else if it leaks.
+ */
+export declare const EPOCH_REQUEST_KEY_INFO = "kithmoot/v1/epoch-request-key";
+/** One epoch of a room. Epoch 0's secret is the room secret itself. */
+export interface RoomEpoch {
+    epoch: number;
+    secret: Uint8Array;
+}
+/** What the roster, chat and descriptor ride under in one epoch. */
+export interface EpochKeys {
+    epoch: number;
+    /** The `d` tag root. The room id in epoch 0. */
+    id: string;
+    /** The cipher key. The room key in epoch 0. */
+    key: Uint8Array;
+}
+/** A fresh secret for the next epoch. */
+export declare function generateEpochSecret(): Uint8Array;
+/**
+ * The id and key a room's traffic rides under in `epoch`.
+ *
+ * Epoch 0 is exactly `deriveRoom(secret)`, so a room that has never been
+ * rekeyed is byte-identical on the wire to one from before epochs existed.
+ * Every later epoch expands its own secret under info strings that carry
+ * the epoch number, so the same secret at two numbers - which a correct
+ * authority never produces - would still derive two different keys.
+ */
+export declare function deriveEpoch(epoch: RoomEpoch): EpochKeys;
+export interface EncodeRekeyOptions {
+    roomId: string;
+    /** The room's authority: the root inviter key. Only it may rekey. */
+    authoritySk: Uint8Array;
+    /** The epoch being left. Its key seals the body. */
+    current: EpochKeys;
+    /** The epoch being entered. Must be `current.epoch + 1`. */
+    next: RoomEpoch;
+    /** Devices to seal the new secret for. Everybody still in the room,
+     *  except the removed participants' devices. */
+    recipients: string[];
+    /** Participants removed at this step. Empty on a rekey that only turns
+     *  the key over. */
+    removed: string[];
+    /** The admin who asked, when one did. */
+    by?: string;
+    /** True when the room is being closed: nobody is kept, and the event
+     *  says so rather than leaving everybody to wonder. */
+    closed?: boolean;
+    now: number;
+}
+/** Announce the next epoch. See the module comment for what this is. */
+export declare function encodeRekeyEvent(opts: EncodeRekeyOptions): Event;
+/** What a rekey says, once read. */
+export interface RekeyNotice {
+    epoch: number;
+    removed: string[];
+    by?: string;
+    closed: boolean;
+    /** The new secret, when a copy was sealed for this device. Absent for a
+     *  device that was removed, or that was not in the room when the
+     *  authority rekeyed. */
+    secret?: Uint8Array;
+    /** True for a current-state grant, whose removed list is cumulative.
+     *  It synchronises this session; it does not describe a new removal. */
+    catchUp?: true;
+    /** The authority's clock when it rekeyed, or receipt time for catch-up. */
+    at: number;
+}
+export interface PeekRekeyOptions {
+    roomId: string;
+    /** The authority pubkey: the root inviter pinned in the link. */
+    authority: string;
+}
+/**
+ * The epoch a rekey announces, checking everything that does not need a
+ * key: kind, room, signer, signature and the epoch tag. What a client uses
+ * to learn that the room is ahead of it before it can read why.
+ */
+export declare function peekRekeyEvent(event: Event, opts: PeekRekeyOptions): number | null;
+export interface DecodeRekeyOptions extends PeekRekeyOptions {
+    /** The epoch this device is at. A rekey is readable only from the epoch
+     *  it leaves, and only accepted when it moves forward. */
+    current: EpochKeys;
+    /** This device's key, to open its own copy. */
+    deviceSk: Uint8Array;
+}
+/**
+ * Read a rekey. Null for anything that does not check out, and for a rekey
+ * this device cannot read from where it stands: one for an epoch it is
+ * already past (a replay), or one sealed to an epoch it is not at.
+ */
+export declare function decodeRekeyEvent(event: Event, opts: DecodeRekeyOptions): RekeyNotice | null;
+/**
+ * The key an epoch request's admission proof is computed under: the epoch-0
+ * room key, expanded under its own info string. Taken from the room key
+ * rather than the room secret for the same reason the media key is: a
+ * joined client holds the room key and need not keep the capability.
+ */
+export declare function deriveEpochRequestKey(roomKey: Uint8Array): Uint8Array;
+export interface EpochRequestAdmissionOptions {
+    /** The epoch-0 room key: `deriveRoom(secret).roomKey`, never a later epoch's. */
+    roomKey: Uint8Array;
+    roomId: string;
+    authority: string;
+    device: string;
+    /** The request event's `created_at`. */
+    createdAt: number;
+}
+/**
+ * Prove, inside an epoch request, that the asking device was admitted to
+ * the room.
+ *
+ * `HMAC-SHA256(deriveEpochRequestKey(roomKey), "kithmoot/v1/epoch-request:" +
+ * roomId + ":" + authority + ":" + device + ":" + createdAt)`, as hex, with
+ * the three identifiers in lower-case hex. Bound to the device and the
+ * moment so that a proof lifted from one request is no use in another,
+ * though the body it rides in is already sealed to the authority. Every
+ * admitted device holds the epoch-0 room key, including one that has fallen
+ * several epochs behind, which is exactly who asks; a removed member holds
+ * it too, and is refused by name, not by this. What this refuses is the
+ * stranger: somebody with the room id and the authority's pubkey off a
+ * public rekey event, and no link.
+ */
+export declare function epochRequestAdmission(opts: EpochRequestAdmissionOptions): string;
+export interface EncodeEpochRequestOptions {
+    roomId: string;
+    authority: string;
+    deviceSk: Uint8Array;
+    /** The epoch-0 room key, which proves this device was admitted. */
+    roomKey: Uint8Array;
+    /** Proves which participant this device speaks for. */
+    credential: DeviceCredential;
+    proof?: KindredProof;
+    now: number;
+}
+/** Ask the authority which epoch the room is at, and for its secret. */
+export declare function encodeEpochRequest(opts: EncodeEpochRequestOptions): Event;
+export interface DecodeEpochRequestOptions {
+    roomId: string;
+    authoritySk: Uint8Array;
+    /** The epoch-0 room key the desk checks admission proofs against. */
+    roomKey: Uint8Array;
+    now: number;
+    policy?: RoomPolicy;
+    /** Participants whose already-signed device credential may bridge a
+     * pre-admission-proof client. Keep this narrow: a missing proof is never
+     * accepted for an ordinary link holder. */
+    legacyParticipants?: ReadonlySet<string>;
+    maxAgeSeconds?: number;
+}
+export interface EpochRequest {
+    device: string;
+    participant: string;
+    request: string;
+}
+/** Null for anything malformed, stale, misaddressed, from a device that
+ *  cannot prove which participant it speaks for in this room, or from one
+ *  that cannot prove it was admitted to the room at all. */
+export declare function decodeEpochRequest(event: Event, opts: DecodeEpochRequestOptions): EpochRequest | null;
+/** Why the authority would not hand an epoch over. */
+export type EpochRefusal = 'removed' | 'closed';
+export interface EncodeEpochGrantOptions {
+    roomId: string;
+    authoritySk: Uint8Array;
+    device: string;
+    request: string;
+    now: number;
+    /** The current epoch. Omitted when refusing. */
+    epoch?: RoomEpoch;
+    removed?: string[];
+    refused?: EpochRefusal;
+}
+/** Answer one request: the current epoch sealed to the asking device, or a
+ *  refusal it alone can read. */
+export declare function encodeEpochGrant(opts: EncodeEpochGrantOptions): Event;
+export interface DecodeEpochGrantOptions {
+    roomId: string;
+    authority: string;
+    deviceSk: Uint8Array;
+    request: string;
+    now: number;
+    maxAgeSeconds?: number;
+}
+export type EpochGrant = {
+    epoch: RoomEpoch | {
+        epoch: 0;
+    };
+    removed: string[];
+    refused?: undefined;
+} | {
+    refused: EpochRefusal;
+};
+/** Read the authority's answer to this device's own request. Null for
+ *  anything else. Note a grant for epoch 0 carries no secret: the room has
+ *  never been rekeyed, and the requester already holds what it needs. */
+export declare function decodeEpochGrant(event: Event, opts: DecodeEpochGrantOptions): EpochGrant | null;
+export interface HostRoomEpochOptions {
+    transport: RelayTransport;
+    roomId: string;
+    authoritySk: Uint8Array;
+    /** The epoch-0 room key: what a request has to prove it holds. */
+    roomKey: Uint8Array;
+    /** Where the room is now. Asked on every request, because it moves. */
+    current: () => RoomEpoch;
+    /** Who has been removed. Asked on every request, for the same reason. */
+    removed: () => ReadonlySet<string>;
+    /** True once the room has been closed: every request is refused. */
+    closed?: () => boolean;
+    policy?: RoomPolicy;
+    legacyParticipants?: ReadonlySet<string>;
+    now?: () => number;
+    onGranted?: (request: EpochRequest) => void;
+    onRefused?: (request: EpochRequest, why: EpochRefusal) => void;
+}
+/**
+ * Answer epoch requests for as long as the handle is open. What a keeper
+ * runs beside its invitation desk: a member arriving, or returning, after
+ * a rekey is handed the current epoch on proof of who it is and that it was
+ * admitted, and a removed participant is told no. This is where removal is
+ * enforced against the link: the link still admits its holder to the room's
+ * *secret*, which opens epoch 0 and nothing after it. A request with no
+ * admission proof, or one made under some other key, is not answered at
+ * all: a stranger learns nothing, not even that a desk is here.
+ */
+export declare function hostRoomEpoch(opts: HostRoomEpochOptions): {
+    close(): void;
+};
+export interface RequestRoomEpochOptions {
+    transport: RelayTransport;
+    roomId: string;
+    authority: string;
+    deviceSk: Uint8Array;
+    /** The epoch-0 room key, which proves this device was admitted. */
+    roomKey: Uint8Array;
+    credential: DeviceCredential;
+    proof?: KindredProof;
+    now?: () => number;
+    timeoutMs?: number;
+    retryMs?: number;
+}
+/** Thrown when the authority answered, and the answer was no. */
+export declare class EpochRefusedError extends Error {
+    readonly refused: EpochRefusal;
+    constructor(refused: EpochRefusal);
+}
+/** Ask the authority where the room is, and wait for the answer. Rejects
+ *  with `EpochRefusedError` on a refusal, and with a plain error when
+ *  nobody answers inside the timeout. */
+export declare function requestRoomEpoch(opts: RequestRoomEpochOptions): Promise<Exclude<EpochGrant, {
+    refused: EpochRefusal;
+}>>;
+/** Canonical form of an admin list: lower-case, deduplicated, sorted. */
+export declare function canonicalAdmins(admins: readonly string[]): string[];
+export interface SignAdminsOptions {
+    roomId: string;
+    epoch: number;
+    admins: readonly string[];
+    authoritySk: Uint8Array;
+}
+/**
+ * Channel names a room may be told about.
+ *
+ * Deliberately stricter than `deriveChannel`, which accepts any string of
+ * 1..64 characters because it is only doing HKDF and has no opinion. A name
+ * in the REGISTRY is different: it is announced to every client, rendered as
+ * a label, and handed to an agent as its thread id. So it is held to a shape
+ * that survives all three without escaping, normalising or truncating -
+ * lower case, digits and hyphens, opening on an alphanumeric.
+ *
+ * The consequence worth stating: a name is stored and compared exactly as
+ * written here, so a client, an agent adapter and a relay all mean the same
+ * string by it, and nothing anywhere has to guess at a canonical form.
+ */
+export declare const CHANNEL_NAME: RegExp;
+/**
+ * Names the registry will not carry, because the room already means
+ * something by them: `agents` is the backchannel, `transcript` is what was
+ * said, `minutes` is what the scribe wrote. Deriving them still works - they
+ * are ordinary channels to the crypto - but announcing one as a place to
+ * chat would put two different things under one name.
+ */
+export declare const RESERVED_CHANNELS: readonly string[];
+/** Canonical form of a channel list: validated, deduplicated, sorted. */
+export declare function canonicalChannels(channels: readonly string[]): string[];
+export interface SignChannelsOptions {
+    roomId: string;
+    epoch: number;
+    channels: readonly string[];
+    authoritySk: Uint8Array;
+}
+/**
+ * Sign the list of channels a room has.
+ *
+ * Signed by the authority and bound to the epoch for exactly the reasons the
+ * admin list is: every member holds the room key, so an unsigned list is the
+ * first thing a member would forge, and a list valid at one epoch must not
+ * be replayable into the next. This is what settles the rule that nothing a
+ * chat message says may change the structure of a room - a channel exists
+ * because the authority said so, or it does not exist.
+ */
+export declare function signChannels(opts: SignChannelsOptions): string;
+export interface VerifyChannelsOptions {
+    roomId: string;
+    epoch: number;
+    channels: readonly string[];
+    sig: string;
+    authority: string;
+}
+/** Never throws: this runs on anything a relay hands over. */
+export declare function verifyChannels(opts: VerifyChannelsOptions): boolean;
+/**
+ * Sign the list of participants who may act on the room, so a client can
+ * tell a keeper's announcement from anybody else's claim: the announcement
+ * rides the control channel, which every member can write to, and only the
+ * authority key pinned in the link can produce this.
+ */
+export declare function signAdmins(opts: SignAdminsOptions): string;
+export interface VerifyAdminsOptions {
+    roomId: string;
+    epoch: number;
+    admins: readonly string[];
+    sig: string;
+    authority: string;
+}
+export declare function verifyAdmins(opts: VerifyAdminsOptions): boolean;
+/** 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 EPOCH_LABELS: readonly ["kithmoot/v1/admins:", "kithmoot/v1/channels:", "kithmoot/v1/epoch-id", "kithmoot/v1/epoch-key", "kithmoot/v1/epoch-request-key", "kithmoot/v1/epoch-request:"];