@statewalker/httpeers-hub 0.1.3

package/src/hub-state.ts

@@ -0,0 +1,199 @@
+/**
+ * The hub's durable state — members and spent invitation ids — over an
+ * INJECTED `SnapshotStore`, with no idea where that store puts anything.
+ *
+ * WHY THIS IS ITS OWN FILE, SEPARATE FROM `./persist.ts`. The
+ * `SnapshotStore` seam exists so the same hub logic can run in a browser
+ * page (`../pages/hub/`, Task 24) as well as in the Node process, and a
+ * seam is only as portable as the module that declares it: `persist.ts`
+ * imports `node:fs`/`node:path` at module scope for its own file store, so
+ * a browser bundle that reached `createPersistentHub` dragged both in with
+ * it. Vite does not fail that build — it substitutes a stub that throws on
+ * first property access — so the failure would have surfaced at runtime, in
+ * a tab, as an error naming `node:fs` and nothing about the hub. Everything
+ * in THIS file is storage-agnostic and free of `node:` imports; `persist.ts`
+ * keeps the Node file store and re-exports all of this unchanged, so no
+ * existing caller (or test) sees a different API.
+ *
+ * PRESENCE IS DELIBERATELY NOT HERE. It is TTL'd and regenerates within one
+ * heartbeat interval of a restart — persisting it would only let a stale
+ * "who was online" view survive past the moment it stopped being true.
+ *
+ * INVITATIONS THEMSELVES ARE ALSO NOT HERE — only which ids have already
+ * been *spent*. An unredeemed invitation forgotten across a restart is a
+ * minor inconvenience (issue a new one); a redeemed one becoming redeemable
+ * again is a membership bypass. Persisting exactly the set that guards
+ * against the second, and nothing else, is the smallest state that closes
+ * the hole. See `createInvitationStore` below: the spent-id check runs
+ * *before* the invitation is even looked up, so a code whose invitation
+ * record did not survive a restart still cannot be redeemed twice.
+ */
+
+import type { RuleSet } from "@statewalker/httpeers-access";
+import { assertValid, validateRoles } from "@statewalker/httpeers-access";
+import type { MemberRecord, MemberStore } from "@statewalker/httpeers-core";
+
+export interface HubSnapshot {
+  members: MemberRecord[];
+  spentInvitationIds: string[];
+  /**
+   * Invitations created and not yet redeemed.
+   *
+   * ABSENT FROM THE PROTOTYPE, and that was a defect rather than a decision:
+   * pending invitations lived in memory only, so a hub restart silently
+   * invalidated every invitation an operator had already handed out — and the
+   * person holding one got `not-found`, which reads like a typo rather than
+   * like "the hub restarted".
+   *
+   * Optional so a snapshot written by the older shape still loads: a hub
+   * upgrading in place finds `undefined` here and starts with no pending
+   * invitations, which is exactly the state it was already in.
+   */
+  pendingInvitations?: InvitationRecord[];
+}
+
+/** What a store with nothing in it yet must read as — see `SnapshotStore.read`. */
+export const EMPTY_SNAPSHOT: HubSnapshot = {
+  members: [],
+  spentInvitationIds: [],
+  pendingInvitations: [],
+};
+
+/**
+ * Where a hub's snapshot lives. THE ONE SEAM BETWEEN THE HUB'S STATE AND
+ * ANY PARTICULAR STORAGE -- `./persist.ts`'s `createFileSnapshotStore` is
+ * the Node one (a JSON file), `../browser/snapshot-store.ts`'s is the
+ * browser one (IndexedDB); nothing else in this file knows either exists.
+ *
+ * `read` returns `EMPTY_SNAPSHOT`-shaped state on a first run rather than
+ * throwing: "nothing stored yet" is the normal first case, not a fault.
+ *
+ * `write` is synchronous on purpose: every mutation below calls it and then
+ * returns, so an async store would open a window where the caller has been
+ * told a member was added while the snapshot still says otherwise. A browser
+ * implementation that can only write asynchronously must therefore keep an
+ * in-memory copy authoritative and flush behind it, rather than making these
+ * methods async. See `../browser/snapshot-store.ts` for the one that does.
+ */
+export interface SnapshotStore {
+  read(): HubSnapshot;
+  write(snapshot: HubSnapshot): void;
+}
+
+export interface PersistentHub {
+  memberStore: MemberStore;
+  invitations: InvitationStore;
+}
+
+export interface InvitationRecord {
+  id: string;
+  roles: string[];
+  expiresAt: number;
+}
+
+export type InvitationRedemption =
+  | { ok: true; roles: string[] }
+  | { ok: false; reason: "not-found" | "expired" | "already-redeemed" };
+
+export interface InvitationStore {
+  /** Throws (via `assertValid`) if any role is one no rule of `rules` knows — caught where the invitation is made, not three hops later. */
+  create(id: string, roles: string[], ttlMs: number): InvitationRecord;
+  redeem(id: string): InvitationRedemption;
+  /** What became of this id. `unknown` means no invitation was ever created with it. */
+  status(id: string): "unspent" | "redeemed" | "expired" | "unknown";
+  /** Every invitation still awaiting redemption, for an operator's listing. */
+  pending(): InvitationRecord[];
+}
+
+export interface CreateHubStateInit {
+  /** Where the snapshot is loaded from at construction and written back to after every mutation. */
+  store: SnapshotStore;
+  /** This mesh's rules — the role registry `validateRoles` reads (ADR-0019). */
+  rules: RuleSet;
+  now?: () => number;
+  createMemberStore: (rules: RuleSet, clock?: () => number) => MemberStore;
+}
+
+/**
+ * Wrap a `MemberStore` so every mutation is followed by a synchronous
+ * snapshot write — members and spent invitation ids share ONE snapshot, so
+ * one write keeps both consistent with each other by construction (no
+ * window where one persisted and the other did not). Presence is
+ * intentionally not part of this — see the module comment.
+ */
+export function createHubState(init: CreateHubStateInit): PersistentHub {
+  const now = init.now ?? Date.now;
+  const snapshot = init.store.read();
+
+  const innerMembers = init.createMemberStore(init.rules, now);
+  for (const m of snapshot.members) innerMembers.add(m.peerId, m.roles);
+  const spentIds = new Set(snapshot.spentInvitationIds);
+
+  const save = (): void => {
+    init.store.write({
+      members: innerMembers.list(),
+      spentInvitationIds: [...spentIds],
+      pendingInvitations: [...pending.values()],
+    });
+  };
+
+  const memberStore: MemberStore = {
+    add(peerId, roles) {
+      const record = innerMembers.add(peerId, roles);
+      save();
+      return record;
+    },
+    setRoles(peerId, roles) {
+      const record = innerMembers.setRoles(peerId, roles);
+      save();
+      return record;
+    },
+    remove(peerId) {
+      innerMembers.remove(peerId);
+      save();
+    },
+    get: innerMembers.get,
+    list: innerMembers.list,
+  };
+
+  // Restored from the snapshot, not merely held in memory — see
+  // `HubSnapshot.pendingInvitations` for what that fixes.
+  const pending = new Map<string, InvitationRecord>(
+    (snapshot.pendingInvitations ?? []).map((record) => [record.id, record]),
+  );
+
+  const invitations: InvitationStore = {
+    create(id, roles, ttlMs) {
+      assertValid(validateRoles(init.rules, roles, `invitation '${id}'`));
+      const record: InvitationRecord = { id, roles: [...roles], expiresAt: now() + ttlMs };
+      pending.set(id, record);
+      save();
+      return record;
+    },
+    redeem(id) {
+      // The spent check runs FIRST, and unconditionally — before the
+      // invitation record is even looked up. That is what makes double
+      // redemption impossible across a restart, and it stays first now that
+      // pending records persist too: the two facts are written together, but
+      // "already spent" must win over "here is the record" whatever order they
+      // were loaded in.
+      if (spentIds.has(id)) return { ok: false, reason: "already-redeemed" };
+      const record = pending.get(id);
+      if (record == null) return { ok: false, reason: "not-found" };
+      if (record.expiresAt <= now()) return { ok: false, reason: "expired" };
+      pending.delete(id);
+      spentIds.add(id);
+      save();
+      return { ok: true, roles: record.roles };
+    },
+    status(id) {
+      if (spentIds.has(id)) return "redeemed";
+      const record = pending.get(id);
+      if (record == null) return "unknown";
+      return record.expiresAt <= now() ? "expired" : "unspent";
+    },
+    pending: () => [...pending.values()],
+  };
+
+  return { memberStore, invitations };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Minting membership, holding the registries, and saying who is in the mesh.
+ */
+
+export { type CreateHubInit, createHub, type Hub } from "./create-hub.js";
+export {
+  ADMIN_CAPABILITY,
+  createHubEndpoints,
+  DEFAULT_PRESENCE_TTL_MS,
+  type HubEndpoints,
+  type HubEndpointsInit,
+  usesTransportIdentity,
+} from "./endpoints.js";
+export {
+  type CreateHubStateInit,
+  createHubState,
+  EMPTY_SNAPSHOT,
+  type HubSnapshot,
+  type InvitationRecord,
+  type InvitationRedemption,
+  type InvitationStore,
+  type PersistentHub,
+  type SnapshotStore,
+} from "./hub-state.js";
+export { type AdvertisementPayload, buildMeshView } from "./mesh-view.js";
+export { createAdvertisementStore, createMemberStore, createPresenceStore } from "./registries.js";
+export {
+  type AsyncSnapshotStore,
+  asyncSnapshotStore,
+  filesStorage,
+  type KeyValueStorage,
+  memoryStorage,
+} from "./storage.js";

package/src/mesh-view.ts

@@ -0,0 +1,83 @@
+/**
+ * The mesh view: a PROJECTION over the three registries (members, presence,
+ * advertisements), not a fourth registry of its own. Nothing here is stored
+ * — it is recomputed from the hub's live state on every read, filtered by
+ * whoever is asking.
+ *
+ * THE HUB IS A BULLETIN BOARD, NEVER AN AUTHORITY. An advertisement says
+ * "worth asking"; the provider it names still decides for itself whether to
+ * answer. Nothing downstream may treat inclusion in this view as a grant —
+ * that is what the membership token and each provider's own policy
+ * are for.
+ *
+ * Two things vary by caller, both because different callers legitimately
+ * see different views:
+ *  - a member with role `hidden` is omitted from the view of anyone who does
+ *    not themselves hold `std:mesh.admin` — this is the one consumer of the
+ *    `hidden` role `DEFAULT_RULES` already knows;
+ *  - an advertisement is omitted unless the caller holds the capability that
+ *    gates its `kind` (`advertisementAccess`, hub-owned config — analogous
+ *    to an allow policy, but for the bulletin board rather than a path).
+ */
+import type {
+  Advertisement,
+  MemberRecord,
+  MeshView,
+  MeshViewAdvertisement,
+  MeshViewMember,
+  PresenceRecord,
+} from "@statewalker/httpeers-core";
+
+// `MeshView` and its members moved to `httpeers-core`. The hub PRODUCES one
+// and `httpeers-member` RETURNS one, and member must not depend on hub — so a
+// type both consume belongs in the package both already import. Re-exported
+// here so this file's own readers still find it where they expect.
+export type { MeshView, MeshViewAdvertisement, MeshViewMember };
+
+/** The payload shape this hub posts advertisements with — see `hub/endpoints.ts`'s presence handler. */
+export interface AdvertisementPayload {
+  kind: string;
+  title: string;
+}
+
+export interface BuildMeshViewInit {
+  version: number;
+  self: string;
+  members: MemberRecord[];
+  presence: PresenceRecord[];
+  addrsByPeer: ReadonlyMap<string, string[]>;
+  advertisements: Advertisement[];
+  /** Capabilities the caller holds (already derived from their roles by the node's rules). */
+  callerCapabilities: ReadonlySet<string>;
+  /** `kind` -> capability required to see advertisements of that kind. A kind absent here is visible to any authenticated caller. */
+  advertisementAccess: Readonly<Record<string, string>>;
+  /** The capability that grants admin visibility (sees `hidden` members). */
+  adminCapability: string;
+}
+
+export function buildMeshView(init: BuildMeshViewInit): MeshView {
+  const isAdmin = init.callerCapabilities.has(init.adminCapability);
+  const present = new Set(init.presence.map((p) => p.peerId));
+
+  const members: MeshViewMember[] = init.members
+    .filter((m) => isAdmin || !m.roles.includes("hidden"))
+    .map((m) => ({
+      peerId: m.peerId,
+      roles: m.roles,
+      online: present.has(m.peerId),
+      addrs: init.addrsByPeer.get(m.peerId) ?? [],
+    }));
+
+  const advertisements: MeshViewAdvertisement[] = init.advertisements
+    .filter((ad) => {
+      const kind = (ad.payload as AdvertisementPayload).kind;
+      const required = init.advertisementAccess[kind];
+      return required == null || init.callerCapabilities.has(required);
+    })
+    .map((ad) => {
+      const payload = ad.payload as AdvertisementPayload;
+      return { peerId: ad.peerId, id: ad.key, kind: payload.kind, title: payload.title };
+    });
+
+  return { version: init.version, self: init.self, members, advertisements };
+}

package/src/node.ts

@@ -0,0 +1,40 @@
+/**
+ * The Node profile: hub state on disk.
+ *
+ * Write-then-rename, for the reason rung 04 measured: the prototype's file
+ * snapshot store wrote IN PLACE, so a crash mid-write left a truncated JSON
+ * document — and a hub that cannot parse its snapshot starts EMPTY. Every
+ * member forgotten, every spent invitation id forgotten and therefore
+ * replayable, and nothing reporting an error.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { KeyValueStorage } from "./storage.js";
+
+export function fileStorage(path: string): KeyValueStorage {
+  const pathFor = (key: string) => `${path}.${key.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+  return {
+    async get(key) {
+      try {
+        return await readFile(pathFor(key), "utf8");
+      } catch (error) {
+        if ((error as { code?: string }).code === "ENOENT") return undefined;
+        throw error;
+      }
+    },
+    async set(key, value) {
+      const target = pathFor(key);
+      await mkdir(dirname(target), { recursive: true });
+      // Same directory, so the rename cannot cross a filesystem boundary —
+      // the one case where it would stop being atomic.
+      const staging = `${target}.${process.pid}.${Date.now()}.tmp`;
+      await writeFile(staging, value, { mode: 0o600 });
+      await rename(staging, target);
+    },
+    async delete(key) {
+      const { rm } = await import("node:fs/promises");
+      await rm(pathFor(key), { force: true });
+    },
+  };
+}

package/src/registries.ts

@@ -0,0 +1,150 @@
+/**
+ * The hub's three registries: members, presence, advertisements.
+ *
+ * All three are plain in-memory data structures with an injected clock
+ * (`() => number`) so TTL and sequencing behaviour is deterministic under
+ * test, with no real timers involved. Persistence is a later task's job —
+ * nothing here touches the filesystem or a database.
+ */
+
+import type { RuleSet } from "@statewalker/httpeers-access";
+import { assertValid, validateRoles } from "@statewalker/httpeers-access";
+import type {
+  Advertisement,
+  AdvertisementStore,
+  MemberRecord,
+  MemberStore,
+  PresenceRecord,
+  PresenceStore,
+  PresenceWriteResult,
+} from "@statewalker/httpeers-core";
+
+/**
+ * Durable membership: who belongs to the mesh, and with what roles.
+ *
+ * `setRoles` validates its `roles` against `rules` before writing — "catch a
+ * typo where it is made, not three hops later as a silent denial" (the v0.9.0
+ * delta's own rationale). Since ADR-0019 there is no separate role registry to
+ * validate against: a role exists for this node exactly when some rule fires
+ * on it, which is what `validateRoles` reads. This is deliberately at the STORE,
+ * not at whichever call site happens to reach `setRoles` today: a guard
+ * placed at a call site is only as durable as that call site, and a later
+ * one added without knowing the guard belongs here would ship an
+ * unvalidated role write. `add` is NOT validated here — every caller that
+ * feeds it caller-supplied roles (e.g. invitation redemption) validates
+ * them earlier, at the point the roles were themselves accepted
+ * (`InvitationStore.create` in `apps/httpeers-stack`), matching the
+ * archived delta's own choice to guard `createInvitation` and `setRoles`,
+ * never `addMember`.
+ */
+export function createMemberStore(rules: RuleSet, clock: () => number = Date.now): MemberStore {
+  const members = new Map<string, MemberRecord>();
+
+  return {
+    add(peerId, roles) {
+      const record: MemberRecord = { peerId, roles: [...roles], updatedAt: clock() };
+      members.set(peerId, record);
+      return record;
+    },
+    setRoles(peerId, roles) {
+      assertValid(validateRoles(rules, roles, `setRoles(${peerId})`));
+      const record: MemberRecord = { peerId, roles: [...roles], updatedAt: clock() };
+      members.set(peerId, record);
+      return record;
+    },
+    remove(peerId) {
+      members.delete(peerId);
+    },
+    get(peerId) {
+      return members.get(peerId);
+    },
+    list() {
+      return [...members.values()];
+    },
+  };
+}
+
+/**
+ * TTL'd, swept presence: who is live right now.
+ *
+ * Writes are monotonic per peer — see `PresenceStore` in types.ts for why.
+ * The comparison is always `seq` against the peer's own last-accepted
+ * `seq`, never wall-clock time and never across different peers.
+ */
+export function createPresenceStore(clock: () => number = Date.now): PresenceStore {
+  const presence = new Map<string, PresenceRecord>();
+
+  return {
+    heartbeat(peerId, seq, ttlMs): PresenceWriteResult {
+      const existing = presence.get(peerId);
+      if (existing !== undefined && seq <= existing.seq) {
+        return { accepted: false, reason: "stale-sequence" };
+      }
+      const record: PresenceRecord = { peerId, seq, expiresAt: clock() + ttlMs };
+      presence.set(peerId, record);
+      return { accepted: true, record };
+    },
+    isPresent(peerId) {
+      const record = presence.get(peerId);
+      return record !== undefined && record.expiresAt > clock();
+    },
+    get(peerId) {
+      return presence.get(peerId);
+    },
+    list() {
+      return [...presence.values()];
+    },
+    sweep() {
+      const now = clock();
+      const expired: string[] = [];
+      for (const record of presence.values()) {
+        if (record.expiresAt <= now) {
+          expired.push(record.peerId);
+        }
+      }
+      for (const peerId of expired) {
+        presence.delete(peerId);
+      }
+      return expired;
+    },
+  };
+}
+
+/**
+ * The bulletin board: what peers offer. Keyed by `(peerId, key)` via a
+ * two-level `Map` — not a joined string — so there is no delimiter to pick
+ * and therefore no way for a `peerId` or `key` value to collide with one.
+ * Entries persist until withdrawn or replaced, not on a timer.
+ */
+export function createAdvertisementStore(clock: () => number = Date.now): AdvertisementStore {
+  const board = new Map<string, Map<string, Advertisement>>();
+
+  return {
+    post(peerId, key, payload) {
+      const ad: Advertisement = { peerId, key, payload, postedAt: clock() };
+      let byKey = board.get(peerId);
+      if (byKey === undefined) {
+        byKey = new Map();
+        board.set(peerId, byKey);
+      }
+      byKey.set(key, ad);
+      return ad;
+    },
+    withdraw(peerId, key) {
+      board.get(peerId)?.delete(key);
+    },
+    get(peerId, key) {
+      return board.get(peerId)?.get(key);
+    },
+    list(peerId) {
+      if (peerId !== undefined) {
+        return [...(board.get(peerId)?.values() ?? [])];
+      }
+      const all: Advertisement[] = [];
+      for (const byKey of board.values()) {
+        all.push(...byKey.values());
+      }
+      return all;
+    },
+  };
+}

package/src/storage.ts

@@ -0,0 +1,136 @@
+/**
+ * The candidate `hub` package's storage seam, and two adapters for it.
+ *
+ * DERIVED, NOT DESIGNED. Everything the hub does to storage today is
+ * whole-value get / set / delete by key: `persist.ts` reads and writes one
+ * JSON file; `browser/snapshot-store.ts` reads and writes one IndexedDB
+ * value. Nothing lists, appends, or compare-and-sets. So the interface is
+ * those three methods and no more.
+ *
+ * `SnapshotStore` (`hub/hub-state.ts`) is deliberately SYNCHRONOUS, because
+ * every mutation writes and returns, and an async write would let a caller be
+ * told "member added" while the snapshot still said otherwise. Both async
+ * backends therefore need the same wrapper the browser already has: the
+ * in-memory copy is authoritative, and flushes are serialised behind it.
+ * `asyncSnapshotStore` below is that wrapper, generalised — it is
+ * `browser/snapshot-store.ts`'s logic over any `KeyValueStorage` rather than
+ * over idb-keyval specifically.
+ */
+
+import type { FilesApi } from "@statewalker/webrun-files";
+import { EMPTY_SNAPSHOT, type HubSnapshot, type SnapshotStore } from "./hub-state.js";
+
+/** The whole persistence contract. Three methods, because three is what the hub uses. */
+export interface KeyValueStorage {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/** For tests and for a hub that deliberately keeps nothing. */
+export function memoryStorage(): KeyValueStorage {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.get(key);
+    },
+    async set(key, value) {
+      map.set(key, value);
+    },
+    async delete(key) {
+      map.delete(key);
+    },
+  };
+}
+
+/**
+ * A `FilesApi` as key/value storage — one file per key under `dir`.
+ *
+ * WRITE-THEN-MOVE, because a crash mid-write must not leave a half-written
+ * snapshot where the whole state lives. `persist.ts`'s Node implementation
+ * does NOT do this (it writes in place), which is a defect this adapter does
+ * not inherit.
+ *
+ * FilesApi HAS NO CONDITIONAL WRITE — no compare-and-set, no if-match. That
+ * is why the hub's single-writer precondition is a precondition rather than
+ * something the storage layer can enforce; rung 04's third claim measures
+ * exactly what that costs.
+ */
+export function filesStorage(files: FilesApi, dir = "hub"): KeyValueStorage {
+  const path = (key: string): string => `${dir}/${encodeURIComponent(key)}.json`;
+
+  return {
+    async get(key) {
+      const file = path(key);
+      if (!(await files.exists(file))) return undefined;
+      const chunks: Uint8Array[] = [];
+      for await (const chunk of files.read(file)) chunks.push(chunk);
+      const total = chunks.reduce((n, c) => n + c.length, 0);
+      const bytes = new Uint8Array(total);
+      let at = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, at);
+        at += chunk.length;
+      }
+      return new TextDecoder().decode(bytes);
+    },
+    async set(key, value) {
+      const file = path(key);
+      const temp = `${file}.tmp`;
+      const bytes = new TextEncoder().encode(value);
+      await files.write(
+        temp,
+        (async function* () {
+          yield bytes;
+        })(),
+      );
+      await files.move(temp, file);
+    },
+    async delete(key) {
+      await files.remove(path(key));
+    },
+  };
+}
+
+export interface AsyncSnapshotStore extends SnapshotStore {
+  /** Resolves when every write issued so far has reached the backend. */
+  flushed(): Promise<void>;
+}
+
+/**
+ * Load once, then serve reads from memory and flush writes behind them —
+ * the shape `SnapshotStore`'s synchronous contract forces on any async
+ * backend.
+ */
+export async function asyncSnapshotStore(
+  storage: KeyValueStorage,
+  key = "snapshot",
+): Promise<AsyncSnapshotStore> {
+  const raw = await storage.get(key);
+  let current: HubSnapshot = EMPTY_SNAPSHOT;
+  if (raw != null) {
+    try {
+      current = JSON.parse(raw) as HubSnapshot;
+    } catch {
+      // A corrupt value reads as empty rather than throwing, matching
+      // `browser/snapshot-store.ts`. A hub that refuses to start because its
+      // state file was truncated is worse than one that starts empty and
+      // says so.
+      current = EMPTY_SNAPSHOT;
+    }
+  }
+
+  // Writes are chained, never concurrent: two overlapping flushes of the same
+  // key can land out of order, and the loser would be the newer state.
+  let chain: Promise<void> = Promise.resolve();
+
+  return {
+    read: () => current,
+    write(snapshot) {
+      current = snapshot;
+      const value = JSON.stringify(snapshot);
+      chain = chain.then(() => storage.set(key, value)).catch(() => {});
+    },
+    flushed: () => chain,
+  };
+}