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

package/dist/transport.d.ts

@@ -0,0 +1,24 @@
+import type { Event } from 'nostr-tools/pure';
+import type { Filter } from 'nostr-tools/filter';
+/**
+ * The relay transport seam the kit's codecs need: publish, subscribe, close.
+ *
+ * This is the kit's own declaration, not an import of KithMoot's
+ * `RelayTransport` (KithMoot's `src/relay-pool.ts`). The relay pool itself
+ * has not moved to the kit yet (see EXTRACTION.md): epoch, invitation and
+ * persistent-invitation only ever call `publish`/`subscribe`/`close` on the
+ * transport they are given, so the kit needs only that much of the shape,
+ * not KithMoot's richer `describe()`/`rekey()` extensions.
+ *
+ * A caller can pass KithMoot's `NostrRelayPool` (which implements a superset
+ * of this interface) straight through, or the kit's own `SimTransport`
+ * (`test/sim-relay.ts`), or any other implementation with the same three
+ * methods.
+ */
+export interface RelayTransport {
+    publish(event: Event): Promise<void>;
+    /** `via` is the relay URL that delivered the event, when the transport
+     *  knows it. */
+    subscribe(filters: Filter[], onEvent: (event: Event, via?: string) => void, onEose?: () => void): () => void;
+    close(): void;
+}

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+import type { Event } from 'nostr-tools/pure';
+/** Circle-layer wire types: a subset of KithMoot's `src/types.ts`, copied
+ * byte-identical per declaration from the pinned source commit (see
+ * EXTRACTION.md). KithMoot's `types.ts` also defines roster, media and
+ * descriptor types that stay in KithMoot; those import `Reachability`
+ * (KithMoot's `src/reachability.ts`), which does not move here (see
+ * EXTRACTION.md's "What did not move" section). None of the types below
+ * need it. */
+/** A device credential is an ordinary signed Nostr event, never published bare. */
+export type DeviceCredential = Event;
+/** Kindred tiers, closest first: family, mutual verified bond, one-way
+ *  recognition, no requirement at all. */
+export type AccessTier = 'open' | 'ken' | 'kith' | 'kin';
+/** What a room requires of its agents. `owned-by-members`: an agent is
+ *  admitted to the roster only with a verified ownership proof from a
+ *  participant who is in the room. See `AgentOwnership`. */
+export type AgentRule = 'owned-by-members';
+/** A room's admission rule. `admitted` lists the issuer pubkeys the room
+ *  trusts to vouch for guests; irrelevant when `tier` is `open`. `agents`
+ *  is a separate rule about what an agent has to show; absent means
+ *  nothing, which is how every room worked before it existed. */
+export interface RoomPolicy {
+    tier: AccessTier;
+    admitted?: string[];
+    agents?: AgentRule;
+    /** When present, the only participants admitted, whatever the tier
+     *  says. A direct message is a room whose policy lists two. See
+     *  `docs/messages.md`. */
+    members?: string[];
+    /** A quiet room: its chat rides the kind 1059 firehose as dead drops to
+     *  keys derived from the epoch key, on a cadence, so a relay cannot tell
+     *  whether anything was said, by whom, or when. Only with `members`,
+     *  because everybody derives every member's keys. Rides here so that
+     *  everyone who joins agrees on how the room talks, exactly as they
+     *  agree on who may enter. See `quiet.ts`. */
+    quiet?: true;
+}
+/**
+ * A signed claim that `issuer` recognises `participant` at `tier` in `room`,
+ * until `expiresAt`. Never issued for `open`, since open needs no proof.
+ *
+ * `room` is what stops a proof being a bearer token: without it, one proof
+ * admits its holder to every room that happens to trust the same issuer, and
+ * an issuer who vouched for a guest at one moot has not vouched for them at
+ * all of them. The cost of that binding is stated plainly: a kindred proof is
+ * a room grant here, not a portable statement about a relationship, so an
+ * issuer mints one per room. In this protocol the party who vouches is the
+ * party who sent the join link, so it already knows the room id.
+ */
+export type KindredProof = {
+    tier: Exclude<AccessTier, 'open'>;
+    participant: string;
+    issuer: string;
+    /** The room id this proof is valid in. */
+    room: string;
+    /** 32 random bytes, hex, unique to this proof. Signed over, so two proofs
+     *  on identical terms are still distinguishable - which is what a revocation
+     *  list, or an audit, needs to name one of them. */
+    nonce: string;
+    sig: string;
+    expiresAt: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,26 @@
+import { type Event } from 'nostr-tools/pure';
+/**
+ * Verify an event's signature, ignoring any cached verdict it arrives with.
+ *
+ * `verifyEvent` caches its result on the event object under `verifiedSymbol`
+ * and returns that cached value on any later call, without re-checking
+ * anything. The property is an own enumerable symbol, so it survives a
+ * shallow copy (`{ ...event }`, which is exactly how a caller might rebuild
+ * an event after editing a field) - and an attacker who hands us an object
+ * rather than a JSON string can simply set it themselves. Either way the
+ * signature check silently becomes a no-op.
+ *
+ * Every inbound event in this library goes through here rather than calling
+ * `verifyEvent` directly, so the defence cannot be forgotten by the next
+ * decoder somebody writes. The copy also keeps the caller's object
+ * unmodified: we never stamp a verdict onto something we did not sign.
+ */
+export declare function verifyEventUncached(event: Event): boolean;
+/**
+ * Keep relay fan-out from verifying the same signed event once per relay and
+ * replay. The cached value includes every signed field, so an object that
+ * reuses a known id while changing its body or signature is rejected. The
+ * fixed-size FIFO also prevents an untrusted relay from
+ * growing keeper memory without bound.
+ */
+export declare function boundedEventVerifier(limit?: number, verify?: (event: Event) => boolean): (event: Event) => boolean;

package/dist/verify.js

@@ -0,0 +1,46 @@
+import { verifyEvent, verifiedSymbol } from 'nostr-tools/pure';
+/**
+ * Verify an event's signature, ignoring any cached verdict it arrives with.
+ *
+ * `verifyEvent` caches its result on the event object under `verifiedSymbol`
+ * and returns that cached value on any later call, without re-checking
+ * anything. The property is an own enumerable symbol, so it survives a
+ * shallow copy (`{ ...event }`, which is exactly how a caller might rebuild
+ * an event after editing a field) - and an attacker who hands us an object
+ * rather than a JSON string can simply set it themselves. Either way the
+ * signature check silently becomes a no-op.
+ *
+ * Every inbound event in this library goes through here rather than calling
+ * `verifyEvent` directly, so the defence cannot be forgotten by the next
+ * decoder somebody writes. The copy also keeps the caller's object
+ * unmodified: we never stamp a verdict onto something we did not sign.
+ */
+export function verifyEventUncached(event) {
+    const unverified = { ...event };
+    delete unverified[verifiedSymbol];
+    return verifyEvent(unverified);
+}
+/**
+ * Keep relay fan-out from verifying the same signed event once per relay and
+ * replay. The cached value includes every signed field, so an object that
+ * reuses a known id while changing its body or signature is rejected. The
+ * fixed-size FIFO also prevents an untrusted relay from
+ * growing keeper memory without bound.
+ */
+export function boundedEventVerifier(limit = 8_192, verify = verifyEventUncached) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error('Event verification cache size must be a positive integer');
+    const verified = new Map();
+    return event => {
+        const cached = verified.get(event.id);
+        if (cached !== undefined) {
+            return cached === JSON.stringify([event.id, event.pubkey, event.created_at, event.kind, event.tags, event.content, event.sig]);
+        }
+        if (!verify(event))
+            return false;
+        verified.set(event.id, JSON.stringify([event.id, event.pubkey, event.created_at, event.kind, event.tags, event.content, event.sig]));
+        if (verified.size > limit)
+            verified.delete(verified.keys().next().value);
+        return true;
+    };
+}

package/llms.txt

@@ -0,0 +1,100 @@
+# @forgesworn/fold-kit
+
+> Circle primitives for private Nostr groups nobody operates: a room key per epoch, sealed to each device that stays; link invitations as capabilities; member removal by rekey; device credentials so a person approves a device once and it signs from then on. Extracted from KithMoot, byte-identical on the wire. Framework-free: owns no storage, UI, relay defaults or identity keys, and does no relay I/O of its own.
+
+ESM-only, Node.js 22.13+. Two entry points: `@forgesworn/fold-kit` (everything) and `@forgesworn/fold-kit/lane` (relay lane classification only).
+
+## Install
+
+```bash
+npm install @forgesworn/fold-kit
+```
+
+Not yet published to npm under this API. Until it is, pin an immutable Git commit:
+
+```json
+{
+  "dependencies": {
+    "@forgesworn/fold-kit": "github:forgesworn/fold-kit#<commit>"
+  }
+}
+```
+
+### Peer dependencies
+
+`nostr-tools` (`>=2.24.2 <3`), `@noble/hashes` (`^1.8.0`), `@noble/curves` (`^2.0.1`) - peers, not dependencies, so a consumer keeps a single copy of each. `@noble/hashes` is 1.x only: this kit's imports have no `.js` suffix and its `hkdf` calls pass a string `info`, both of which 2.x rejects.
+
+## Exports
+
+### Identity, verification, hex
+
+- `hexEquals(a, b)` → `boolean` - constant-shape hex comparison
+- `normaliseHex(hex)` → `string` - lower-cases and validates hex
+- `verifyEventUncached(event)` → `boolean`
+- `boundedEventVerifier(limit?, verify?)` → `(event) => boolean` - an LRU-bounded verifier
+- `localIdentity(participantSk)` → `ParticipantIdentity` - a local signer, plus the `ParticipantIdentity`/`UnsignedEvent` seam every codec below takes as a dependency
+
+### Wire kinds and types
+
+- `KINDS` → `{ CREDENTIAL: 20460, CHAT: 1460, INVITATION_REQUEST: 20466, INVITATION_GRANT: 20467, INVITATION_RETIREMENT: 1461, GROUP_INVITATION: 1463, ROOM_REKEY: 1462, EPOCH_REQUEST: 20468, EPOCH_GRANT: 20469 }`
+- `DeviceCredential`, `AccessTier` (`'open' | 'ken' | 'kith' | 'kin'`), `AgentRule`, `RoomPolicy`, `KindredProof` - link-layer wire types
+- `RelayTransport` → `{ publish(event), subscribe(filters, onEvent, onEose?), close() }` - the transport seam every relay-facing codec takes; this kit declares its own interface rather than importing a relay pool implementation
+
+### Rooms, credentials, access
+
+- `generateRoomSecret()` → `Uint8Array` (32 bytes)
+- `deriveRoom(secret)` → `{ roomId, roomKey }`
+- `encodeJoinUrl(base, secret, relays, policy?)` / `decodeJoinUrl(url)` - legacy v1 join URL
+- `parseRoomPolicy(raw)` → `RoomPolicy | undefined`
+- `createDeviceCredential(opts)` → `Promise<DeviceCredential>` - room-scope or person-scope (`scope: 'person'`)
+- `verifyDeviceCredential(event, opts)` → `VerifyResult` - pass `acceptPerson: true` to accept a person-scope credential where a room credential is expected
+- `PERSON_CREDENTIAL_MAX_SECONDS` - 30-day cap on a person-scope credential
+- `issueKindredProof(opts)` → `KindredProof`
+- `evaluateAccess(policy, participant, proof, now, roomId)` → `{ admitted, reason }`
+- `sanitiseDisplayName(raw)` → `string | undefined`, `MAX_DISPLAY_NAME_LENGTH`
+- `safeRelayUrls(raw)`, `safeIceUrls(raw)`, `assertNetworkHintBounds(relays, ice)`, `MAX_RELAY_HINTS`, `MAX_ICE_HINTS`, `MAX_NETWORK_HINT_LENGTH`
+
+### Links and invitations
+
+- `parseRoomLink(url)` / `encodeRoomLink(base, link)` → `RoomLink` - the v1/v2/v3 link envelope
+- `createRoomInvitation(persistent?)`, `roomInvitation(bearer, inviter, persistent?)`, `deriveInvitationId(invitation)`
+- `encodeInvitationRequest(opts)` / `decodeInvitationRequest(event, opts)` - v2 live rendezvous request
+- `encodeInvitationGrant(opts)` / `decodeRoomAdmissionGrant(event, opts)` - v2 grant, with a delegation chain
+- `verifyInvitationDelegation(invitation, chain, now)`
+- `encodeInvitationRetirement(opts)` / `decodeInvitationRetirementNotice(event, invitation)` - durable tombstone (kind 1461)
+- `hostRoomInvitation(opts)` / `requestRoomAdmission(opts)` - the live desk, both sides
+- `encodePersistentInvitation(opts)` / `decodePersistentInvitation(event, invitation)` - v3 stored group invitation (kind 1463)
+- `requestPersistentRoomAdmission(opts)` - joins from stored admission alone, no live desk needed
+
+### Epochs (removal by rekey)
+
+- `deriveEpoch({ epoch, secret })` → `{ epoch, id, key }`, `generateEpochSecret()`
+- `encodeRekeyEvent(opts)` / `peekRekeyEvent(event, opts)` / `decodeRekeyEvent(event, opts)` - the durable rekey notice (kind 1462), sealed per remaining device, naming who was removed
+- `encodeEpochRequest(opts)` / `decodeEpochRequest(event, opts)` - a device asking the authority for the current epoch
+- `encodeEpochGrant(opts)` / `decodeEpochGrant(event, opts)` - the authority's answer (secret, epoch-0, or a refusal `'removed' | 'closed'`)
+- `epochRequestAdmission(opts)`, `deriveEpochRequestKey(roomKey)`
+- `hostRoomEpoch(opts)` / `requestRoomEpoch(opts)` / `EpochRefusedError` - the live request/grant desk, both sides
+- `canonicalAdmins(admins)` / `signAdmins(opts)` / `verifyAdmins(opts)` - the authority's signed admin list
+- `canonicalChannels(channels)` / `signChannels(opts)` / `verifyChannels(opts)` - the authority's signed channel list; `CHANNEL_NAME`, `RESERVED_CHANNELS`
+
+### Channel derivation
+
+- `deriveChannel(roomId, roomKey, channel?)` → `{ id, key }` - a named channel's id/key, derived from the room key; `CHANNEL_ID_INFO`, `CHANNEL_KEY_INFO`, `MAX_CHANNEL_NAME_LENGTH`. The chat log and event codecs themselves stay in the consuming app.
+
+### Lane (`@forgesworn/fold-kit/lane`)
+
+- `laneOfRelayUrl(url, circle?)` / `laneOfRelays(urls, circle?)` → `Lane | undefined` (`'public' | 'sheltered' | 'direct'`)
+- `isLane(value)`, `weakestLane(lanes)`, `isDowngrade(requested, actual)`
+- `LANES`, `LANE_MEANING`, `LANE_LABEL`, `LANE_GLYPH`
+
+## Design notes
+
+- Every `kithmoot/v*` derivation label and message prefix is byte-identical to the source KithMoot commit this kit was extracted from (see EXTRACTION.md). These are protocol names now, not branding.
+- No baked-in relay defaults, no storage, no DOM access. A caller supplies a `RelayTransport` implementation (a relay pool, or a test double).
+- A room's authority - the party that may rekey and remove members - is the root inviter key pinned in the room's link, not a separate role system.
+
+## Docs
+
+- README.md - full API overview, peer dependency rationale, how this kit relates to `covey-kit` and `roost-kit`
+- EXTRACTION.md - the source commit, exactly which modules and functions moved, and the two splits (`access.ts`, `chat.ts`) performed on the way
+- AGENTS.md - build/test commands and repository conventions for an agent working in this repo

package/package.json

@@ -1,19 +1,89 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.0.0-seed.0",
+  "version": "0.1.0",
   "description": "Circle primitives for private Nostr groups nobody operates: epoch keys, link invites, removal by rekey, device credentials.",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./lane": {
+      "types": "./dist/lane.d.ts",
+      "default": "./dist/lane.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
+    "dist",
+    "vectors/kithmoot-vectors.json",
+    "vectors/circle-vectors.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/forgesworn/fold-kit.git"
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "diff-source": "node scripts/diff-source.mjs",
+    "bundle-check": "node scripts/bundle-check.mjs",
+    "tarball-smoke": "node scripts/tarball-smoke.mjs",
+    "vectors": "vitest run vectors/",
+    "check": "npm run typecheck && npm test && npm run diff-source",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check && npm run bundle-check && npm run tarball-smoke"
   },
+  "keywords": [
+    "nostr",
+    "e2ee",
+    "circle",
+    "group-chat",
+    "epoch-key",
+    "invite-link",
+    "device-credential"
+  ],
   "author": "forgesworn",
   "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13"
+  },
+  "peerDependencies": {
+    "nostr-tools": ">=2.24.2 <3",
+    "@noble/hashes": "^1.8.0",
+    "@noble/curves": "^2.0.1"
+  },
+  "dependencies": {
+    "@scure/base": "^2.0.0"
+  },
+  "devDependencies": {
+    "@noble/curves": "2.0.1",
+    "@noble/hashes": "^1.8.0",
+    "@types/node": "^22",
+    "esbuild": "^0.25.0",
+    "nostr-tools": "2.25.0",
+    "signet-login": "0.17.1",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.11"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "funding": {
+    "type": "lightning",
+    "url": "lightning:profusemeat89@walletofsatoshi.com"
+  },
+  "homepage": "https://github.com/forgesworn/fold-kit#readme",
+  "bugs": {
+    "url": "https://github.com/forgesworn/fold-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgesworn/fold-kit.git"
   }
 }