@statewalker/httpeers-member 0.1.4

package/dist/node.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The NODE half of `MemberPlatform` — the counterpart to
+ * `./browser-profile.ts`'s `createBrowserNode`.
+ *
+ * WHAT DIFFERS FROM THE BROWSER PROFILE, AND WHAT DELIBERATELY DOES NOT:
+ *
+ *   - `tcp()` is added. It is the one transport a page cannot have and the
+ *     one a Node member wants, for the direct member-to-member hop a page
+ *     makes over WebRTC instead.
+ *   - The LISTEN ADDRESSES ARE THE SAME — `/p2p-circuit` and `/webrtc`,
+ *     plus a loopback TCP port. If a Node member listened differently it
+ *     would reserve somewhere else, and the rung would be testing a
+ *     different design rather than the same one on another platform.
+ *   - The connection gater is permissive, which the browser profile also
+ *     does for loopback and private addresses (`dialNeedsPermissiveGater`).
+ *     Node has no browser default to relax, so this is the same policy
+ *     arrived at from the other side.
+ *   - There is no `mountEdge`: `MemberHandle.fetch` is the edge under Node.
+ *   - There is no `watchWake`: a Node process gets no wake events, so the
+ *     supervisor's backstop timer is the whole story.
+ */
+import type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+import type { MemberPlatform } from "./start-member.js";
+export declare function createNodeMemberNode(init: {
+    privateKey?: Ed25519PrivateKey;
+}): Promise<Libp2p>;
+/** The whole Node platform: a node factory, and nothing else. */
+export declare const nodePlatform: MemberPlatform;
+//# 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAKnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,GAAG,OAAO,CAAC,MAAM,CAAC,CAUlB;AAED,iEAAiE;AACjE,eAAO,MAAM,YAAY,EAAE,cAAqD,CAAC"}

package/dist/node.js

@@ -0,0 +1,42 @@
+/**
+ * The NODE half of `MemberPlatform` — the counterpart to
+ * `./browser-profile.ts`'s `createBrowserNode`.
+ *
+ * WHAT DIFFERS FROM THE BROWSER PROFILE, AND WHAT DELIBERATELY DOES NOT:
+ *
+ *   - `tcp()` is added. It is the one transport a page cannot have and the
+ *     one a Node member wants, for the direct member-to-member hop a page
+ *     makes over WebRTC instead.
+ *   - The LISTEN ADDRESSES ARE THE SAME — `/p2p-circuit` and `/webrtc`,
+ *     plus a loopback TCP port. If a Node member listened differently it
+ *     would reserve somewhere else, and the rung would be testing a
+ *     different design rather than the same one on another platform.
+ *   - The connection gater is permissive, which the browser profile also
+ *     does for loopback and private addresses (`dialNeedsPermissiveGater`).
+ *     Node has no browser default to relax, so this is the same policy
+ *     arrived at from the other side.
+ *   - There is no `mountEdge`: `MemberHandle.fetch` is the edge under Node.
+ *   - There is no `watchWake`: a Node process gets no wake events, so the
+ *     supervisor's backstop timer is the whole story.
+ */
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { identify } from "@libp2p/identify";
+import { tcp } from "@libp2p/tcp";
+import { webRTC } from "@libp2p/webrtc";
+import { webSockets } from "@libp2p/websockets";
+import { createLibp2p } from "libp2p";
+export async function createNodeMemberNode(init) {
+    return createLibp2p({
+        ...(init.privateKey != null ? { privateKey: init.privateKey } : {}),
+        addresses: { listen: ["/ip4/127.0.0.1/tcp/0", "/p2p-circuit", "/webrtc"] },
+        transports: [webSockets(), circuitRelayTransport(), webRTC(), tcp()],
+        connectionEncrypters: [noise()],
+        streamMuxers: [yamux()],
+        connectionGater: { denyDialMultiaddr: async () => false },
+        services: { identify: identify() },
+    });
+}
+/** The whole Node platform: a node factory, and nothing else. */
+export const nodePlatform = { createNode: createNodeMemberNode };

package/dist/page-wake.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The page events that mean "the relay link may have died while nothing was
+ * watching, and may be reachable again now" -- turned into one callback.
+ */
+/** The parts of `window` this reads. */
+export type WakeWindow = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+/** The parts of `document` this reads. */
+export type WakeDocument = Pick<EventTarget, "addEventListener" | "removeEventListener"> & {
+    readonly visibilityState: string;
+};
+export interface WatchPageWakeInit {
+    win?: WakeWindow;
+    doc?: WakeDocument;
+}
+/**
+ * Call `onWake` whenever the page comes back; returns the unsubscribe.
+ *
+ * Why these events, and not a timer: a suspended page's timers are
+ * throttled or stopped, so the relay supervisor's own backoff may not fire
+ * for minutes after the page is usable again. See
+ * `tests/browser-page-wake.test.ts` for what each event means.
+ */
+export declare function watchPageWake(onWake: () => void, init?: WatchPageWakeInit): () => void;
+//# sourceMappingURL=page-wake.d.ts.map

package/dist/page-wake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-wake.d.ts","sourceRoot":"","sources":["../src/page-wake.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CAAC,CAAC;AAEvF,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CAAC,GAAG;IACzF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAeD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,IAAI,CAmB1F"}

package/dist/page-wake.js

@@ -0,0 +1,31 @@
+/**
+ * The page events that mean "the relay link may have died while nothing was
+ * watching, and may be reachable again now" -- turned into one callback.
+ */
+/**
+ * Call `onWake` whenever the page comes back; returns the unsubscribe.
+ *
+ * Why these events, and not a timer: a suspended page's timers are
+ * throttled or stopped, so the relay supervisor's own backoff may not fire
+ * for minutes after the page is usable again. See
+ * `tests/browser-page-wake.test.ts` for what each event means.
+ */
+export function watchPageWake(onWake, init = {}) {
+    const win = init.win ?? window;
+    const doc = init.doc ?? document;
+    const wake = () => onWake();
+    const onVisibility = () => {
+        if (doc.visibilityState === "visible")
+            onWake();
+    };
+    win.addEventListener("online", wake);
+    win.addEventListener("pageshow", wake);
+    doc.addEventListener("resume", wake);
+    doc.addEventListener("visibilitychange", onVisibility);
+    return () => {
+        win.removeEventListener("online", wake);
+        win.removeEventListener("pageshow", wake);
+        doc.removeEventListener("resume", wake);
+        doc.removeEventListener("visibilitychange", onVisibility);
+    };
+}

package/dist/peer-request.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A `Request` addressed at a mesh path.
+ *
+ * `Peer.call(peerId, request)` takes a whole `Request`, because that is the
+ * contract every other seam in this system speaks — the prototype's peer took
+ * `(peerId, path, init)` instead, which meant it owned a second, narrower idea
+ * of what a call is and could not carry anything a `Request` can (a stream, an
+ * `AbortSignal`, a `Headers` instance a caller already had).
+ *
+ * The origin is a placeholder and is never dialled: the far side routes on the
+ * pathname alone. It is spelled `peer.local` rather than `localhost` so that a
+ * stray log line cannot be mistaken for a loopback request that really went out.
+ */
+export interface PeerRequestInit extends RequestInit {
+    /**
+     * A membership token, placed in `MESH_TOKEN_HEADER` -- never
+     * `Authorization`, which stays the caller's to use for the application it
+     * is calling.
+     *
+     * The prototype's `peer.call` took this as its own option and built the
+     * header internally. Keeping it here rather than making every call site
+     * write the header keeps those sites reading as intent — and keeps ONE
+     * place that decides the scheme, which is what a token's format being
+     * changed later will want.
+     */
+    token?: string;
+}
+export declare function peerRequest(path: string, init?: PeerRequestInit): Request;
+//# sourceMappingURL=peer-request.d.ts.map

package/dist/peer-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-request.d.ts","sourceRoot":"","sources":["../src/peer-request.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAQ7E"}

package/dist/peer-request.js

@@ -0,0 +1,11 @@
+import { setMeshToken } from "@statewalker/httpeers-core";
+export function peerRequest(path, init = {}) {
+    const { token, headers, ...rest } = init;
+    const merged = new Headers(headers);
+    if (token != null)
+        setMeshToken(merged, token);
+    return new Request(`http://peer.local${path.startsWith("/") ? path : `/${path}`}`, {
+        ...rest,
+        headers: merged,
+    });
+}

package/dist/reset.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Getting a stuck origin back to a first visit — and NOTHING ELSE IN IT.
+ *
+ * ITS OWN ENTRY POINT ON PURPOSE. This is what a rescue page loads when the
+ * app will not start, so it must not depend on the app starting. Importing it
+ * through `./browser` would drag in the session, the member lifecycle,
+ * `httpeers-access` and its Biscuit engine, crypto and transport code -- all to
+ * unregister a ServiceWorker. If any of that is what broke, the rescue page
+ * breaks with it.
+ *
+ * This was measured when the engine was WebAssembly: importing
+ * `@statewalker/httpeers-member/browser` failed outright until the wasm loader
+ * was wired. The engine is pure TypeScript now, but the rule stands for every
+ * other reason an app fails to start.
+ *
+ * So: zero imports. Everything here is a platform global.
+ */
+/** What a reset actually removed, so a page can report it rather than guess. */
+export interface ResetResult {
+    /** ServiceWorker registrations unregistered on this origin. */
+    serviceWorkers: number;
+    /** IndexedDB databases deleted, by name. */
+    databases: string[];
+}
+/**
+ * Put this origin back to a first-visit state: no worker, no databases, no
+ * stored values.
+ *
+ * WHY THIS EXISTS AT ALL. A ServiceWorker is the stickiest thing a static site
+ * can install, and the obvious remedies do not work — measured in a real
+ * browser, not inferred:
+ *
+ *   - **A reload does not remove one.** Registration is durable state on the
+ *     ORIGIN, independent of any page's lifetime.
+ *   - **`unregister()` does not evict the worker already controlling this
+ *     page.** It removes the registration; the active worker keeps serving
+ *     open clients until they are unloaded. So a reset control that reports
+ *     success without reloading is still being served by the thing it says it
+ *     removed. **Reload after calling this.**
+ *   - **Unregistering alone is a half-reset.** The identity that makes a page
+ *     "the same peer" is in IndexedDB. Clear only the worker and the page
+ *     comes back as the same member, which is exactly the outcome people
+ *     report as "it did not work".
+ *
+ * EVERYTHING ON THE ORIGIN, NOT A LIST OF NAMES. The state spans idb-keyval's
+ * store (identity, remembered mesh), the hub's database, the libp2p key store,
+ * the ServiceWorker adapter's claimed-keys table and `localStorage` — five
+ * places across three packages today. A hand-maintained list would go stale
+ * the first time one moved, silently, leaving the half-reset above. An origin
+ * here belongs to one app, so "all of it" is both simpler and correct.
+ *
+ * NEVER THROWS. It runs on a rescue page that must work when everything else
+ * is broken, including on a first visit with nothing to remove.
+ */
+export declare function resetBrowserState(): Promise<ResetResult>;
+//# sourceMappingURL=reset.d.ts.map

package/dist/reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../src/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAoBH,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,CAoD9D"}

package/dist/reset.js

@@ -0,0 +1,103 @@
+/**
+ * Getting a stuck origin back to a first visit — and NOTHING ELSE IN IT.
+ *
+ * ITS OWN ENTRY POINT ON PURPOSE. This is what a rescue page loads when the
+ * app will not start, so it must not depend on the app starting. Importing it
+ * through `./browser` would drag in the session, the member lifecycle,
+ * `httpeers-access` and its Biscuit engine, crypto and transport code -- all to
+ * unregister a ServiceWorker. If any of that is what broke, the rescue page
+ * breaks with it.
+ *
+ * This was measured when the engine was WebAssembly: importing
+ * `@statewalker/httpeers-member/browser` failed outright until the wasm loader
+ * was wired. The engine is pure TypeScript now, but the rule stands for every
+ * other reason an app fails to start.
+ *
+ * So: zero imports. Everything here is a platform global.
+ */
+/**
+ * Put this origin back to a first-visit state: no worker, no databases, no
+ * stored values.
+ *
+ * WHY THIS EXISTS AT ALL. A ServiceWorker is the stickiest thing a static site
+ * can install, and the obvious remedies do not work — measured in a real
+ * browser, not inferred:
+ *
+ *   - **A reload does not remove one.** Registration is durable state on the
+ *     ORIGIN, independent of any page's lifetime.
+ *   - **`unregister()` does not evict the worker already controlling this
+ *     page.** It removes the registration; the active worker keeps serving
+ *     open clients until they are unloaded. So a reset control that reports
+ *     success without reloading is still being served by the thing it says it
+ *     removed. **Reload after calling this.**
+ *   - **Unregistering alone is a half-reset.** The identity that makes a page
+ *     "the same peer" is in IndexedDB. Clear only the worker and the page
+ *     comes back as the same member, which is exactly the outcome people
+ *     report as "it did not work".
+ *
+ * EVERYTHING ON THE ORIGIN, NOT A LIST OF NAMES. The state spans idb-keyval's
+ * store (identity, remembered mesh), the hub's database, the libp2p key store,
+ * the ServiceWorker adapter's claimed-keys table and `localStorage` — five
+ * places across three packages today. A hand-maintained list would go stale
+ * the first time one moved, silently, leaving the half-reset above. An origin
+ * here belongs to one app, so "all of it" is both simpler and correct.
+ *
+ * NEVER THROWS. It runs on a rescue page that must work when everything else
+ * is broken, including on a first visit with nothing to remove.
+ */
+export async function resetBrowserState() {
+    let serviceWorkers = 0;
+    try {
+        const registrations = (await navigator.serviceWorker?.getRegistrations()) ?? [];
+        for (const registration of registrations) {
+            try {
+                await registration.unregister();
+                serviceWorkers += 1;
+            }
+            catch {
+                /* one that refuses must not stop the rest */
+            }
+        }
+    }
+    catch {
+        /* no ServiceWorker support, or an insecure context */
+    }
+    const databases = [];
+    try {
+        // `indexedDB.databases()` is unsupported in Firefox, where enumeration is
+        // impossible and this half is a no-op. The worker and the stores below are
+        // still cleared, so a reset there is partial rather than absent -- worth
+        // knowing, and better than refusing to run.
+        const found = (await indexedDB.databases?.()) ?? [];
+        for (const { name } of found) {
+            if (name == null || name === "")
+                continue;
+            await new Promise((resolve) => {
+                const request = indexedDB.deleteDatabase(name);
+                request.onsuccess = () => resolve();
+                request.onerror = () => resolve();
+                // A database still open in another tab blocks. Resolving anyway keeps
+                // the reset moving; the page reload that follows closes this tab's
+                // handle, and the delete completes then.
+                request.onblocked = () => resolve();
+            });
+            databases.push(name);
+        }
+    }
+    catch {
+        /* enumeration unsupported */
+    }
+    try {
+        localStorage?.clear();
+    }
+    catch {
+        /* blocked site data */
+    }
+    try {
+        sessionStorage?.clear();
+    }
+    catch {
+        /* blocked site data */
+    }
+    return { serviceWorkers, databases };
+}

package/dist/session.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The page session: one persistent identity, resume-or-redeem on start, and
+ * the three operator controls -- join, disconnect, reset identity -- with
+ * no DOM anywhere in it.
+ *
+ * WHY EVERY CONSUMER PAGE SHARES THIS. Two pages differ in exactly one
+ * thing: what they mount and advertise. Everything else -- read the saved
+ * identity, try to resume, say which of the two "cannot resume" situations
+ * this is, offer an invitation field, disconnect without surrendering
+ * membership, reset the key -- is identical between them, down to the
+ * wording, and duplicating it would have been duplicating the wording too.
+ *
+ * NO DOM, AND NOTHING BROWSER-ONLY IMPORTED. This module decides things --
+ * which mesh to try, resume or redeem, what an operator is told -- and
+ * deciding is exactly what is worth testing, so `tests/session.test.ts`
+ * exercises every branch under Node with no browser, no relay and no
+ * ServiceWorker. That is only possible because the platform, the two stores
+ * and the reload are INJECTED rather than defaulted: `browserPlatform`
+ * reaches `@libp2p/webrtc`, whose Node build loads a native module, so a
+ * default here would have made importing this module a browser-only act.
+ * `./browser.ts`'s `createSession` is where those defaults live instead.
+ *
+ * Pages render `SessionState` and call the four methods; they hold no state
+ * of their own.
+ *
+ * THE CONFIG IS RESOLVED HERE, because `startMember` requires one and will
+ * not fetch anything itself (see `StartMemberInit.config`). That moved the
+ * `httpeers.json` read up into this module, which is the only place that
+ * knows which of the three candidates -- a blob's mesh, the remembered one,
+ * the deployment's -- applies to the attempt at hand.
+ *
+ * WHICH MESH IS TRIED, AND THE ONE RULE THAT MUST NOT BEND. When someone
+ * supplies an invitation, the invitation decides: a join blob names its own
+ * mesh, and a BARE invitation id still means "the mesh `httpeers.json`
+ * names", i.e. the Node hub's -- the contract `./join-blob.ts` states and
+ * the reason both deployments keep working. Only a RESUME (nobody supplied
+ * anything) consults `./mesh-memory.ts`, and only because a mesh whose hub
+ * is a browser page cannot be named any other way after the `?join=` query
+ * has gone. See `./mesh-memory.ts`.
+ *
+ * DISCONNECT IS NOT LEAVING. `MemberHandle.stop()` drops presence and
+ * keeps membership, which is what makes the page resumable afterwards with
+ * no new invitation; see that method's own doc comment. This module never
+ * calls anything that surrenders membership, and the one control that
+ * destroys something -- `resetIdentity` -- says what it costs and is named
+ * separately.
+ */
+import type { Ed25519PrivateKey } from "@libp2p/interface";
+import type { RuleSet } from "@statewalker/httpeers-access";
+import type { MeshConfig as HttpeersConfig, Mounts } from "@statewalker/httpeers-core";
+import type { IdentityStoreInit } from "./identity.js";
+import type { AdvertisementInput } from "./join.js";
+import type { MeshMemory } from "./mesh-memory.js";
+import type { HubLink, JoinMethod, MemberHandle, MemberPlatform, MemberState, StartMemberInit } from "./start-member.js";
+/** Why this page is asking for an invitation. The two that matter are the first two -- see `SessionPhase`. */
+export type NeedsInvitationReason = 
+/** This browser has never held an identity for this origin: a genuine first run. */
+"no-identity"
+/** This browser holds an identity, the hub was reachable, and it does not know it. */
+ | "unknown-identity"
+/** An invitation was supplied and the hub refused it (spent, expired, unknown). */
+ | "invitation-refused"
+/** Nothing was supplied and nothing is remembered, so there is no mesh to even try. */
+ | "no-mesh";
+/**
+ * Where the session is. Every one of these is a distinct thing to say on
+ * screen, which is the only reason there are six.
+ *
+ * `needs-invitation` CARRIES ITS REASON because "no saved identity yet" and
+ * "saved identity, but this hub does not know it" are not the same
+ * situation and must not read the same (Task 28, requirement 3). The first
+ * is a page that has never run; the second is a hub reset or a revoked
+ * membership, and an operator told only "please paste an invitation" would
+ * have no way to tell which had happened -- or that their saved identity is
+ * intact and simply unrecognised.
+ *
+ * `blocked` is the duplicate-identity refusal, kept apart from `failed`
+ * because it is not a fault to retry: two tabs are running one libp2p
+ * identity, and something has to give before this page can proceed.
+ */
+/**
+ * What `starting` reports.
+ *
+ * `"loading-config"` is the SESSION'S OWN step, not the member's: resolving
+ * which mesh to try can mean an `httpeers.json` fetch, which is the one part
+ * of a start that happens before `startMember` exists to have a state. Every
+ * other value is `MemberState` verbatim, forwarded.
+ */
+export type SessionStartState = "loading-config" | MemberState;
+export type SessionPhase = {
+    kind: "checking";
+} | {
+    kind: "starting";
+    peerState: SessionStartState;
+} | {
+    kind: "live";
+    joinedBy: JoinMethod;
+    note: string | null;
+} | {
+    kind: "needs-invitation";
+    reason: NeedsInvitationReason;
+    message: string;
+} | {
+    kind: "disconnected";
+    message: string;
+} | {
+    kind: "blocked";
+    message: string;
+} | {
+    kind: "failed";
+    message: string;
+};
+/** Which controls make sense in the current phase. Derived here, once, rather than by each page re-deriving it from `phase.kind`. */
+export interface SessionControls {
+    join: boolean;
+    disconnect: boolean;
+    reconnect: boolean;
+    reset: boolean;
+}
+export interface SessionState {
+    phase: SessionPhase;
+    /** The peerId this origin holds, or `null` when it has never had one. Known before anything is dialled. */
+    identity: string | null;
+    /** Live only while `phase.kind === "live"`. */
+    handle: MemberHandle | null;
+    /** How the live member reaches its hub (`MemberHandle.hubLink`, fixed for the member's run); `null` unless live. */
+    hubLink: HubLink | null;
+    controls: SessionControls;
+}
+/** `startMember`'s shape, as a seam -- see the module comment. */
+export type StartPeer = (init: StartMemberInit) => Promise<MemberHandle>;
+/** The identity store's three operations, as a seam. Defaults to `./identity.ts` over the real IndexedDB. */
+export interface IdentityStore {
+    read(): Promise<Ed25519PrivateKey | null>;
+    loadOrCreate(): Promise<Ed25519PrivateKey>;
+    clear(): Promise<void>;
+}
+export declare function createIdentityStore(init: IdentityStoreInit): IdentityStore;
+export interface PeerSessionInit {
+    /** Everything `startMember` needs that is this PAGE's own, and nothing that is the session's. */
+    key: string;
+    mounts: Mounts;
+    /** This page's own rule set, already built -- see `StartMemberInit.rules`. */
+    rules: RuleSet;
+    advertisements?: () => AdvertisementInput[];
+    /**
+     * How this host builds a node, mounts an edge and hears about wakes.
+     * REQUIRED, and deliberately: see the module comment on why a default
+     * would make importing this module browser-only.
+     */
+    platform: MemberPlatform;
+    /** This page's `location.search`, read once at `start()`. */
+    search: string;
+    /** Fired on every state change, including the first. */
+    onChange: (state: SessionState) => void;
+    /** Where this origin's key lives. Required for the same reason `./mesh-memory.ts`'s backend is. */
+    identity: IdentityStore;
+    /** The mesh this origin last joined. Required for the same reason. */
+    meshMemory: MeshMemory;
+    /**
+     * Reloading the host after a reset. REQUIRED because `location` is the one
+     * DOM global this module would otherwise have to name; `./browser.ts`
+     * supplies it.
+     */
+    reload: () => void;
+    startPeer?: StartPeer;
+    /**
+     * The mesh this DEPLOYMENT names (`httpeers.json`).
+     *
+     * READ FOR TWO REASONS. It is the fallback mesh -- what a bare invitation
+     * id means, and what a page with an identity but no remembered mesh tries.
+     * And it explains a failure: when a page cannot resume against the mesh it
+     * REMEMBERS and the deployment now names a different hub, that is almost
+     * always a re-run of `pnpm bootstrap` (or a switch between the Node hub and
+     * a hub page), and saying so is the difference between a two-minute fix and
+     * an hour.
+     */
+    readDeploymentConfig?: () => Promise<HttpeersConfig | null>;
+}
+export interface PeerSession {
+    /** Read the saved identity and try to resume. Call once, on page load. */
+    start(): Promise<void>;
+    /** Join with what someone typed or pasted: a blob, a bare invitation id, or a whole join link. */
+    join(text: string): Promise<void>;
+    /** Stop this peer: drop presence, KEEP membership -- see `MemberHandle.stop`. */
+    disconnect(): Promise<void>;
+    /** Come back after a `disconnect`, by resuming. No invitation involved. */
+    reconnect(): Promise<void>;
+    /** Forget this origin's key, so the next run is a different peer. Destructive -- see below. */
+    resetIdentity(): Promise<void>;
+    state(): SessionState;
+}
+/**
+ * Where a deployment publishes the mesh it names.
+ *
+ * A SITE-ABSOLUTE PATH, so every page of an origin reads the same file
+ * whatever directory it was served from. It left with `peer-runtime.ts` and
+ * is declared here because this module is now the only thing that reads it.
+ */
+export declare const DEFAULT_HTTPEERS_CONFIG_URL = "/httpeers.json";
+/**
+ * The sentence added to a "this hub does not know you" message when the
+ * deployment has visibly moved underneath the page.
+ *
+ * THE CASE THIS EXISTS FOR: `pnpm bootstrap` was re-run, so `httpeers.json`
+ * now names a hub with a different peerId than the one this page last
+ * joined. Everything about the page is fine, the hub it is talking to is
+ * fine, and the membership is simply in a mesh that no longer exists. With
+ * nothing said, that presents as "please paste an invitation" for reasons
+ * an operator cannot see. Exported for its own test.
+ */
+export declare function describeMeshDrift(tried: string, deployment: HttpeersConfig | null): string | null;
+export declare function createPeerSession(init: PeerSessionInit): PeerSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}