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

package/dist/hex.js

@@ -0,0 +1,32 @@
+/**
+ * Case-insensitive equality for hex identifiers.
+ *
+ * Nostr pubkeys, room ids, and every other hex field this protocol compares
+ * are canonically produced in lower case, but nothing on the wire enforces
+ * that: an allow-list entry typed or pasted by a person, in particular, may
+ * carry upper-case hex naming exactly the same key. Every place this
+ * protocol decides whether two hex identifiers name the same thing must go
+ * through this function rather than `===`/`!==`, so a case difference is
+ * never mistaken for a different identity - see `vectors/README.md`.
+ */
+export function hexEquals(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Canonicalise a hex identifier to lower case.
+ *
+ * `hexEquals` makes an equality check safe regardless of case, but nothing
+ * protects a *lexicographic* comparison the same way: `Peer`'s glare
+ * tiebreak and `resolveSingularRoles`' device tiebreak both order hex
+ * strings with `<`, and two implementations that disagree on which of two
+ * differently-cased spellings of the same identifier sorts first can reach
+ * opposite answers from identical input - the exact deadlock perfect
+ * negotiation exists to prevent. Call this once, at the point a hex
+ * identifier enters the system - a decoded event, a parsed credential or
+ * proof, a pubkey read from storage or a URL - rather than at each
+ * comparison site, so every later equality or ordering check on it is
+ * correct by construction. See `vectors/README.md`.
+ */
+export function normaliseHex(hex) {
+    return hex.toLowerCase();
+}

package/dist/identity.d.ts

@@ -0,0 +1,49 @@
+import { type Event } from 'nostr-tools/pure';
+/**
+ * An event with everything filled in except the three fields a signature
+ * produces: `pubkey`, `id`, `sig`.
+ *
+ * Deliberately the same shape an external signer expects - NIP-07's
+ * `window.nostr.signEvent`, NIP-46's `sign_event`, and signet-login's
+ * `SignetSigner.signEvent` all take exactly this - so a signer built for
+ * any of those satisfies the interface below without an adapter.
+ */
+export interface UnsignedEvent {
+    kind: number;
+    created_at: number;
+    tags: string[][];
+    content: string;
+}
+/**
+ * The person, as far as this protocol is concerned.
+ *
+ * The participant key is used for exactly one thing: signing a device
+ * credential, one small event per room. Everything else in a room already
+ * runs on other keys - the device key signs the roster and the gift-wrapped
+ * signalling, the room key encrypts the roster and the chat. So this is the
+ * whole surface an identity has to cover.
+ *
+ * That narrowness is what makes an external signer practical, and the
+ * reason to prefer one: a participant who signs in with a browser extension
+ * or a remote bunker never has a participant secret in this app's storage
+ * at all. `localIdentity` is the other implementation - a key generated and
+ * held here, which is the zero-friction default and is exactly as valid.
+ *
+ * `signEvent` is async because a remote signer is a round trip: an
+ * extension prompt, a relay hop to a bunker, a tap on a phone. Every caller
+ * in this library awaits it rather than assuming an answer is available in
+ * the same tick.
+ */
+export interface ParticipantIdentity {
+    /** Lower-case hex. See `normaliseHex`. */
+    readonly pubkey: string;
+    signEvent(unsigned: UnsignedEvent): Promise<Event>;
+}
+/**
+ * An identity backed by a secret key held in this process.
+ *
+ * The key never leaves the closure, which is the same guarantee the app
+ * gave before this seam existed - it is simply now one implementation of an
+ * interface rather than the only way to be a participant.
+ */
+export declare function localIdentity(participantSk: Uint8Array): ParticipantIdentity;

package/dist/identity.js

@@ -0,0 +1,17 @@
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { normaliseHex } from './hex.js';
+/**
+ * An identity backed by a secret key held in this process.
+ *
+ * The key never leaves the closure, which is the same guarantee the app
+ * gave before this seam existed - it is simply now one implementation of an
+ * interface rather than the only way to be a participant.
+ */
+export function localIdentity(participantSk) {
+    return {
+        pubkey: normaliseHex(getPublicKey(participantSk)),
+        async signEvent(unsigned) {
+            return finalizeEvent(unsigned, participantSk);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { hexEquals, normaliseHex } from './hex.js';
+export { verifyEventUncached, boundedEventVerifier } from './verify.js';
+export type { UnsignedEvent, ParticipantIdentity } from './identity.js';
+export { localIdentity } from './identity.js';
+export { KINDS } from './kinds.js';
+export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof } from './types.js';
+export type { RelayTransport } from './transport.js';
+export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, } from './credential.js';
+export type { CreateCredentialOptions, VerifyResult } from './credential.js';
+export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
+export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
+export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
+export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
+export type { IssueKindredProofOptions } from './access.js';
+export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
+export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
+export type { PersistentRoomAdmission } from './persistent-invitation.js';
+export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
+export type { RoomLink } from './link.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';
+export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';
+export type { Lane } from './lane.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+// Public entry point. See README.md for an API overview and EXTRACTION.md
+// for where each export came from.
+export { hexEquals, normaliseHex } from './hex.js';
+export { verifyEventUncached, boundedEventVerifier } from './verify.js';
+export { localIdentity } from './identity.js';
+export { KINDS } from './kinds.js';
+export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, } from './credential.js';
+export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
+export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
+export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
+export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
+export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
+export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';
+export { LANES, LANE_MEANING, LANE_LABEL, LANE_GLYPH, isLane, laneOfRelayUrl, laneOfRelays, weakestLane, isDowngrade, } from './lane.js';

package/dist/invitation.d.ts

@@ -0,0 +1,217 @@
+import { type Event } from 'nostr-tools/pure';
+import type { RelayTransport } from './transport.js';
+/** A delegated responder cannot silently make its authority permanent. */
+export declare const INVITATION_DELEGATION_TTL_SECONDS: number;
+/** Bounds both verification work and the size of a grant from a hostile peer. */
+export declare const MAX_INVITATION_DELEGATION_DEPTH = 16;
+/**
+ * What a share link grants.
+ *
+ * `bearer` proves that somebody received the link. It is not a traffic key.
+ * `inviter` pins the root pubkey allowed to establish a room-bound responder
+ * chain, so another bearer can ask to enter but cannot nominate an authority
+ * or substitute a room of their own.
+ */
+export interface RoomInvitation {
+    bearer: Uint8Array;
+    inviter: string;
+    /** Version 3 group link: admission is stored encrypted on the relays. */
+    persistent?: true;
+}
+/** The private half retained by the browser that created an invitation. */
+export interface RoomInvitationHost {
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+}
+/**
+ * One hop in the authority chain rooted at the inviter pubkey in the link.
+ *
+ * Every field that gives the certificate meaning is signed. In particular,
+ * `invitation` binds it to one bearer-derived rendezvous and `room` to one
+ * traffic-secret derivation, so a member delegated for an old link cannot
+ * answer a replacement or substitute another room.
+ */
+export interface InvitationDelegation {
+    invitation: string;
+    room: string;
+    issuer: string;
+    delegate: string;
+    expiresAt: number;
+    sig: string;
+}
+/** The capability an admitted browser retains so it can answer the next
+ * joiner even after the creator has left. */
+export interface RoomInvitationDelegate {
+    delegateSk: Uint8Array;
+    chain: InvitationDelegation[];
+}
+/** The result of admission: room traffic capability plus bounded authority
+ * to keep this particular invitation available. */
+export interface RoomAdmission {
+    secret: Uint8Array;
+    delegate: RoomInvitationDelegate;
+    /**
+     * The epoch the responder says the room is at. A hint, not a key: the
+     * secret above opens epoch 0, and a room that has been rekeyed is read
+     * only with the current epoch's secret, which the room's authority hands
+     * to a member on proof of who it is (see `epoch.ts`). A joiner told the
+     * room is ahead asks before it announces; one told nothing waits a
+     * moment for the rekey events themselves. Absent from a responder that
+     * predates epochs.
+     */
+    epoch?: number;
+}
+/** Create a bearer plus a fresh, unlinkable inviter key for one share URL. */
+export declare function createRoomInvitation(persistent?: boolean): RoomInvitationHost;
+/** Validate and canonicalise an invitation crossing a URL/storage boundary. */
+export declare function roomInvitation(bearer: Uint8Array, inviter: string, persistent?: boolean): RoomInvitation;
+/** Public rendezvous id. Relays see this and timing, but cannot derive the bearer. */
+export declare function deriveInvitationId(invitation: RoomInvitation): string;
+export interface EncodeInvitationRequestOptions {
+    invitation: RoomInvitation;
+    requesterSk: Uint8Array;
+    now: number;
+    name?: string;
+    participant?: string;
+}
+/** Who is asking, as decoded from a request. */
+export interface InvitationRequest {
+    device: string;
+    request: string;
+    name?: string;
+    participant?: string;
+}
+/** Prove possession of the bearer without putting it, or a traffic key, on a relay. */
+export declare function encodeInvitationRequest(opts: EncodeInvitationRequestOptions): Event;
+export interface DecodeInvitationRequestOptions {
+    invitation: RoomInvitation;
+    now: number;
+    maxAgeSeconds?: number;
+}
+/** Returns null for all malformed, stale, wrongly addressed, or unauthorised asks. */
+export declare function decodeInvitationRequest(event: Event, opts: DecodeInvitationRequestOptions): InvitationRequest | null;
+/**
+ * Verify a whole chain and return the pubkey authorised by its final hop.
+ * An empty chain names the root inviter itself.
+ */
+export declare function verifyInvitationDelegation(invitation: RoomInvitation, chain: InvitationDelegation[], now: number): string | null;
+export interface EncodeInvitationGrantOptions {
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+    requester: string;
+    request: string;
+    roomSecret: Uint8Array;
+    now: number;
+    /** Empty for the creator; otherwise the root-to-signer chain received when
+     * this responder joined. */
+    delegation?: InvitationDelegation[];
+    delegationTtlSeconds?: number;
+    /** The epoch this responder is at, so the requester knows whether the
+     *  secret it is being handed opens the live room or only its history. */
+    epoch?: number;
+}
+/** 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 declare function encodeInvitationGrant(opts: EncodeInvitationGrantOptions): Event;
+export interface DecodeInvitationGrantOptions {
+    invitation: RoomInvitation;
+    requesterSk: Uint8Array;
+    request: string;
+    now: number;
+    maxAgeSeconds?: number;
+}
+/**
+ * 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 declare function decodeRoomAdmissionGrant(event: Event, opts: DecodeInvitationGrantOptions): RoomAdmission | 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 declare function decodeInvitationGrant(event: Event, opts: DecodeInvitationGrantOptions): Uint8Array | null;
+export interface HostRoomInvitationOptions {
+    transport: RelayTransport;
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+    roomSecret: Uint8Array;
+    /** Root-to-this-responder chain. Empty/absent only on the creator. */
+    delegation?: InvitationDelegation[];
+    now?: () => number;
+    onAdmitted?: (device: string) => void;
+    /** Called when the creator's durable retirement tombstone is heard. */
+    onRetired?: () => void;
+    /** The epoch this responder is at, asked on every grant because it
+     *  moves. Omit to say nothing, which a joiner treats as unknown. */
+    epoch?: () => number;
+    /**
+     * Asked before every grant, when present. Return true to let the
+     * request in, false to leave it unanswered: there is no refusal on the
+     * wire, so a declined person sees the room not answer, which is the same
+     * as nobody being home. A request is asked about once, whatever its
+     * retries; a person who tries again with a fresh request is asked about
+     * again. Absent, every request is granted, which is what a temporary
+     * room's link has always meant.
+     */
+    admit?: (request: InvitationRequest) => boolean | Promise<boolean>;
+}
+export interface EncodeInvitationRetirementOptions {
+    invitation: RoomInvitation;
+    /** Only the root inviter may retire a link. Delegates never receive this
+     * key, which stops one room member disabling admission for everybody. */
+    inviterSk: Uint8Array;
+    now: number;
+    /** The room itself was ended, not just this link replaced. Additive: a
+     * reader that predates it still sees an ordinary retirement. */
+    ended?: boolean;
+}
+/** What a joiner is told when a link was retired because its room ended. */
+export declare const ROOM_ENDED_MESSAGE = "this room was ended by the person who started it";
+/** Make a permanent tombstone for one invitation rendezvous. */
+export declare function encodeInvitationRetirement(opts: EncodeInvitationRetirementOptions): Event;
+/** A valid tombstone never expires: invitation ids are random and unique,
+ * and a retired bearer must not become usable again after a timeout. */
+export declare function decodeInvitationRetirement(event: Event, invitation: RoomInvitation): boolean;
+/** A valid retirement, and whether it says the room was ended. Undefined
+ * for anything that is not a valid retirement of this invitation. */
+export declare function decodeInvitationRetirementNotice(event: Event, invitation: RoomInvitation): {
+    ended: boolean;
+} | undefined;
+/** The error a joiner rejects with on a retirement. */
+export declare function retirementError(notice: {
+    ended: boolean;
+}): Error;
+/**
+ * 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 declare function hostRoomInvitation(opts: HostRoomInvitationOptions): {
+    close(): void;
+};
+export interface RequestRoomAdmissionOptions {
+    transport: RelayTransport;
+    invitation: RoomInvitation;
+    requesterSk?: Uint8Array;
+    now?: () => number;
+    timeoutMs?: number;
+    retryMs?: number;
+    /** Carried in the request for a host who asks before letting people in. */
+    name?: string;
+    participant?: string;
+}
+/** 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 declare function requestRoomAdmissionCapability(opts: RequestRoomAdmissionOptions): Promise<RoomAdmission>;
+/** Compatibility wrapper for non-interactive consumers. It joins correctly,
+ * but discards the ability to keep the link available for somebody else. */
+export declare function requestRoomAdmission(opts: RequestRoomAdmissionOptions): Promise<Uint8Array>;
+/** 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 INVITATION_LABELS: readonly ["kithmoot/v2/invitation-delegation:", "kithmoot/v2/invitation-id", "kithmoot/v2/invitation-request-key"];