@statewalker/httpeers-libp2p 0.1.3

package/src/hub-link.ts

@@ -0,0 +1,281 @@
+/**
+ * A member's link to its hub: reach it, reserve on it, and address other
+ * members through it. See `./hub-relay.ts` for the hub's side and why.
+ *
+ * TRANSPORT-NEUTRAL, like `./reservation.ts`: nothing here is browser-only,
+ * so the same code runs in a page and under the Node tests.
+ */
+
+import type { Connection, Libp2p } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { multiaddr } from "@multiformats/multiaddr";
+import { lastPeerIdOf } from "./multiaddr-parts.js";
+import { type RelaySupervisor, superviseRelay } from "./reservation.js";
+
+/**
+ * The address a member dials another member at: through their hub, with a
+ * WebRTC upgrade. The `/webrtc` step is what turns the hub's circuit into a
+ * signalling channel -- dialled without it, the result is a limited
+ * connection through the hub, which carries nothing.
+ *
+ * COMPOSED, NEVER TAKEN FROM A PEER'S OWN ADDRESSES. A reservation on the
+ * hub makes libp2p report a double-circuit address
+ * (`<relay>/p2p-circuit/webrtc/p2p/<hub>/p2p-circuit/p2p/<member>`) that
+ * nothing can dial. This works because the circuit transport reuses the
+ * connection it already holds to the hub.
+ */
+export function hubRoute(hubPeerId: string, peerId: string): string {
+  return `/p2p/${hubPeerId}/p2p-circuit/webrtc/p2p/${peerId}`;
+}
+
+/**
+ * Reach the hub over WebRTC through the public relay, and keep ONLY the
+ * WebRTC connection.
+ *
+ * WHY THE SIGNALLING CIRCUIT IS CLOSED. Reaching the hub leaves two
+ * connections to it: the limited circuit through the public relay that
+ * carried the SDP exchange, and the WebRTC one. The circuit transport relays
+ * through `getConnections(relay)[0]` -- the FIRST connection to the relay,
+ * limited or not -- so while the limited one is open, every dial THROUGH the
+ * hub fails with `LimitedConnectionError`. Found by the `proto/hub-relay`
+ * prototype; the "connects two members directly" test fails without it.
+ */
+export async function reachHub(node: Libp2p, relayAddr: string, hubPeerId: string): Promise<void> {
+  await node.dial(multiaddr(`${relayAddr}/p2p-circuit/webrtc/p2p/${hubPeerId}`));
+  const limited = node.getConnections(peerIdFromString(hubPeerId)).filter((c) => c.limits != null);
+  await Promise.all(limited.map((c) => c.close()));
+}
+
+/**
+ * Reach the hub through the public relay WITHOUT the WebRTC upgrade, and KEEP
+ * the circuit: the fallback for when `reachHub` cannot work (a hub in Docker on
+ * a bridge network has nothing a WebRTC dial can reach).
+ *
+ * The result is a LIMITED connection, and nothing crosses it unless both ends
+ * opt in: the hub serves with `serveOnLimitedConnection: true`, and the member
+ * calls with `callOnLimitedConnection` allowing the hub (`servePeer`,
+ * `createRemote`), which then opens its streams on this connection rather than
+ * dialling again.
+ *
+ * RETURNED AS LIBP2P RETURNS IT, and not always limited: if an unlimited
+ * connection to the hub already exists (a WebRTC upgrade that did come up),
+ * `dial` hands that back instead of opening a circuit. Check `limits` if it
+ * matters; the intended caller only gets here after `reachHub` failed, or
+ * after it succeeded but the hub refused a reservation -- and then hangs up
+ * the WebRTC connection first (`startMember`).
+ *
+ * NOT CLOSED, unlike `reachHub`'s circuit, because it is the data path. Two
+ * consequences for the caller: `reserveOnHub` has nothing to reserve over, so
+ * other members cannot reach this one; and `leaveRelay` would hang up the
+ * circuit itself.
+ */
+export async function reachHubRelayed(
+  node: Libp2p,
+  relayAddr: string,
+  hubPeerId: string,
+): Promise<Connection> {
+  return node.dial(multiaddr(`${relayAddr}/p2p-circuit/p2p/${hubPeerId}`));
+}
+
+/**
+ * Why a hub did not grant a reservation, as far as libp2p lets us tell.
+ *
+ *   - `"store-full"` -- `RESERVATION_REFUSED`: the hub's relay already holds
+ *     as many reservations as it grants (libp2p's `maxReservations`). A
+ *     capacity condition on the hub; nothing about this peer.
+ *   - `"resource-limit"` -- `RESOURCE_LIMIT_EXCEEDED`: the same kind of thing,
+ *     from a relay that meters resources rather than counting reservations.
+ *   - `"not-a-member"` -- `PERMISSION_DENIED`: the hub's `membershipGater`
+ *     does not count this peer as a member. (libp2p also answers it to a
+ *     reservation asked for over a relayed connection, which `reserveOnHub`
+ *     never does: it runs over `reachHub`'s WebRTC connection.)
+ *   - `"no-relay"` -- the hub does not speak the relay protocol at all
+ *     (`UnsupportedProtocolError`): a hub deployed without `hubRelayService`.
+ *   - `"no-answer"` -- no status came back: a timeout, a link that dropped
+ *     mid-request. Nothing was refused; nothing was granted either.
+ *   - `"other"` -- any other status, named verbatim in the message.
+ */
+export type HubReservationRefusal =
+  | "store-full"
+  | "resource-limit"
+  | "not-a-member"
+  | "no-relay"
+  | "no-answer"
+  | "other";
+
+/** `reserveOnHub`'s failure: which refusal, the relay's own status when it sent one, and libp2p's error as `cause`. */
+export class HubReservationError extends Error {
+  constructor(
+    readonly hubPeerId: string,
+    /** The circuit-relay v2 status the hub answered (`"RESERVATION_REFUSED"`, ...), or `null` when it answered none. */
+    readonly status: string | null,
+    readonly refusal: HubReservationRefusal,
+    options: { cause: unknown },
+  ) {
+    super(describeRefusal(hubPeerId, status, refusal, options.cause), options);
+    this.name = "HubReservationError";
+  }
+}
+
+/**
+ * Read the refusal out of libp2p's error.
+ *
+ * FROM THE TEXT, BECAUSE THAT IS ALL THERE IS. The transport manager wraps
+ * every failed listen in one `UnsupportedListenAddressesError` whose message
+ * embeds the inner error's stack -- `reservation failed with status <STATUS>`
+ * from the reservation store, or `UnsupportedProtocolError: ...` from protocol
+ * negotiation -- and keeps no reference to the inner error itself. The
+ * patterns are pinned against a real hub by the conformance suite's
+ * `member-reservation-fallback.test.ts`.
+ */
+function classify(err: unknown): { status: string | null; refusal: HubReservationRefusal } {
+  const text =
+    err instanceof Error ? `${err.name}: ${err.message}\n${err.stack ?? ""}` : String(err);
+  const status = /reservation failed with status (\w+)/.exec(text)?.[1] ?? null;
+  switch (status) {
+    case "RESERVATION_REFUSED":
+      return { status, refusal: "store-full" };
+    case "RESOURCE_LIMIT_EXCEEDED":
+      return { status, refusal: "resource-limit" };
+    case "PERMISSION_DENIED":
+      return { status, refusal: "not-a-member" };
+    case null:
+      return {
+        status,
+        refusal: /UnsupportedProtocolError|could not negotiate/.test(text)
+          ? "no-relay"
+          : "no-answer",
+      };
+    default:
+      return { status, refusal: "other" };
+  }
+}
+
+function describeRefusal(
+  hubPeerId: string,
+  status: string | null,
+  refusal: HubReservationRefusal,
+  cause: unknown,
+): string {
+  const hub = `hub-link: the hub (${hubPeerId})`;
+  switch (refusal) {
+    case "store-full":
+      return (
+        `${hub} refused a reservation with RESERVATION_REFUSED: the hub's reservation store is ` +
+        "full (it grants a fixed number, each held until it expires). Nothing is wrong with this " +
+        "peer; the hub has no slot for it."
+      );
+    case "resource-limit":
+      return `${hub} refused a reservation with RESOURCE_LIMIT_EXCEEDED: the hub's relay is at a resource limit.`;
+    case "not-a-member":
+      return (
+        `${hub} refused a reservation with PERMISSION_DENIED: this peer is not a member as far ` +
+        "as the hub is concerned (a hub grants reservations to its members only)."
+      );
+    case "no-relay":
+      return `${hub} does not relay at all -- it has no circuit-relay service (UnsupportedProtocolError).`;
+    case "no-answer":
+      return `${hub} gave no answer to a reservation request. Cause: ${firstLine(cause)}`;
+    case "other":
+      return `${hub} refused a reservation with ${status}.`;
+  }
+}
+
+/** The inner error libp2p quotes, or the error itself -- without the stack. */
+function firstLine(err: unknown): string {
+  const text = err instanceof Error ? err.message : String(err);
+  const lines = text.split("\n").map((line) => line.trim());
+  // libp2p's wrapper: a header line, then `<addr>: <inner error>` per address.
+  const inner = lines.find((line) => line.startsWith("/") && line.includes(": "));
+  return inner != null ? inner.slice(inner.indexOf(": ") + 2) : (lines[0] ?? "");
+}
+
+/**
+ * Reserve on the hub, over the WebRTC connection `reachHub` left open.
+ * Returns the reserved address. Only a member is granted one -- call this
+ * after the hub has accepted this peer, not before.
+ *
+ * A REFUSAL IS A `HubReservationError` that names the relay's own status --
+ * see `HubReservationRefusal`. libp2p reports every refusal alike, as "Some
+ * configured addresses failed to be listened on"; a full store and a
+ * non-member used to read the same, and in production a full store was
+ * diagnosed as a membership problem.
+ *
+ * A CONFIGURED RELAY, NOT A DISCOVERED ONE: libp2p will not restore it on
+ * its own if the link to the hub drops, which is `superviseHubReservation`'s
+ * job, below. Each call adds a listener; after a lost link -- or a refused
+ * reservation -- the old one sits empty. That is one small object per
+ * attempt, accepted rather than reaching into libp2p's internals to reuse it.
+ */
+export async function reserveOnHub(node: Libp2p, hubPeerId: string): Promise<string> {
+  try {
+    await transportManagerOf(node).listen([multiaddr(`/p2p/${hubPeerId}/p2p-circuit`)]);
+  } catch (err) {
+    const { status, refusal } = classify(err);
+    throw new HubReservationError(hubPeerId, status, refusal, { cause: err });
+  }
+  const reserved = node
+    .getMultiaddrs()
+    .map((addr) => addr.toString())
+    .find((addr) => addr.includes(`/p2p/${hubPeerId}/p2p-circuit`));
+  if (reserved == null) {
+    throw new Error(`hub-link: listening on the hub (${hubPeerId}) produced no reserved address`);
+  }
+  return reserved;
+}
+
+/**
+ * Close this member's connection to the public relay, once its hub link is
+ * up. A member holds no reservation there any more, and other members reach
+ * it through the hub, so the socket would only spend the relay's capacity.
+ * It is reopened on demand: `reachHub` dials through the relay whenever the
+ * hub has to be reached again.
+ */
+export async function leaveRelay(node: Libp2p, relayAddr: string): Promise<void> {
+  const relayPeerId = lastPeerIdOf(multiaddr(relayAddr));
+  if (relayPeerId != null) await node.hangUp(peerIdFromString(relayPeerId));
+}
+
+export interface SuperviseHubReservationInit {
+  node: Libp2p;
+  /** The public relay the hub is reached through -- `reachHub`'s. */
+  relayAddr: string;
+  hubPeerId: string;
+  minRetryDelayMs?: number;
+  maxRetryDelayMs?: number;
+}
+
+/**
+ * Keep this member's reservation on its hub: whenever it is lost, reach the
+ * hub again and re-reserve, with `superviseRelay`'s backoff and `poke()`.
+ * Call once the first `reserveOnHub` has succeeded.
+ */
+export function superviseHubReservation(init: SuperviseHubReservationInit): RelaySupervisor {
+  const { node, relayAddr, hubPeerId } = init;
+  return superviseRelay({
+    node,
+    relayAddr: `/p2p/${hubPeerId}`,
+    minRetryDelayMs: init.minRetryDelayMs,
+    maxRetryDelayMs: init.maxRetryDelayMs,
+    restore: async () => {
+      await reachHub(node, relayAddr, hubPeerId);
+      await reserveOnHub(node, hubPeerId);
+    },
+  });
+}
+
+/**
+ * The node's transport manager -- the only way to add a listen address after
+ * start. `components` is a public field of the libp2p 3.x node class but not
+ * part of the `Libp2p` interface, hence the narrow cast; pinned by
+ * `tests/e2e/hub-relay.test.ts`, which fails if a libp2p upgrade moves it.
+ */
+function transportManagerOf(node: Libp2p): {
+  listen(addrs: ReturnType<typeof multiaddr>[]): Promise<void>;
+} {
+  return (
+    node as unknown as {
+      components: { transportManager: { listen(addrs: unknown[]): Promise<void> } };
+    }
+  ).components.transportManager;
+}

package/src/hub-relay.ts

@@ -0,0 +1,188 @@
+/**
+ * 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,
+  circuitRelayServer,
+} from "@libp2p/circuit-relay-v2";
+import type { ConnectionGater, Libp2pEvents, PeerId, TypedEventTarget } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+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 function membershipGater(isMember: () => IsMember): ConnectionGater {
+  return {
+    denyInboundRelayReservation: async (source: PeerId) => !isMember()(source.toString()),
+    denyOutboundRelayedConnection: async (source: PeerId, destination: PeerId) => {
+      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;
+
+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 function hubRelayService(
+  init: HubRelayServiceInit = {},
+): (components: HubRelayComponents) => CircuitRelayService {
+  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: Pick<CircuitRelayService, "reservations">,
+  peer: PeerId | PeerIdStr,
+): boolean {
+  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: PeerIdStr): PeerId | undefined {
+  try {
+    return peerIdFromString(peer);
+  } catch {
+    return undefined;
+  }
+}

package/src/identity.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 type { Ed25519PrivateKey, Ed25519PublicKey } from "@libp2p/interface";
+import { peerIdFromPrivateKey, peerIdFromPublicKey } from "@libp2p/peer-id";
+import type { PeerIdStr } from "@statewalker/httpeers-core";
+
+/** `generateKeyPairFromSeed("Ed25519", seed)` requires exactly this many bytes. */
+const SEED_BYTES = 32;
+
+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 async function generateKey(init: GenerateKeyInit = {}): Promise<Ed25519PrivateKey> {
+  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: Ed25519PrivateKey | Ed25519PublicKey): PeerIdStr {
+  return key.type === "Ed25519" && "publicKey" in key
+    ? peerIdFromPrivateKey(key).toString()
+    : peerIdFromPublicKey(key as Ed25519PublicKey).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: Ed25519PrivateKey): Uint8Array {
+  return privateKeyToProtobuf(key);
+}
+
+/** Decode a stored key, refusing anything that is not Ed25519 **and saying what it was**. */
+export function decodeKey(bytes: Uint8Array): Ed25519PrivateKey {
+  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;
+}
+
+/**
+ * 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 function signerOf(key: Ed25519PrivateKey): SignerLike {
+  return { mesh: peerIdOf(key), seed: key.raw.slice(0, SEED_BYTES) };
+}
+
+/** 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 function identityStore(init: IdentityStoreInit): IdentityStore {
+  const entry = init.key ?? "identity";
+
+  const read = async (): Promise<Ed25519PrivateKey | null> => {
+    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);
+    },
+  };
+}