@statewalker/httpeers-libp2p 0.1.3

package/dist/hub-relay.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The hub as a relay for its own members — signalling only, members only.
+ *
+ * WHY A HUB RELAYS AT ALL. Members reach each other through their hub rather
+ * than through the public relay: the hub is the one peer every member is
+ * already connected to and heartbeating against, so it can carry the few
+ * kilobytes of WebRTC offer/answer between two members, after which they talk
+ * directly. The public relay is then needed only to reach the hub itself.
+ *
+ * MEMBERS ONLY. `membershipGater` refuses a reservation from a non-member and
+ * refuses to relay unless BOTH ends are members. A non-member can still
+ * *connect* to a hub — it must, to redeem an invitation — it simply cannot use
+ * the hub to reach anyone else. The public relay, by contrast, connects anyone
+ * to any reserved peer whose id they know.
+ *
+ * SIGNALLING ONLY, ENFORCED RATHER THAN HOPED FOR. `hubRelayService` keeps
+ * libp2p's default per-circuit limits (128 KiB, 2 min), sized for an SDP
+ * exchange. A circuit carrying limits is a LIMITED connection, and libp2p
+ * refuses to open an application protocol on one — so application data cannot
+ * cross a hub by accident. When two members cannot connect directly, WebRTC
+ * falls back to TURN, never to the hub.
+ *
+ * Opening a protocol with `runOnLimitedConnection` would bypass that, and the
+ * prototype measured the result: a 1 MiB transfer silently cut at 112 KiB.
+ * **Nothing may set it for application traffic.**
+ *
+ * HOW MANY, AND FOR HOW LONG -- a different question from how much. The data
+ * limits above bound what one CIRCUIT may carry. The reservation store bounds
+ * how many members may be REACHABLE through the hub at once, and libp2p's
+ * default for it (15, each held for two hours, kept after its holder hangs
+ * up) is sized for a public relay, not for a hub. A hub on that default
+ * filled after fifteen distinct peers in two hours -- test runs, revoked
+ * members, a member whose page was reopened -- and then refused every member
+ * with `RESERVATION_REFUSED`, which a member reports as a failed join. So:
+ *
+ *   - the store is sized for a mesh (`HUB_MAX_RESERVATIONS`), which is safe
+ *     because only members can take a slot;
+ *   - a reservation is released when its holder's last connection closes
+ *     (it is useless from then on: libp2p relays only to a CONNECTED
+ *     reservation holder, and a member re-reserves when it comes back);
+ *   - `releaseReservation` lets the hub release a REVOKED member's
+ *     reservation at once, rather than leave the slot held until expiry.
+ */
+import { type CircuitRelayServerComponents, type CircuitRelayService } from "@libp2p/circuit-relay-v2";
+import type { ConnectionGater, Libp2pEvents, PeerId, TypedEventTarget } from "@libp2p/interface";
+import type { PeerIdStr } from "@statewalker/httpeers-core";
+/** Is this peer a member of our mesh? Read LIVE — see `membershipGater`. */
+export type IsMember = (peerId: PeerIdStr) => boolean;
+/**
+ * A gater that admits only members to the relay.
+ *
+ * TAKES A THUNK, and that is not a style preference — it breaks a genuine
+ * ordering cycle. The gater is needed to CREATE the node; the answer to "is
+ * this peer a member" comes from the hub's member store; and the hub cannot be
+ * built until the node exists. Passing `isMember` directly forces a caller to
+ * resolve that cycle themselves, and the prototype's two profiles each did it
+ * differently.
+ *
+ * A thunk defers the lookup to the moment a decision is actually needed, by
+ * which time the hub exists. It also means a revocation takes effect on the
+ * next relay request rather than at the next restart, because nothing is
+ * captured.
+ */
+export declare function membershipGater(isMember: () => IsMember): ConnectionGater;
+/**
+ * How many members may hold a reservation on a hub at once: one per member
+ * currently connected to it.
+ *
+ * WHY THIS NUMBER. It is a ceiling, not an allocation -- an empty slot costs
+ * nothing, and a held one is a map entry of a few hundred bytes, so 4096 of
+ * them is about a megabyte. Only members can take a slot (`membershipGater`),
+ * and a slot is given back when its holder disconnects, so what this really
+ * bounds is simultaneously connected members; a hub serving thousands of
+ * members at once has other limits to meet first (libp2p's connection
+ * manager, the hub's own CPU). libp2p's default, 15, is sized for a public
+ * relay that anyone can fill, and is the value that broke a real hub.
+ *
+ * NOT RAISED TO "UNLIMITED", because the gater is the only thing between a
+ * large member list and this map; a finite ceiling keeps a runaway (a bug
+ * that mints members, say) from growing it without bound.
+ */
+export declare const HUB_MAX_RESERVATIONS = 4096;
+export interface HubRelayServiceInit {
+    /**
+     * The reservation store's size (default `HUB_MAX_RESERVATIONS`). How MANY
+     * members can be reached through the hub -- not how much data may cross it,
+     * which stays at libp2p's signalling-sized default whatever this is.
+     */
+    maxReservations?: number;
+}
+/**
+ * What the hub relay needs from the node: the relay server's own components,
+ * plus the node's event bus, to hear a holder hang up. Both are standard
+ * libp2p components; `createLibp2p` hands every service all of them.
+ */
+export type HubRelayComponents = CircuitRelayServerComponents & {
+    events: TypedEventTarget<Libp2pEvents>;
+};
+/**
+ * The circuit-relay server a hub runs for its members.
+ *
+ * The default DATA limits are stated explicitly rather than left implicit, so
+ * that nobody raises them to "make it smoother": they are the thing that keeps
+ * a hub a signalling channel instead of a data path. The store's SIZE is a
+ * separate setting (`init.maxReservations`) and changes none of that.
+ *
+ * RELEASES ON DISCONNECT. libp2p keeps a reservation for its full TTL after
+ * the holder is gone. This listens for `peer:disconnect` -- which libp2p
+ * fires when a peer's LAST connection closes -- and releases the reservation
+ * then, rechecking that no connection came back in the meantime.
+ */
+export declare function hubRelayService(init?: HubRelayServiceInit): (components: HubRelayComponents) => CircuitRelayService;
+/**
+ * Release a peer's reservation on this hub's relay, now. Returns whether there
+ * was one. The daemon calls it when it revokes a member; the membership gater
+ * already refuses that peer a NEW reservation, and this frees the one it held.
+ *
+ * THROUGH THE SERVICE'S PUBLIC SURFACE. libp2p offers no "remove reservation"
+ * call, but `CircuitRelayService.reservations` is a public map and each entry
+ * carries its expiry `signal`. Clearing that signal before removing the entry
+ * matters: the store's own expiry listener deletes by PEER, so a timer left
+ * running would, two hours later, delete whatever reservation the same peer
+ * holds by then.
+ *
+ * A STRING THAT IS NOT A PEER ID holds no reservation, so it returns false
+ * rather than throwing: a revocation must not fail half-way over it.
+ */
+export declare function releaseReservation(relay: Pick<CircuitRelayService, "reservations">, peer: PeerId | PeerIdStr): boolean;
+//# sourceMappingURL=hub-relay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hub-relay.d.ts","sourceRoot":"","sources":["../src/hub-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EAEzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,QAAQ,GAAG,eAAe,CAUzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,4BAA4B,GAAG;IAC9D,MAAM,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,mBAAwB,GAC7B,CAAC,UAAU,EAAE,kBAAkB,KAAK,mBAAmB,CAgBzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,EAChD,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAQT"}

package/dist/hub-relay.js

@@ -0,0 +1,154 @@
+/**
+ * The hub as a relay for its own members — signalling only, members only.
+ *
+ * WHY A HUB RELAYS AT ALL. Members reach each other through their hub rather
+ * than through the public relay: the hub is the one peer every member is
+ * already connected to and heartbeating against, so it can carry the few
+ * kilobytes of WebRTC offer/answer between two members, after which they talk
+ * directly. The public relay is then needed only to reach the hub itself.
+ *
+ * MEMBERS ONLY. `membershipGater` refuses a reservation from a non-member and
+ * refuses to relay unless BOTH ends are members. A non-member can still
+ * *connect* to a hub — it must, to redeem an invitation — it simply cannot use
+ * the hub to reach anyone else. The public relay, by contrast, connects anyone
+ * to any reserved peer whose id they know.
+ *
+ * SIGNALLING ONLY, ENFORCED RATHER THAN HOPED FOR. `hubRelayService` keeps
+ * libp2p's default per-circuit limits (128 KiB, 2 min), sized for an SDP
+ * exchange. A circuit carrying limits is a LIMITED connection, and libp2p
+ * refuses to open an application protocol on one — so application data cannot
+ * cross a hub by accident. When two members cannot connect directly, WebRTC
+ * falls back to TURN, never to the hub.
+ *
+ * Opening a protocol with `runOnLimitedConnection` would bypass that, and the
+ * prototype measured the result: a 1 MiB transfer silently cut at 112 KiB.
+ * **Nothing may set it for application traffic.**
+ *
+ * HOW MANY, AND FOR HOW LONG -- a different question from how much. The data
+ * limits above bound what one CIRCUIT may carry. The reservation store bounds
+ * how many members may be REACHABLE through the hub at once, and libp2p's
+ * default for it (15, each held for two hours, kept after its holder hangs
+ * up) is sized for a public relay, not for a hub. A hub on that default
+ * filled after fifteen distinct peers in two hours -- test runs, revoked
+ * members, a member whose page was reopened -- and then refused every member
+ * with `RESERVATION_REFUSED`, which a member reports as a failed join. So:
+ *
+ *   - the store is sized for a mesh (`HUB_MAX_RESERVATIONS`), which is safe
+ *     because only members can take a slot;
+ *   - a reservation is released when its holder's last connection closes
+ *     (it is useless from then on: libp2p relays only to a CONNECTED
+ *     reservation holder, and a member re-reserves when it comes back);
+ *   - `releaseReservation` lets the hub release a REVOKED member's
+ *     reservation at once, rather than leave the slot held until expiry.
+ */
+import { circuitRelayServer, } from "@libp2p/circuit-relay-v2";
+import { peerIdFromString } from "@libp2p/peer-id";
+/**
+ * A gater that admits only members to the relay.
+ *
+ * TAKES A THUNK, and that is not a style preference — it breaks a genuine
+ * ordering cycle. The gater is needed to CREATE the node; the answer to "is
+ * this peer a member" comes from the hub's member store; and the hub cannot be
+ * built until the node exists. Passing `isMember` directly forces a caller to
+ * resolve that cycle themselves, and the prototype's two profiles each did it
+ * differently.
+ *
+ * A thunk defers the lookup to the moment a decision is actually needed, by
+ * which time the hub exists. It also means a revocation takes effect on the
+ * next relay request rather than at the next restart, because nothing is
+ * captured.
+ */
+export function membershipGater(isMember) {
+    return {
+        denyInboundRelayReservation: async (source) => !isMember()(source.toString()),
+        denyOutboundRelayedConnection: async (source, destination) => {
+            const member = isMember();
+            // BOTH ends. A member must not be able to use the hub to reach a
+            // stranger any more than a stranger may use it to reach a member.
+            return !member(source.toString()) || !member(destination.toString());
+        },
+    };
+}
+/**
+ * How many members may hold a reservation on a hub at once: one per member
+ * currently connected to it.
+ *
+ * WHY THIS NUMBER. It is a ceiling, not an allocation -- an empty slot costs
+ * nothing, and a held one is a map entry of a few hundred bytes, so 4096 of
+ * them is about a megabyte. Only members can take a slot (`membershipGater`),
+ * and a slot is given back when its holder disconnects, so what this really
+ * bounds is simultaneously connected members; a hub serving thousands of
+ * members at once has other limits to meet first (libp2p's connection
+ * manager, the hub's own CPU). libp2p's default, 15, is sized for a public
+ * relay that anyone can fill, and is the value that broke a real hub.
+ *
+ * NOT RAISED TO "UNLIMITED", because the gater is the only thing between a
+ * large member list and this map; a finite ceiling keeps a runaway (a bug
+ * that mints members, say) from growing it without bound.
+ */
+export const HUB_MAX_RESERVATIONS = 4096;
+/**
+ * The circuit-relay server a hub runs for its members.
+ *
+ * The default DATA limits are stated explicitly rather than left implicit, so
+ * that nobody raises them to "make it smoother": they are the thing that keeps
+ * a hub a signalling channel instead of a data path. The store's SIZE is a
+ * separate setting (`init.maxReservations`) and changes none of that.
+ *
+ * RELEASES ON DISCONNECT. libp2p keeps a reservation for its full TTL after
+ * the holder is gone. This listens for `peer:disconnect` -- which libp2p
+ * fires when a peer's LAST connection closes -- and releases the reservation
+ * then, rechecking that no connection came back in the meantime.
+ */
+export function hubRelayService(init = {}) {
+    const createServer = circuitRelayServer({
+        reservations: {
+            applyDefaultLimit: true,
+            maxReservations: init.maxReservations ?? HUB_MAX_RESERVATIONS,
+        },
+    });
+    return (components) => {
+        const relay = createServer(components);
+        components.events.addEventListener("peer:disconnect", (event) => {
+            const peer = event.detail;
+            if (components.connectionManager.getConnections(peer).length > 0)
+                return;
+            releaseReservation(relay, peer);
+        });
+        return relay;
+    };
+}
+/**
+ * Release a peer's reservation on this hub's relay, now. Returns whether there
+ * was one. The daemon calls it when it revokes a member; the membership gater
+ * already refuses that peer a NEW reservation, and this frees the one it held.
+ *
+ * THROUGH THE SERVICE'S PUBLIC SURFACE. libp2p offers no "remove reservation"
+ * call, but `CircuitRelayService.reservations` is a public map and each entry
+ * carries its expiry `signal`. Clearing that signal before removing the entry
+ * matters: the store's own expiry listener deletes by PEER, so a timer left
+ * running would, two hours later, delete whatever reservation the same peer
+ * holds by then.
+ *
+ * A STRING THAT IS NOT A PEER ID holds no reservation, so it returns false
+ * rather than throwing: a revocation must not fail half-way over it.
+ */
+export function releaseReservation(relay, peer) {
+    const peerId = typeof peer === "string" ? parsePeerId(peer) : peer;
+    if (peerId == null)
+        return false;
+    const reservation = relay.reservations.get(peerId);
+    if (reservation == null)
+        return false;
+    reservation.signal.clear();
+    relay.reservations.delete(peerId);
+    return true;
+}
+function parsePeerId(peer) {
+    try {
+        return peerIdFromString(peer);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Identity, before a node exists.
+ *
+ * WHY THIS IS ITS OWN MODULE. Every process and every page in the mesh needs a
+ * peerId *before* it can start a node: a hub's peerId is the mesh identity that
+ * every token's `mesh` claim restates, a relay's is baked into the multiaddr
+ * its members dial, and a member's is what the hub records. The prototype's
+ * three assemblies each derived one their own way, and revision 1 of the
+ * extraction exported none of it.
+ *
+ * ED25519 ONLY, and never branching on key type. The reason is the one
+ * `httpeers-access` is built on: an Ed25519 peerId inlines its own public key,
+ * so verification never needs a fetch. A key of any other type would produce a
+ * peerId that cannot self-certify, and every token issued under it would be
+ * unverifiable — so `decodeKey` refuses one rather than carrying it forward.
+ *
+ * IDEMPOTENCE IS THE WHOLE POINT of `identityStore`. A store that quietly
+ * re-generated a key on a second read would silently re-found the mesh: every
+ * token already issued stops verifying, every policy naming the issuer goes
+ * stale, and nothing reports an error. There is no path in `loadOrCreate` that
+ * writes when a key is already present.
+ */
+import type { Ed25519PrivateKey, Ed25519PublicKey } from "@libp2p/interface";
+import type { PeerIdStr } from "@statewalker/httpeers-core";
+export interface GenerateKeyInit {
+    /**
+     * Derive the key deterministically instead of drawing from the CSPRNG, so a
+     * test or a CI run can name a peerId as a constant. Exactly 32 bytes.
+     */
+    seed?: Uint8Array;
+}
+export declare function generateKey(init?: GenerateKeyInit): Promise<Ed25519PrivateKey>;
+/** The peerId a key identifies as — the mesh id, for a hub's key. */
+export declare function peerIdOf(key: Ed25519PrivateKey | Ed25519PublicKey): PeerIdStr;
+/**
+ * The libp2p protobuf encoding — the format both platforms already persist and
+ * the relay already reads back. Not a format chosen here; see the prototype's
+ * `setup/keys.ts` for the contract it exists to satisfy.
+ */
+export declare function encodeKey(key: Ed25519PrivateKey): Uint8Array;
+/** Decode a stored key, refusing anything that is not Ed25519 **and saying what it was**. */
+export declare function decodeKey(bytes: Uint8Array): Ed25519PrivateKey;
+/**
+ * The bridge to `@statewalker/httpeers-access`.
+ *
+ * Declared STRUCTURALLY rather than imported, so this package does not depend
+ * on `httpeers-access` — the dependency graph runs core → access and
+ * core → libp2p, and the two never point at each other. The shape is
+ * `access`'s `Signer`, and a mismatch would be a compile error at whichever
+ * assembly wires them together, which is where it belongs.
+ */
+export interface SignerLike {
+    readonly mesh: string;
+    readonly seed: Uint8Array;
+}
+/**
+ * A key, as something that can mint.
+ *
+ * A libp2p Ed25519 private key's `raw` is the 64-byte expanded form — the
+ * 32-byte seed followed by the public key — and Biscuit signs from the seed
+ * alone.
+ */
+export declare function signerOf(key: Ed25519PrivateKey): SignerLike;
+/** Somewhere bytes live. A file on a server, IndexedDB in a page. */
+export interface BytesStore {
+    get(key: string): Promise<Uint8Array | undefined>;
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface IdentityStoreInit {
+    backend: BytesStore;
+    /** Which entry in the backend holds it. Defaults to `"identity"`. */
+    key?: string;
+}
+export interface IdentityStore {
+    /** The stored key, or `null`. Never generates. */
+    read(): Promise<Ed25519PrivateKey | null>;
+    /** The stored key, generating and persisting one only if there is none. */
+    loadOrCreate(): Promise<Ed25519PrivateKey>;
+    /** Forget it. The next `loadOrCreate` founds a NEW identity — see the module comment. */
+    clear(): Promise<void>;
+}
+export declare function identityStore(init: IdentityStoreInit): IdentityStore;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAK5D,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,wBAAsB,WAAW,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CASxF;AAED,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU,CAE5D;AAED,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,CAS9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU,CAE3D;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,CAAC;IACpB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC3C,yFAAyF;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAwBpE"}

package/dist/identity.js

@@ -0,0 +1,91 @@
+/**
+ * Identity, before a node exists.
+ *
+ * WHY THIS IS ITS OWN MODULE. Every process and every page in the mesh needs a
+ * peerId *before* it can start a node: a hub's peerId is the mesh identity that
+ * every token's `mesh` claim restates, a relay's is baked into the multiaddr
+ * its members dial, and a member's is what the hub records. The prototype's
+ * three assemblies each derived one their own way, and revision 1 of the
+ * extraction exported none of it.
+ *
+ * ED25519 ONLY, and never branching on key type. The reason is the one
+ * `httpeers-access` is built on: an Ed25519 peerId inlines its own public key,
+ * so verification never needs a fetch. A key of any other type would produce a
+ * peerId that cannot self-certify, and every token issued under it would be
+ * unverifiable — so `decodeKey` refuses one rather than carrying it forward.
+ *
+ * IDEMPOTENCE IS THE WHOLE POINT of `identityStore`. A store that quietly
+ * re-generated a key on a second read would silently re-found the mesh: every
+ * token already issued stops verifying, every policy naming the issuer goes
+ * stale, and nothing reports an error. There is no path in `loadOrCreate` that
+ * writes when a key is already present.
+ */
+import { generateKeyPair, generateKeyPairFromSeed, privateKeyFromProtobuf, privateKeyToProtobuf, } from "@libp2p/crypto/keys";
+import { peerIdFromPrivateKey, peerIdFromPublicKey } from "@libp2p/peer-id";
+/** `generateKeyPairFromSeed("Ed25519", seed)` requires exactly this many bytes. */
+const SEED_BYTES = 32;
+export async function generateKey(init = {}) {
+    if (init.seed === undefined)
+        return generateKeyPair("Ed25519");
+    if (init.seed.length !== SEED_BYTES) {
+        throw new TypeError(`generateKey: a seed must be exactly ${SEED_BYTES} bytes, got ${init.seed.length}. ` +
+            "Hash a passphrase to 32 bytes rather than passing it directly.");
+    }
+    return generateKeyPairFromSeed("Ed25519", init.seed);
+}
+/** The peerId a key identifies as — the mesh id, for a hub's key. */
+export function peerIdOf(key) {
+    return key.type === "Ed25519" && "publicKey" in key
+        ? peerIdFromPrivateKey(key).toString()
+        : peerIdFromPublicKey(key).toString();
+}
+/**
+ * The libp2p protobuf encoding — the format both platforms already persist and
+ * the relay already reads back. Not a format chosen here; see the prototype's
+ * `setup/keys.ts` for the contract it exists to satisfy.
+ */
+export function encodeKey(key) {
+    return privateKeyToProtobuf(key);
+}
+/** Decode a stored key, refusing anything that is not Ed25519 **and saying what it was**. */
+export function decodeKey(bytes) {
+    const key = privateKeyFromProtobuf(bytes);
+    if (key.type !== "Ed25519") {
+        throw new TypeError(`decodeKey: expected an Ed25519 key, got ${key.type}. Only Ed25519 peerIds carry their ` +
+            "own public key, which is what lets a token be verified without fetching anything.");
+    }
+    return key;
+}
+/**
+ * A key, as something that can mint.
+ *
+ * A libp2p Ed25519 private key's `raw` is the 64-byte expanded form — the
+ * 32-byte seed followed by the public key — and Biscuit signs from the seed
+ * alone.
+ */
+export function signerOf(key) {
+    return { mesh: peerIdOf(key), seed: key.raw.slice(0, SEED_BYTES) };
+}
+export function identityStore(init) {
+    const entry = init.key ?? "identity";
+    const read = async () => {
+        const bytes = await init.backend.get(entry);
+        return bytes === undefined ? null : decodeKey(bytes);
+    };
+    return {
+        read,
+        async loadOrCreate() {
+            const existing = await read();
+            // The whole point: a key that exists is READ, never regenerated and
+            // never overwritten. There is no write on this branch.
+            if (existing !== null)
+                return existing;
+            const created = await generateKey();
+            await init.backend.set(entry, encodeKey(created));
+            return created;
+        },
+        async clear() {
+            await init.backend.delete(entry);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The transport — the one package in the extraction that knows what libp2p is.
+ *
+ * An explicit list, never `export *`: the barrel this code came from ended
+ * with `export * from "./transport-duplex.js"`, which is how a package that
+ * documented itself as isomorphic pulled libp2p, TCP, Noise and yamux into
+ * every consumer's bundle.
+ */
+/**
+ * The SECOND ALTITUDE: duplex streams over the mesh.
+ *
+ * A fetch-only contract cannot express a WebSocket — both sides talking with
+ * neither input closed. These run one `Duplex` per libp2p stream, addressed by
+ * `(peerId, path)`, with identity captured per stream by closure exactly as
+ * the fetch path does it.
+ */
+export { createDuplexMounts, DUPLEX_PROTOCOL, type DuplexContext, type DuplexHandler, type DuplexMounts, NO_MOUNT, type OpenDuplexInit, openDuplex, type PeerDuplex, type ServeDuplexInit, serveDuplex, } from "./duplex.js";
+export { decodeHopAnswer, HOP_RESERVE_TIMEOUT_MS, HOP_STATUS_NAMES, HOP_STATUS_OK, type HopAnswer, RelayNotConnectedError, type RelayReservationGrant, RelayReservationRefusedError, requestRelayReservation, } from "./hop-reserve.js";
+export { HubReservationError, type HubReservationRefusal, hubRoute, leaveRelay, reachHub, reachHubRelayed, reserveOnHub, type SuperviseHubReservationInit, superviseHubReservation, } from "./hub-link.js";
+export { HUB_MAX_RESERVATIONS, type HubRelayComponents, type HubRelayServiceInit, hubRelayService, type IsMember, membershipGater, releaseReservation, } from "./hub-relay.js";
+export { type BytesStore, decodeKey, encodeKey, type GenerateKeyInit, generateKey, type IdentityStore, type IdentityStoreInit, identityStore, peerIdOf, type SignerLike, signerOf, } from "./identity.js";
+export type { CallOnLimitedConnection } from "./link.js";
+export { lastPeerIdOf } from "./multiaddr-parts.js";
+export { type CircuitAddrs, circuitAddrs, DEFAULT_RENEWAL_INTERVAL_MS, dialRelay, MAX_RENEWAL_INTERVAL_MS, MIN_RENEWAL_INTERVAL_MS, RESERVATION_LOSS_GRACE_MS, RESERVATION_POLL_ATTEMPTS, RESERVATION_POLL_INTERVAL_MS, type RelayLog, type RelayReservationEvent, type RelayReservationState, type RelayReservationStatus, type RelaySupervisor, renewalDelayMs, renewalIntervalMs, reservationHealthy, retryDelayMs, type SuperviseRelayInit, superviseRelay, type WaitForCircuitReservationInit, waitForCircuitReservation, } from "./reservation.js";
+export { type Peer, type ServePeerInit, servePeer } from "./serve-peer.js";
+export { globalTimers, type TimerHandle, type Timers } from "./timers.js";
+export { type CreateNodeInit, type CreateRemoteInit, createNode, createRemote, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_STREAMS, PROTOCOL, type ServeTransportInit, serveTransport, type TransportFactory, } from "./transport.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;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,QAAQ,EACR,KAAK,cAAc,EACnB,UAAU,EACV,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACb,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,KAAK,2BAA2B,EAChC,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,eAAe,EACf,KAAK,QAAQ,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,UAAU,EACf,SAAS,EACT,SAAS,EACT,KAAK,eAAe,EACpB,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,aAAa,EACb,QAAQ,EACR,KAAK,UAAU,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,KAAK,YAAY,EACjB,YAAY,EACZ,2BAA2B,EAC3B,SAAS,EACT,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,4BAA4B,EAC5B,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,6BAA6B,EAClC,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,UAAU,EACV,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,QAAQ,EACR,KAAK,kBAAkB,EACvB,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * The transport — the one package in the extraction that knows what libp2p is.
+ *
+ * An explicit list, never `export *`: the barrel this code came from ended
+ * with `export * from "./transport-duplex.js"`, which is how a package that
+ * documented itself as isomorphic pulled libp2p, TCP, Noise and yamux into
+ * every consumer's bundle.
+ */
+/**
+ * The SECOND ALTITUDE: duplex streams over the mesh.
+ *
+ * A fetch-only contract cannot express a WebSocket — both sides talking with
+ * neither input closed. These run one `Duplex` per libp2p stream, addressed by
+ * `(peerId, path)`, with identity captured per stream by closure exactly as
+ * the fetch path does it.
+ */
+export { createDuplexMounts, DUPLEX_PROTOCOL, NO_MOUNT, openDuplex, serveDuplex, } from "./duplex.js";
+export { decodeHopAnswer, HOP_RESERVE_TIMEOUT_MS, HOP_STATUS_NAMES, HOP_STATUS_OK, RelayNotConnectedError, RelayReservationRefusedError, requestRelayReservation, } from "./hop-reserve.js";
+export { HubReservationError, hubRoute, leaveRelay, reachHub, reachHubRelayed, reserveOnHub, superviseHubReservation, } from "./hub-link.js";
+export { HUB_MAX_RESERVATIONS, hubRelayService, membershipGater, releaseReservation, } from "./hub-relay.js";
+export { decodeKey, encodeKey, generateKey, identityStore, peerIdOf, signerOf, } from "./identity.js";
+export { lastPeerIdOf } from "./multiaddr-parts.js";
+export { circuitAddrs, DEFAULT_RENEWAL_INTERVAL_MS, dialRelay, MAX_RENEWAL_INTERVAL_MS, MIN_RENEWAL_INTERVAL_MS, RESERVATION_LOSS_GRACE_MS, RESERVATION_POLL_ATTEMPTS, RESERVATION_POLL_INTERVAL_MS, renewalDelayMs, renewalIntervalMs, reservationHealthy, retryDelayMs, superviseRelay, waitForCircuitReservation, } from "./reservation.js";
+export { servePeer } from "./serve-peer.js";
+export { globalTimers } from "./timers.js";
+export { createNode, createRemote, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_STREAMS, PROTOCOL, serveTransport, } from "./transport.js";

package/dist/link.d.ts

@@ -0,0 +1,49 @@
+/**
+ * libp2p, as a `PeerLink`.
+ *
+ * This is the whole of what makes the bridge libp2p-specific: how to open a
+ * duplex to a peer, and how to accept one. Everything the bridge does with
+ * those duplexes -- binding the proven peer, one stream per call, the permit,
+ * the timeout -- lives in `@statewalker/httpeers-bridge` and is shared with
+ * every other transport, including the MessagePort one the tests use.
+ *
+ * `serveConnections` is used rather than `node.handle` by hand because it
+ * already threads a `ConnectionContext`, and `context.remotePeer` is the
+ * answer the Noise handshake established. That value is what the bridge binds
+ * to every inbound request, and it is the reason a peer cannot lie about who
+ * it is no matter what headers it sets.
+ */
+import type { Libp2p } from "@libp2p/interface";
+import type { PeerLink } from "@statewalker/httpeers-bridge";
+import type { PeerIdStr } from "@statewalker/httpeers-core";
+export interface Libp2pLinkInit {
+    node: Libp2p;
+    /** Defaults to `PROTOCOL`. Two meshes on one node need two protocols. */
+    protocol?: string;
+    drainTimeoutMs?: number;
+    maxInboundStreams?: number;
+    maxOutboundStreams?: number;
+    /**
+     * ACCEPT streams on LIMITED connections (a relay circuit). Off by default:
+     * libp2p refuses, and that refusal is what keeps application traffic off a
+     * relay's small budget. A hub reached over the public relay sets it; a member
+     * never does, so its hub's relay limits still bound member-to-member traffic.
+     */
+    serveOnLimitedConnection?: boolean;
+    /** OPEN streams on limited connections, to the peers this allows. See `CallOnLimitedConnection`. */
+    callOnLimitedConnection?: CallOnLimitedConnection;
+}
+/**
+ * Which peers a call may reach over a LIMITED connection: `true` for all of
+ * them, or a predicate evaluated per target when the call opens its stream.
+ *
+ * A PREDICATE, NOT A BOOLEAN, because the one caller that needs it -- a member
+ * whose hub is reachable only through the relay -- must say "the hub" and
+ * nothing wider: `(peerId) => peerId === hubPeerId`. Separate from
+ * `serveOnLimitedConnection` for the same reason: a member calls its hub over
+ * the circuit without opening its own serving side to circuits.
+ */
+export type CallOnLimitedConnection = boolean | ((peerId: PeerIdStr) => boolean);
+/** Wrap a running libp2p node as the one seam the bridge needs. */
+export declare function libp2pLink(init: Libp2pLinkInit): PeerLink;
+//# sourceMappingURL=link.d.ts.map

package/dist/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAkB,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,4BAA4B,CAAC;AASxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oGAAoG;IACpG,uBAAuB,CAAC,EAAE,uBAAuB,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC;AAEjF,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,QAAQ,CA6CzD"}