@statewalker/httpeers-hub 0.1.3

package/dist/endpoints.js

@@ -0,0 +1,305 @@
+/**
+ * The hub's `.well-known` surface: registries, invitations, presence and the
+ * mesh view. The hub is an ordinary peer (note 03) — nothing here imports
+ * libp2p; it is handed a `mintToken` capability already scoped to this
+ * peer's own signing key (see `createPeer`'s `mounts` factory in
+ * `@statewalker/httpeers-core`), never the key itself.
+ *
+ * Built on Hono. `app.fetch` is already `(Request) => Promise<Response>`, so
+ * it drops straight into the `FetchHandler` contract with no adapter — and
+ * `c.req.raw` is the very `Request` the transport (or, in a test, the
+ * caller) registered a peer binding on, which is what makes `lookupPeer`
+ * and `lookupClaims` work at all from inside a handler.
+ *
+ * NO QUERY PARAMETERS. Conditional reads use `ETag` / `If-None-Match`, not
+ * `?since=`: some transports drop `url.search` before the wire, and ETag is
+ * better HTTP regardless.
+ */
+import { capabilityNames, deriveCapabilities } from "@statewalker/httpeers-access";
+import { ANONYMOUS, createMounts, json, lookupClaims, lookupPeer, } from "@statewalker/httpeers-core";
+import { Hono } from "hono";
+import { createAdminEndpoints } from "./admin.js";
+import { buildMeshView } from "./mesh-view.js";
+import { createAdvertisementStore, createPresenceStore } from "./registries.js";
+/** The capability that grants admin visibility — sees `hidden` members and gates `/admin/*` (Task 8's `DELETE /admin/members/{peerId}` included). */
+export const ADMIN_CAPABILITY = "std:mesh.admin";
+/** Presence TTL: an entry not refreshed within this window is swept. */
+export const DEFAULT_PRESENCE_TTL_MS = 15_000;
+/** Exactly two handlers, method-aware: a presence WRITE is bootstrap, a read is not. */
+export function usesTransportIdentity() {
+    return async (req) => {
+        if (req.method !== "POST")
+            return false;
+        const { pathname } = new URL(req.url);
+        return pathname === "/.well-known/invite" || pathname === "/.well-known/presence";
+    };
+}
+/**
+ * The diagnostic `/test` surface: `/test/whoami` and `/test/echo`, per the
+ * archived `12-httpeers-prototype-validated/src/endpoints.ts` (lines 128
+ * and 138). NOT hub-specific — every peer in that archive served this
+ * unconditionally, hub or not, and Task 7b's promoted E2E suites need the
+ * same: their "provider" peer (an ordinary member, never a hub) must answer
+ * `/test/whoami` with this rich shape too.
+ *
+ * This is deliberately NOT `httpeers.core`'s own default diagnostic mount
+ * (`peer.ts`'s `defaultMounts`, also `/test/whoami`) — that one answers
+ * `{ peer, sub }` from the transport/binding alone and knows nothing about
+ * a minted token's `roles`/`mesh`. The archived suites assert `body.you`,
+ * `body.roles`, `body.mesh` — fields the core's default does not have and
+ * is not meant to grow, since the core must stay hub-agnostic. Any peer
+ * that wants this richer surface mounts this handler explicitly, the same
+ * way `createHubEndpoints` below does for the hub itself.
+ */
+export function createTestSurfaceHandler(selfPeerId) {
+    const app = new Hono();
+    app.get("/test/whoami", (c) => {
+        const claims = lookupClaims(c.req.raw) ?? null;
+        return json({
+            servedBy: selfPeerId,
+            you: claims?.sub ?? null,
+            roles: claims?.roles ?? [],
+            mesh: claims?.mesh ?? null,
+        });
+    });
+    app.post("/test/echo", async (c) => json({ method: c.req.method, body: await c.req.text() }));
+    return app.fetch;
+}
+function sameAddrs(a, b) {
+    if (a == null)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    return a.every((v, i) => v === b[i]);
+}
+function sameAdvertisements(prev, next) {
+    if (prev.length !== next.length)
+        return false;
+    const prevById = new Map(prev.map((a) => [a.key, a.payload]));
+    return next.every((ad) => {
+        const p = prevById.get(ad.id);
+        return p != null && p.kind === ad.kind && p.title === ad.title;
+    });
+}
+export function createHubEndpoints(init) {
+    const now = init.now ?? Date.now;
+    const presenceTtlMs = init.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS;
+    const advertisementAccess = init.advertisementAccess ?? {};
+    const presenceStore = createPresenceStore(now);
+    const advertisementStore = createAdvertisementStore(now);
+    const addrsByPeer = new Map();
+    // Whatever this deployment says about itself, posted once — see
+    // `ownAdvertisements` for why this is the only path onto the board for a
+    // peer that never heartbeats.
+    for (const ad of init.ownAdvertisements ?? []) {
+        advertisementStore.post(init.selfPeerId, ad.id, {
+            kind: ad.kind,
+            title: ad.title,
+        });
+    }
+    // Tracks the highest `seq` EVER accepted for a peer, independent of
+    // `presenceStore` — which the TTL sweep clears. Without this, a delayed
+    // duplicate of an old heartbeat arriving AFTER the peer has already been
+    // swept would look like a brand-new write (no record exists to compare
+    // against) and resurrect a peer that has genuinely departed. This map is
+    // never cleared by sweep, only ever advanced.
+    const lastSeqByPeer = new Map();
+    // The one counter this whole module exists to bump correctly: it moves
+    // only when the OBSERVABLE mesh view could have changed (a member added,
+    // a peer's online/addrs state changed, an advertisement changed, or the
+    // sweep removed someone) — never on a heartbeat that repeats what the hub
+    // already knew, which is what keeps `/.well-known/mesh`'s ETag stable
+    // between identical heartbeats instead of churning every 5 s.
+    let meshVersion = 1;
+    const bumpMesh = () => {
+        meshVersion++;
+    };
+    const claimsOf = (req) => lookupClaims(req) ?? null;
+    const provenPeer = (req) => {
+        const peer = lookupPeer(req);
+        if (peer === undefined || peer === ANONYMOUS) {
+            throw new Error("hub bootstrap handler reached without a transport-proven peer");
+        }
+        return peer;
+    };
+    const withdrawAllFor = (peerId) => {
+        for (const ad of advertisementStore.list(peerId))
+            advertisementStore.withdraw(peerId, ad.key);
+    };
+    const app = new Hono();
+    // --- BOOTSTRAP: no token exists yet ---------------------------------------
+    app.post("/.well-known/invite", async (c) => {
+        const peerId = provenPeer(c.req.raw);
+        const { id } = await c.req.json();
+        const redemption = init.invitations.redeem(id);
+        if (!redemption.ok) {
+            return json({ error: `invitation ${redemption.reason}` }, 403);
+        }
+        init.memberStore.add(peerId, redemption.roles);
+        bumpMesh();
+        return json({
+            token: await init.mintToken(peerId, redemption.roles),
+            mesh: init.selfPeerId,
+            roles: redemption.roles,
+        });
+    });
+    // --- BOOTSTRAP: mints the token, so cannot itself require one -------------
+    app.post("/.well-known/presence", async (c) => {
+        const peerId = provenPeer(c.req.raw);
+        const member = init.memberStore.get(peerId);
+        if (member == null)
+            return json({ error: "not a member" }, 403);
+        const body = await c.req.json();
+        const lastSeq = lastSeqByPeer.get(peerId);
+        if (lastSeq !== undefined && body.seq <= lastSeq) {
+            return json({ error: "stale-sequence" }, 409);
+        }
+        lastSeqByPeer.set(peerId, body.seq);
+        const wasPresent = presenceStore.isPresent(peerId);
+        const prevAddrs = addrsByPeer.get(peerId);
+        // Result intentionally ignored: `lastSeqByPeer` above already decided
+        // whether this write is stale, using a guard that survives the TTL
+        // sweep clearing `presenceStore`'s own record (see that map's doc
+        // comment) — so `presenceStore`'s own monotonic check can only agree.
+        presenceStore.heartbeat(peerId, body.seq, presenceTtlMs);
+        addrsByPeer.set(peerId, body.addrs);
+        let changed = !wasPresent || !sameAddrs(prevAddrs, body.addrs);
+        if (body.advertisements !== undefined) {
+            const prevAds = advertisementStore.list(peerId);
+            if (!sameAdvertisements(prevAds, body.advertisements)) {
+                withdrawAllFor(peerId);
+                for (const ad of body.advertisements) {
+                    const payload = { kind: ad.kind, title: ad.title };
+                    advertisementStore.post(peerId, ad.id, payload);
+                }
+                changed = true;
+            }
+        }
+        if (changed)
+            bumpMesh();
+        return json({
+            token: await init.mintToken(peerId, member.roles),
+            versions: {
+                mesh: meshVersion,
+                policy: init.revocations.policyVersion(),
+                rules: init.rules.version,
+            },
+            // `ttl` is unchanged context from the archive (`CHANGES-v0.8.0.txt`'s
+            // heartbeat shape `{ token, versions, meshVersion, ttl }`), not part
+            // of that delta -- unlike `meshVersion`, which WAS superseded by
+            // `versions.mesh` and correctly dropped (Ruling R31). It lets a
+            // client take its heartbeat interval from the server rather than
+            // hardcoding it.
+            ttl: presenceTtlMs,
+        });
+    });
+    // --- ORDINARY: identity comes from the verified token ----------------------
+    app.get("/.well-known/members", (_c) => json({ members: init.memberStore.list() }));
+    app.get("/.well-known/presence", (_c) => json({
+        presence: presenceStore.list().map((p) => ({ ...p, addrs: addrsByPeer.get(p.peerId) ?? [] })),
+    }));
+    app.get("/.well-known/advertisements", (_c) => json({
+        advertisements: advertisementStore.list().map((ad) => {
+            const payload = ad.payload;
+            return { peerId: ad.peerId, id: ad.key, kind: payload.kind, title: payload.title };
+        }),
+    }));
+    // ONE expression, two readers: this endpoint and `HubEndpoints.meshView`
+    // below. They must not drift -- an in-process UI showing a different
+    // membership or a different `online` from the one every remote peer reads
+    // would be a debugging trap rather than a diagnostic.
+    const viewFor = (self, callerCapabilities) => buildMeshView({
+        version: meshVersion,
+        self,
+        members: init.memberStore.list(),
+        presence: presenceStore.list(),
+        addrsByPeer,
+        advertisements: advertisementStore.list(),
+        callerCapabilities,
+        advertisementAccess,
+        adminCapability: ADMIN_CAPABILITY,
+    });
+    app.get("/.well-known/mesh", (c) => {
+        const claims = claimsOf(c.req.raw);
+        if (claims == null)
+            return json({ error: "unauthenticated" }, 401);
+        const etag = `"v${meshVersion}"`;
+        if (c.req.header("if-none-match") === etag) {
+            return new Response(null, { status: 304, headers: { etag } });
+        }
+        const view = viewFor(claims.sub, deriveCapabilities(init.rules, claims.roles));
+        return new Response(JSON.stringify(view), {
+            headers: { "content-type": "application/json", etag },
+        });
+    });
+    // ADR-0016's amendment: the rules are published, still read-only in the
+    // strict sense -- what this returns influences no decision, here or on any
+    // other peer, which is why no signing scheme is needed for it. It is served
+    // for discovery, debugging and the explainability of a denial.
+    app.get("/.well-known/rules", (c) => {
+        const etag = `"rules${init.rules.version}"`;
+        if (c.req.header("if-none-match") === etag) {
+            return new Response(null, { status: 304, headers: { etag } });
+        }
+        return new Response(JSON.stringify(init.rules), {
+            headers: { "content-type": "application/json", etag },
+        });
+    });
+    app.get("/.well-known/revocations", (c) => {
+        const version = init.revocations.policyVersion();
+        const etag = `"policy${version}"`;
+        if (c.req.header("if-none-match") === etag) {
+            return new Response(null, { status: 304, headers: { etag } });
+        }
+        return new Response(JSON.stringify({ version, entries: init.revocations.list() }), {
+            headers: { "content-type": "application/json", etag },
+        });
+    });
+    // --- admin-only, to exercise the policy middleware -----------------------
+    // Archive: `12/src/endpoints.ts` line 122. Listing only — invitations are
+    // created programmatically (`InvitationStore.create`, `persist.ts`), never
+    // over HTTP; see this app's `PROVENANCE.md`.
+    app.get("/admin/invitations", (c) => json({ ok: true, issuedBy: init.selfPeerId, caller: claimsOf(c.req.raw)?.sub }));
+    app.all("*", (c) => json({ error: "not found", path: new URL(c.req.raw.url).pathname }, 404));
+    const mounts = createMounts();
+    mounts.provide("/.well-known", app.fetch);
+    mounts.provide("/test", createTestSurfaceHandler(init.selfPeerId));
+    mounts.provide("/admin", app.fetch);
+    // Longer prefix wins (R-1): "/admin/members" is more specific than the
+    // "/admin" mount above, so DELETE /admin/members/{peerId} reaches
+    // admin.ts's handler while GET /admin/invitations keeps hitting `app`.
+    mounts.provide("/admin/members", createAdminEndpoints({ memberStore: init.memberStore, revocations: init.revocations }));
+    // Revocation for `/search` (and every other route on this hub) is NOT
+    // handled here. Policy (`policy.ts`) only ever checks the CAPABILITY a
+    // token's roles expand to, which cannot see a membership change made
+    // after the token was minted -- but the fix for that is a single seam on
+    // this peer's own `createPeer` (`hub/main.ts`'s `revocationCache:
+    // revocations`, using `RevocationRegistry`'s own `check`, added in
+    // `httpeers.core` alongside this task -- see that package's
+    // `revocation.ts`), applied uniformly to EVERY mount by the binding
+    // middleware before any handler runs. An earlier version of this file put
+    // a bespoke membership check on this one mount instead; that covered only
+    // the route being built and silently left every other hub endpoint
+    // (including `/admin/*`) still honouring a revoked token until it
+    // expired -- removed on review. See `hub/main.ts` and this app's
+    // `PROVENANCE.md`.
+    for (const [prefix, handler] of Object.entries(init.extraMounts ?? {})) {
+        mounts.provide(prefix, handler);
+    }
+    return {
+        mounts,
+        // Every capability the rules can derive, so the hub's own view is
+        // unfiltered -- see this field's doc comment on `HubEndpoints`.
+        meshView: () => viewFor(init.selfPeerId, new Set(capabilityNames(init.rules))),
+        sweep() {
+            const expired = presenceStore.sweep();
+            if (expired.length === 0)
+                return;
+            for (const peerId of expired) {
+                addrsByPeer.delete(peerId);
+                withdrawAllFor(peerId);
+            }
+            bumpMesh();
+        },
+    };
+}

package/dist/hub-state.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 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 declare const EMPTY_SNAPSHOT: HubSnapshot;
+/**
+ * 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 declare function createHubState(init: CreateHubStateInit): PersistentHub;
+//# sourceMappingURL=hub-state.d.ts.map

package/dist/hub-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-state.d.ts","sourceRoot":"","sources":["../src/hub-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACzC;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,EAAE,WAI5B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,WAAW,CAAC;IACpB,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,kBAAkB,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,0IAA0I;IAC1I,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAAC;IACzC,sFAAsF;IACtF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IACnE,6EAA6E;IAC7E,OAAO,IAAI,gBAAgB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,KAAK,EAAE,aAAa,CAAC;IACrB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM,KAAK,WAAW,CAAC;CAC1E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,aAAa,CA2EtE"}

package/dist/hub-state.js

@@ -0,0 +1,118 @@
+/**
+ * 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 { assertValid, validateRoles } from "@statewalker/httpeers-access";
+/** What a store with nothing in it yet must read as — see `SnapshotStore.read`. */
+export const EMPTY_SNAPSHOT = {
+    members: [],
+    spentInvitationIds: [],
+    pendingInvitations: [],
+};
+/**
+ * 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) {
+    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 = () => {
+        init.store.write({
+            members: innerMembers.list(),
+            spentInvitationIds: [...spentIds],
+            pendingInvitations: [...pending.values()],
+        });
+    };
+    const 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((snapshot.pendingInvitations ?? []).map((record) => [record.id, record]));
+    const invitations = {
+        create(id, roles, ttlMs) {
+            assertValid(validateRoles(init.rules, roles, `invitation '${id}'`));
+            const record = { 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/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,KAAK,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,kBAAkB,EACvB,cAAc,EACd,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,EACL,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,aAAa,GACd,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Minting membership, holding the registries, and saying who is in the mesh.
+ */
+export { createHub } from "./create-hub.js";
+export { ADMIN_CAPABILITY, createHubEndpoints, DEFAULT_PRESENCE_TTL_MS, usesTransportIdentity, } from "./endpoints.js";
+export { createHubState, EMPTY_SNAPSHOT, } from "./hub-state.js";
+export { buildMeshView } from "./mesh-view.js";
+export { createAdvertisementStore, createMemberStore, createPresenceStore } from "./registries.js";
+export { asyncSnapshotStore, filesStorage, memoryStorage, } from "./storage.js";

package/dist/mesh-view.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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";
+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 declare function buildMeshView(init: BuildMeshViewInit): MeshView;
+//# sourceMappingURL=mesh-view.d.ts.map

package/dist/mesh-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-view.d.ts","sourceRoot":"","sources":["../src/mesh-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,cAAc,EACf,MAAM,4BAA4B,CAAC;AAMpC,YAAY,EAAE,QAAQ,EAAE,qBAAqB,EAAE,cAAc,EAAE,CAAC;AAEhE,wGAAwG;AACxG,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,4FAA4F;IAC5F,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,mIAAmI;IACnI,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,QAAQ,CAyB/D"}

package/dist/mesh-view.js

@@ -0,0 +1,23 @@
+export function buildMeshView(init) {
+    const isAdmin = init.callerCapabilities.has(init.adminCapability);
+    const present = new Set(init.presence.map((p) => p.peerId));
+    const members = 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 = init.advertisements
+        .filter((ad) => {
+        const kind = ad.payload.kind;
+        const required = init.advertisementAccess[kind];
+        return required == null || init.callerCapabilities.has(required);
+    })
+        .map((ad) => {
+        const payload = ad.payload;
+        return { peerId: ad.peerId, id: ad.key, kind: payload.kind, title: payload.title };
+    });
+    return { version: init.version, self: init.self, members, advertisements };
+}

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 type { KeyValueStorage } from "./storage.js";
+export declare function fileStorage(path: string): KeyValueStorage;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAyBzD"}