@statewalker/httpeers-hub 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @statewalker/httpeers-hub
+
+Minting membership, holding the registries, and saying who is in the mesh.
+
+```ts
+import { createHub, memoryStorage } from "@statewalker/httpeers-hub";
+
+const hub = await createHub({
+  selfPeerId,                       // this hub's peerId IS the mesh's name
+  policies: rules,
+  storage: memoryStorage(),
+  mintToken: async (sub, roles) => mintToken({ signer, sub, roles, ttlMs: 60_000 }),
+});
+
+const invite = await hub.invitations.create(["member"], 60_000);
+```
+
+`hub.mounts` is a mount table. Serving it on a wire is somebody else's job.
+
+## A hub has no transport, and that is what lets it run in a tab
+
+This package dials nothing and listens on nothing. `servePeer`
+(`@statewalker/httpeers-libp2p`) is what puts the mount table on a wire, and
+the dependency list here is `core`, `access` and `hono` — no libp2p, asserted
+by `tests/boundary.test.ts`.
+
+That is not tidiness. It is the property that makes a **hub in a browser tab**
+possible at all, and it is why the hub's *lifecycle* is deliberately not in
+this package: composing a node, a relay reservation, `createHub` and an edge is
+application wiring, and both the Node hub and the hub page do it themselves.
+`httpeers-conformance` compiles that composition as a consumer, so if the
+packages ever stop being sufficient for it, a test says so.
+
+## Invitations are bearer credentials, and are treated as such
+
+An invitation id is **128 bits from the platform CSPRNG**, never `Math.random`:
+whoever holds one can become a member. The hub generates it **by default**, so
+nobody has to invent unguessable strings — `create(roles, ttlMs)` is the whole
+call. A caller may name the id (`{ id }`) for a deployment migrating existing
+codes or a test wanting a constant, and that is the only way to get a weak one.
+
+Every mutator resolves when the write is **durable**. A caller is never told
+"created" before it is, because an invitation handed out over the phone and
+then lost to a crash a millisecond later is an invitation somebody is standing
+there holding.
+
+Unredeemed invitations **survive a restart** — they are in the snapshot, not in
+memory — and `pending()` lists them so an operator can see what is outstanding.
+
+## The snapshot is synchronous and the storage is not
+
+`SnapshotStore.write` must stay synchronous: `createHubState` calls it and
+returns, so an async write would open a window where a caller has been told a
+member was added while the snapshot still says otherwise. There is no way to
+block on a promise in a browser, so the shape is forced:
+
+**the in-memory copy is authoritative, and the backend trails it.** `write`
+replaces `current` and returns; the flush runs behind it on one promise chain.
+Reads answer from `current`, so the hub always sees what it last wrote.
+
+The chain matters: writes reach storage **in order**. An unordered
+`void put(...)` per write would let a slow earlier write land on top of a later
+one and **resurrect a spent invitation id**, which is a membership bypass.
+`asyncSnapshotStore` is that wrapper over any `KeyValueStorage`, and
+`flushed()` is how a test waits for durability.
+
+Honestly stated: a tab closed between a write and its flush loses that write.
+This is a page, not a database.
+
+| Import | Storage |
+|---|---|
+| `.` | `memoryStorage()`, `filesStorage(files, dir?)` over a `FilesApi` |
+| `./node` | `fileStorage(path)` |
+| `./browser` | `idbStorage(name?, store?)` — IndexedDB, which is transactional |
+
+`filesStorage` **writes-then-moves**. The prototype's Node persistence wrote in
+place, so a crash mid-write left a half-written snapshot where the whole state
+lives; this adapter does not inherit that.
+
+## Roles come off the rules, not a second list
+
+There is no separate vocabulary document. A role exists for this mesh exactly
+when some rule fires on it, so `roleNames(rules)` is the registry, and both
+`members.setRoles` and `invitations.create` validate against it. A role added
+to the policy appears everywhere without anyone updating a second place.
+
+## Changing roles takes two writes, or it is a lie
+
+`MemberStore.setRoles` rewrites the record — but the peer is carrying a token
+that already states its **old** roles and stays valid until it expires, so a
+demoted admin keeps admin for the life of that token. `revocations.changeRoles`
+records the change so tokens minted before it stop verifying, which is what
+makes the new roles take effect on the peer's next heartbeat.
+
+The store does not do this for you. Both halves, or the change is cosmetic.
+
+## Presence is a heartbeat
+
+A member that stops beating is swept from the mesh view within one TTL, and its
+advertisements go with it. `sweep()` is callable directly — which is what a
+test with a controlled clock wants — or driven on a timer with
+`sweepIntervalMs`.
+
+## Tests
+
+**43, plus 4 skipped** (the platform-entry exemptions in the boundary test).
+The hub is also exercised for real in `@statewalker/httpeers-conformance`,
+where it mints an invitation that a live member redeems over a relay.

package/dist/admin.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `DELETE /admin/members/{peerId}` — closes the gap the design record has
+ * carried since Task 1: `MemberStore.remove` has existed as a store method
+ * with no endpoint and no authorisation the whole time, "exactly the kind
+ * of thing that must not be reachable by an ordinary member" (design
+ * record §5.2). Capability gating (`std:mesh.admin`) is `policy.ts`'s
+ * `/admin` policy in `policy.ts`, not this handler's job — this file only
+ * does the removal, same split as every other handler in this app.
+ *
+ * TWO CALLS, NOT ONE, BECAUSE THIS PACKAGE SPLIT WHAT THE ARCHIVE KEPT AS
+ * ONE STORE. `hub.memberStore.remove(peerId)` drops membership;
+ * `hub.revocations.revoke(peerId)` records the change so a provider's
+ * pulled deny-list cache can see it — see `tests/support/mesh.ts`'s own
+ * header comment for the archived one-call precedent this splits in two.
+ * `RevocationRegistry.revoke` bumps `policyVersion()` internally (see
+ * `revocation.ts`): there is no separate "bump the version" step to
+ * forget — calling `revoke` at all IS the bump, which is what makes a
+ * provider's next heartbeat see the change.
+ *
+ * Removal (and revocation) is unconditional and idempotent: `MemberStore
+ * .remove` on a peerId that is not currently a member is a harmless no-op
+ * (`Map.delete` on a missing key), and revoking a peerId with no prior
+ * membership is a legitimate "make sure this identity can never redeem an
+ * old token" operation, not an error condition — so this handler does not
+ * 404 on an unknown peerId.
+ */
+import type { RevocationRegistry } from "@statewalker/httpeers-access/issuer";
+import type { FetchHandler, MemberStore } from "@statewalker/httpeers-core";
+export interface AdminEndpointsInit {
+    memberStore: MemberStore;
+    revocations: RevocationRegistry;
+}
+/** `DELETE /admin/members/{peerId}`. Mounted at `/admin/members` — see `hub/endpoints.ts`. */
+export declare function createAdminEndpoints(init: AdminEndpointsInit): FetchHandler;
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAI5E,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY,CAW3E"}

package/dist/admin.js

@@ -0,0 +1,39 @@
+/**
+ * `DELETE /admin/members/{peerId}` — closes the gap the design record has
+ * carried since Task 1: `MemberStore.remove` has existed as a store method
+ * with no endpoint and no authorisation the whole time, "exactly the kind
+ * of thing that must not be reachable by an ordinary member" (design
+ * record §5.2). Capability gating (`std:mesh.admin`) is `policy.ts`'s
+ * `/admin` policy in `policy.ts`, not this handler's job — this file only
+ * does the removal, same split as every other handler in this app.
+ *
+ * TWO CALLS, NOT ONE, BECAUSE THIS PACKAGE SPLIT WHAT THE ARCHIVE KEPT AS
+ * ONE STORE. `hub.memberStore.remove(peerId)` drops membership;
+ * `hub.revocations.revoke(peerId)` records the change so a provider's
+ * pulled deny-list cache can see it — see `tests/support/mesh.ts`'s own
+ * header comment for the archived one-call precedent this splits in two.
+ * `RevocationRegistry.revoke` bumps `policyVersion()` internally (see
+ * `revocation.ts`): there is no separate "bump the version" step to
+ * forget — calling `revoke` at all IS the bump, which is what makes a
+ * provider's next heartbeat see the change.
+ *
+ * Removal (and revocation) is unconditional and idempotent: `MemberStore
+ * .remove` on a peerId that is not currently a member is a harmless no-op
+ * (`Map.delete` on a missing key), and revoking a peerId with no prior
+ * membership is a legitimate "make sure this identity can never redeem an
+ * old token" operation, not an error condition — so this handler does not
+ * 404 on an unknown peerId.
+ */
+import { json } from "@statewalker/httpeers-core";
+import { Hono } from "hono";
+/** `DELETE /admin/members/{peerId}`. Mounted at `/admin/members` — see `hub/endpoints.ts`. */
+export function createAdminEndpoints(init) {
+    const app = new Hono();
+    app.delete("/admin/members/:peerId", (c) => {
+        const peerId = c.req.param("peerId");
+        init.memberStore.remove(peerId);
+        init.revocations.revoke(peerId);
+        return json({ ok: true, removed: peerId, policyVersion: init.revocations.policyVersion() });
+    });
+    return app.fetch;
+}

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser profile: hub state in IndexedDB.
+ *
+ * A hub in a tab is a real hub — it mints, it holds the registries, and its
+ * members expect to still be members after a reload. `localStorage` would do
+ * for strings, but IndexedDB is transactional, which matters when two writes
+ * race a reload.
+ */
+import type { KeyValueStorage } from "./storage.js";
+export declare function idbStorage(name?: string, store?: string): KeyValueStorage;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAyBpD,wBAAgB,UAAU,CAAC,IAAI,SAAiB,EAAE,KAAK,SAAU,GAAG,eAAe,CAsClF"}

package/dist/browser.js

@@ -0,0 +1,42 @@
+/**
+ * The browser profile: hub state in IndexedDB.
+ *
+ * A hub in a tab is a real hub — it mints, it holds the registries, and its
+ * members expect to still be members after a reload. `localStorage` would do
+ * for strings, but IndexedDB is transactional, which matters when two writes
+ * race a reload.
+ */
+export function idbStorage(name = "httpeers-hub", store = "state") {
+    const open = () => new Promise((resolve, reject) => {
+        const request = indexedDB.open(name, 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(store)) {
+                request.result.createObjectStore(store);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    const run = async (mode, act) => {
+        const db = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const request = act(db.transaction(store, mode).objectStore(store));
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+        }
+        finally {
+            db.close();
+        }
+    };
+    return {
+        get: (key) => run("readonly", (s) => s.get(key)),
+        set: async (key, value) => {
+            await run("readwrite", (s) => s.put(value, key));
+        },
+        delete: async (key) => {
+            await run("readwrite", (s) => s.delete(key));
+        },
+    };
+}

package/dist/create-hub.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One constructor that returns the parts.
+ *
+ * THE API SPEC SAID THERE WOULD NOT BE A `createHub`, and the prototype proved
+ * it wrong by writing the assembly three times — the Node hub, the browser hub
+ * and the test hub. A hub is not a mount table: it is a mount table *plus* a
+ * snapshot store, a clock, a revocation registry, an invitation store, two
+ * registries with different consistency needs, and a sweep timer. Anything that
+ * hands back only the mounts leaves the other six to every caller.
+ *
+ * `mounts` is still separately usable, so nothing is walled off — the point is
+ * to stop each assembly re-deriving the wiring, not to hide it.
+ *
+ * THE ORDERING CYCLE, closed here because it cannot be closed by the caller.
+ * A hub's node must exist before `createHub` (the node needs a key; this needs
+ * `selfPeerId`), and the node's connection gater needs `hub.isMember`. So the
+ * documented order is:
+ *
+ *   key -> node with a LATE-BOUND gater -> createHub -> servePeer
+ *        -> point the gater's thunk at hub.isMember
+ *
+ * `membershipGater` takes a thunk for exactly this reason; see its comment in
+ * `httpeers-libp2p`.
+ */
+import type { RuleSet } from "@statewalker/httpeers-access";
+import { RevocationRegistry } from "@statewalker/httpeers-access/issuer";
+import type { FetchHandler, MeshView, Mounts, PeerIdStr } from "@statewalker/httpeers-core";
+import { type HubEndpointsInit } from "./endpoints.js";
+import { type InvitationRecord, type InvitationRedemption, type PersistentHub } from "./hub-state.js";
+import { type KeyValueStorage } from "./storage.js";
+export interface CreateHubInit {
+    /** This hub's own peerId — the mesh identity every token restates. */
+    selfPeerId: PeerIdStr;
+    /** Mint a membership token that self-certifies as this mesh. */
+    mintToken: HubEndpointsInit["mintToken"];
+    /** Where members and spent invitation ids are persisted. Defaults to memory. */
+    storage?: KeyValueStorage;
+    /** This mesh's Datalog rules. Injected, never global — there is no default rule set. */
+    policies: RuleSet;
+    now?: () => number;
+    presenceTtlMs?: number;
+    /**
+     * Expire stale presence on a timer. Omit to drive `sweep()` yourself, which
+     * is what a test with a controlled clock wants.
+     */
+    sweepIntervalMs?: number;
+    extraMounts?: Record<string, FetchHandler>;
+    ownAdvertisements?: Array<{
+        id: string;
+        kind: string;
+        title: string;
+    }>;
+    advertisementAccess?: Record<string, string>;
+    /** Longest life of any token this hub mints. Sets the revocation pruning horizon. */
+    maxTokenTtlMs?: number;
+}
+export interface Hub {
+    /** The `.well-known` surface and `/admin`, plus whatever `extraMounts` added. */
+    mounts: Mounts;
+    /** Expire stale presence and the advertisements that rode along with it. */
+    sweep(): void;
+    /** The very view `GET /.well-known/mesh` serves, read in-process. */
+    meshView(caller?: PeerIdStr): MeshView;
+    /**
+     * The operator-facing shape (spec §9), which differs from the store's:
+     * the hub generates the id, and every mutator resolves when the write is
+     * DURABLE — so a caller is never told "created" before it is, and an
+     * invitation handed out over the phone cannot be lost to a crash a
+     * millisecond later.
+     */
+    invitations: {
+        create(roles: string[], ttlMs: number, opts?: {
+            id?: string;
+        }): Promise<{
+            id: string;
+            expiresAt: number;
+        }>;
+        redeem(id: string): Promise<InvitationRedemption>;
+        status(id: string): "unspent" | "redeemed" | "expired" | "unknown";
+        pending(): InvitationRecord[];
+    };
+    members: PersistentHub["memberStore"];
+    isMember(peerId: PeerIdStr): boolean;
+    revocations: RevocationRegistry;
+    rules: RuleSet;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createHub(init: CreateHubInit): Promise<Hub>;
+//# sourceMappingURL=create-hub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-hub.d.ts","sourceRoot":"","sources":["../src/create-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAsB,KAAK,eAAe,EAAiB,MAAM,cAAc,CAAC;AAEvF,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,UAAU,EAAE,SAAS,CAAC;IACtB,gEAAgE;IAChE,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,gFAAgF;IAChF,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,iBAAiB,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,GAAG;IAClB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACvC;;;;;;OAMG;IACH,WAAW,EAAE;QACX,MAAM,CACJ,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAA;SAAE,GACrB,OAAO,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAClD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;QACnE,OAAO,IAAI,gBAAgB,EAAE,CAAC;KAC/B,CAAC;IACF,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACrC,WAAW,EAAE,kBAAkB,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAeD,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CA6FjE"}

package/dist/create-hub.js

@@ -0,0 +1,132 @@
+/**
+ * One constructor that returns the parts.
+ *
+ * THE API SPEC SAID THERE WOULD NOT BE A `createHub`, and the prototype proved
+ * it wrong by writing the assembly three times — the Node hub, the browser hub
+ * and the test hub. A hub is not a mount table: it is a mount table *plus* a
+ * snapshot store, a clock, a revocation registry, an invitation store, two
+ * registries with different consistency needs, and a sweep timer. Anything that
+ * hands back only the mounts leaves the other six to every caller.
+ *
+ * `mounts` is still separately usable, so nothing is walled off — the point is
+ * to stop each assembly re-deriving the wiring, not to hide it.
+ *
+ * THE ORDERING CYCLE, closed here because it cannot be closed by the caller.
+ * A hub's node must exist before `createHub` (the node needs a key; this needs
+ * `selfPeerId`), and the node's connection gater needs `hub.isMember`. So the
+ * documented order is:
+ *
+ *   key -> node with a LATE-BOUND gater -> createHub -> servePeer
+ *        -> point the gater's thunk at hub.isMember
+ *
+ * `membershipGater` takes a thunk for exactly this reason; see its comment in
+ * `httpeers-libp2p`.
+ */
+import { RevocationRegistry } from "@statewalker/httpeers-access/issuer";
+import { createHubEndpoints } from "./endpoints.js";
+import { createHubState, } from "./hub-state.js";
+import { createMemberStore } from "./registries.js";
+import { asyncSnapshotStore, memoryStorage } from "./storage.js";
+/**
+ * An invitation id.
+ *
+ * 128 bits from the platform CSPRNG, base36. An invitation is a bearer
+ * credential for membership, so a guessable id is a way into the mesh —
+ * `Math.random` is not acceptable here and the crypto global is available on
+ * every runtime this package targets.
+ */
+function newInvitationId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export async function createHub(init) {
+    const now = init.now ?? Date.now;
+    const storage = init.storage ?? memoryStorage();
+    // Storage is async; the snapshot seam is not. An in-memory authoritative
+    // copy with serialised flushes behind it is what lets `SnapshotStore.write`
+    // stay synchronous while the durable write is still awaited by whoever
+    // mutated — so a caller is never told "added" before it is.
+    const snapshots = await asyncSnapshotStore(storage);
+    const state = createHubState({
+        store: snapshots,
+        rules: init.policies,
+        now,
+        createMemberStore,
+    });
+    const revocations = new RevocationRegistry({
+        maxTokenTtlMs: init.maxTokenTtlMs ?? 24 * 60 * 60 * 1000,
+        now,
+    });
+    const endpoints = createHubEndpoints({
+        selfPeerId: init.selfPeerId,
+        mintToken: init.mintToken,
+        memberStore: state.memberStore,
+        invitations: state.invitations,
+        rules: init.policies,
+        revocations,
+        advertisementAccess: init.advertisementAccess,
+        extraMounts: init.extraMounts,
+        ownAdvertisements: init.ownAdvertisements,
+        presenceTtlMs: init.presenceTtlMs,
+        now,
+    });
+    // The timer is optional so a test can drive `sweep()` with a controlled
+    // clock. A hub that also sweeps on a real timer would race that test.
+    let timer;
+    if (init.sweepIntervalMs != null) {
+        timer = setInterval(() => endpoints.sweep(), init.sweepIntervalMs);
+        // Never hold a process open for a sweep. A CLI that finished its work
+        // should exit, and an interval that keeps it alive is a hang nobody
+        // attributes to the hub.
+        timer.unref?.();
+    }
+    let stopped = false;
+    return {
+        mounts: endpoints.mounts,
+        sweep: endpoints.sweep,
+        meshView: endpoints.meshView,
+        invitations: {
+            async create(roles, ttlMs, opts) {
+                // A caller may name the id — a deployment migrating existing codes, or
+                // a test wanting a constant — but the hub generates one by default so
+                // nobody has to invent unguessable strings.
+                const id = opts?.id ?? newInvitationId();
+                const record = state.invitations.create(id, roles, ttlMs);
+                await snapshots.flushed();
+                return { id: record.id, expiresAt: record.expiresAt };
+            },
+            async redeem(id) {
+                const result = state.invitations.redeem(id);
+                // Flush even on refusal: a redemption that FAILED still may have
+                // consumed nothing, but one that succeeded must be durable before the
+                // caller is told it is a member.
+                await snapshots.flushed();
+                return result;
+            },
+            status: (id) => state.invitations.status(id),
+            pending: () => state.invitations.pending(),
+        },
+        members: state.memberStore,
+        isMember: (peerId) => state.memberStore.get(peerId) !== undefined,
+        revocations,
+        rules: init.policies,
+        async reset() {
+            // Forget every member and every spent invitation id. The next start
+            // founds a fresh mesh under the SAME peerId — which is the one thing
+            // this cannot undo, and why it is a separate call rather than something
+            // `stop()` does.
+            for (const record of state.memberStore.list())
+                state.memberStore.remove(record.peerId);
+            await snapshots.flushed();
+        },
+        async stop() {
+            // Idempotent: an assembly that tears down twice — a page unloading while
+            // a test also cleans up — must not see the second call throw.
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer != null)
+                clearInterval(timer);
+        },
+    };
+}

package/dist/endpoints.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 type { RuleSet } from "@statewalker/httpeers-access";
+import type { RevocationRegistry } from "@statewalker/httpeers-access/issuer";
+import type { FetchHandler, MemberStore, Mounts, PeerIdStr, UsesTransportIdentity } from "@statewalker/httpeers-core";
+import type { InvitationStore } from "./hub-state.js";
+import type { MeshView } from "./mesh-view.js";
+/** The capability that grants admin visibility — sees `hidden` members and gates `/admin/*` (Task 8's `DELETE /admin/members/{peerId}` included). */
+export declare const ADMIN_CAPABILITY = "std:mesh.admin";
+/** Presence TTL: an entry not refreshed within this window is swept. */
+export declare const DEFAULT_PRESENCE_TTL_MS = 15000;
+/** Exactly two handlers, method-aware: a presence WRITE is bootstrap, a read is not. */
+export declare function usesTransportIdentity(): UsesTransportIdentity;
+/**
+ * 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 declare function createTestSurfaceHandler(selfPeerId: PeerIdStr): FetchHandler;
+export interface HubEndpointsInit {
+    selfPeerId: PeerIdStr;
+    /**
+     * Mint a membership token that self-certifies as this mesh. Structurally
+     * `MountsFactoryContext["mintToken"]` from `httpeers.core`, restated here
+     * rather than imported so this file stays a plain description of what the
+     * hub needs -- including the audience option ADR-0020 added, which nothing
+     * in this file passes yet: the invitation and presence protocols mint
+     * unrestricted tokens, and narrowing them is a protocol change, not a
+     * signature change.
+     */
+    mintToken: (sub: string, roles: string[], options?: {
+        ttlMs?: number;
+        audience?: readonly PeerIdStr[];
+    }) => Promise<string>;
+    memberStore: MemberStore;
+    invitations: InvitationStore;
+    /** This mesh's Datalog rules and policies (ADR-0019) — published read-only, and the source of the caller's capabilities in the mesh view. */
+    rules: RuleSet;
+    revocations: RevocationRegistry;
+    /** `kind` -> capability required to see advertisements of that kind. Defaults to `{}` (no kind gated). */
+    advertisementAccess?: Record<string, string>;
+    presenceTtlMs?: number;
+    now?: () => number;
+    /**
+     * Application mounts served alongside the hub's own `.well-known` surface
+     * and `/admin`, behind the same access checks.
+     *
+     * The prototype hard-mounted a demo `/search` endpoint here, which made the
+     * library import the application. A hub is membership and the bulletin
+     * board; what else a particular deployment serves is not its business.
+     */
+    extraMounts?: Record<string, FetchHandler>;
+    /**
+     * What this hub advertises about ITSELF on the bulletin board.
+     *
+     * Posted once at construction, because the hub is the one peer that never
+     * sends a heartbeat — and a heartbeat's `advertisements` array is otherwise
+     * the only way anything reaches that store. The prototype learned this the
+     * hard way: its `/search` mount was served and gated but INVISIBLE, so a
+     * consumer filtering `/.well-known/mesh` by `kind` found the image peer and
+     * nothing else.
+     *
+     * A hub that serves a route while withholding its advertisement is a
+     * half-wired state, so a deployment passing `extraMounts` almost always
+     * wants a matching entry here. These never need withdrawing: `sweep`
+     * withdraws only for peers whose PRESENCE expired, and a hub has no presence
+     * record of its own.
+     */
+    ownAdvertisements?: Array<{
+        id: string;
+        kind: string;
+        title: string;
+    }>;
+}
+export interface HubEndpoints {
+    mounts: Mounts;
+    /** Expire stale presence and the advertisements that rode along with it; bumps the mesh version only if something actually left. Call on a timer (production) or directly with a controlled clock (tests). */
+    sweep: () => void;
+    /**
+     * The very view `GET /.well-known/mesh` serves, read in-process.
+     *
+     * FOR A UI THAT IS ALREADY INSIDE THE HUB, and for nothing else. The
+     * browser hub page (`../pages/hub/`) renders the member list from this;
+     * going through the HTTP endpoint for it would mean the hub minting
+     * itself a token and dispatching a request to itself, purely so it could
+     * read three registries it is holding two references away. The HTTP
+     * endpoint remains the ONLY way any other peer sees this — this accessor
+     * adds no route, no capability, and no way in from the network.
+     *
+     * IT IS `buildMeshView`, NOT A SECOND OPINION. "Saved" (a member record,
+     * from the persisted snapshot) and "active" (`online`, from the TTL'd
+     * presence store) are two different facts, and `mesh-view.ts` already
+     * computes the second per member. A UI that re-derived `online` by
+     * joining a member list against a presence list would be inventing a
+     * parallel notion that could disagree with the one every remote peer
+     * reads — the exact kind of divergence that turns into a debugging trap.
+     *
+     * THE HUB'S OWN VIEW SEES EVERYTHING: every capability the rules can
+     * derive is passed as the caller's, so `hidden` members and every gated
+     * advertisement are included. There is nobody to hide from — this is the
+     * machine that holds the list, and an operator shown a filtered version
+     * of their own mesh would be misled about what they are administering.
+     *
+     * Live, not a snapshot: a swept peer is `online: false` on the next call,
+     * and a removed member is gone from it, which is what a polling UI wants.
+     */
+    meshView: () => MeshView;
+}
+export declare function createHubEndpoints(init: HubEndpointsInit): HubEndpoints;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../src/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAGV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,SAAS,EAET,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAepC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAwB,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAIrE,qJAAqJ;AACrJ,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,qBAAqB,IAAI,qBAAqB,CAM7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,SAAS,GAAG,YAAY,CAgB5E;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,EAAE,CACT,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;KAAE,KAC1D,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,eAAe,CAAC;IAC7B,6IAA6I;IAC7I,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,0GAA0G;IAC1G,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8MAA8M;IAC9M,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,EAAE,MAAM,QAAQ,CAAC;CAC1B;AA0BD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAuQvE"}