@statewalker/httpeers-member 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Everything a participant does: hold an identity, redeem or resume, connect,
+ * keep the link, advertise, discover, call, and serve.
+ *
+ * `startMember` is the seam rung 01 proved: one lifecycle, with the three
+ * things that genuinely differ between a Node process and a page injected as a
+ * `MemberPlatform`. `MemberHandle.fetch` IS the edge on both platforms;
+ * `baseUrl` is the browser-only part.
+ */
+export { type ConnectionKind, classifyConnection, describeConnection } from "./connection-kind.js";
+export { describeError } from "./describe-error.js";
+export { createEdgeDispatch, type EdgeDispatchInit, PEER_ERROR_STATUS, type PeerErrorBody, stripEdgePrefix, targetPeerId, } from "./edge-dispatch.js";
+/**
+ * The mesh as ordinary HTTP.
+ *
+ * `createGateway` turns a member into a `FetchHandler` dispatching
+ * `/{peerId}/{path}` — so a client with no peer object, no token and no
+ * knowledge of libp2p can `fetch()` a mesh resource. `GatewaySource` is
+ * structurally a subset of `MemberHandle`, so a member IS one.
+ */
+export { createGateway, GATEWAY_MARKER, type GatewayInit, type GatewaySource } from "./gateway.js";
+export { clearIdentity, decodeIdentity, encodeIdentity, IDENTITY_STORAGE_KEY, type IdentityStoreInit, loadOrCreateIdentity, peerIdOf, readIdentity, } from "./identity.js";
+export { decodeJoinBlob, encodeJoinBlob, invitationFromQrText, JOIN_BLOB_PARAM, type JoinBlob, type JoinInput, joinUrl, readJoinInputFromSearch, readJoinInputFromText, } from "./join-blob.js";
+export type { AsyncBytesBackend, AsyncKeyValueBackend } from "./kv.js";
+export { parseMeshConfig } from "./mesh-config.js";
+export { type CreateMeshMemoryInit, createMeshMemory, MESH_STORAGE_KEY, type MeshMemory, } from "./mesh-memory.js";
+export { type PeerRequestInit, peerRequest } from "./peer-request.js";
+/**
+ * The session machine — ISOMORPHIC, and exported from the root on purpose.
+ *
+ * It used to be the browser peer's private business. Everything platform-bound
+ * in it is now injected (the platform, the two stores, the reload), so a Node
+ * member that wants resume-or-redeem and the same four operator controls gets
+ * them here rather than reimplementing them. `./browser`'s `createSession` is
+ * the same thing with a page's defaults filled in.
+ */
+export { createIdentityStore, createPeerSession, DEFAULT_HTTPEERS_CONFIG_URL, describeMeshDrift, type IdentityStore, type NeedsInvitationReason, type PeerSession, type PeerSessionInit, type SessionControls, type SessionPhase, type SessionStartState, type SessionState, type StartPeer, } from "./session.js";
+export { type HubLink, type JoinMethod, type MemberEdge, type MemberHandle, MemberJoinError, type MemberPlatform, type MemberState, type StartMemberInit, startMember, } from "./start-member.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;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EACL,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACnG,OAAO,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,oBAAoB,EACpB,QAAQ,EACR,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,OAAO,EACP,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtE;;;;;;;;GAQG;AACH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,WAAW,GACZ,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * Everything a participant does: hold an identity, redeem or resume, connect,
+ * keep the link, advertise, discover, call, and serve.
+ *
+ * `startMember` is the seam rung 01 proved: one lifecycle, with the three
+ * things that genuinely differ between a Node process and a page injected as a
+ * `MemberPlatform`. `MemberHandle.fetch` IS the edge on both platforms;
+ * `baseUrl` is the browser-only part.
+ */
+export { classifyConnection, describeConnection } from "./connection-kind.js";
+export { describeError } from "./describe-error.js";
+export { createEdgeDispatch, PEER_ERROR_STATUS, stripEdgePrefix, targetPeerId, } from "./edge-dispatch.js";
+/**
+ * The mesh as ordinary HTTP.
+ *
+ * `createGateway` turns a member into a `FetchHandler` dispatching
+ * `/{peerId}/{path}` — so a client with no peer object, no token and no
+ * knowledge of libp2p can `fetch()` a mesh resource. `GatewaySource` is
+ * structurally a subset of `MemberHandle`, so a member IS one.
+ */
+export { createGateway, GATEWAY_MARKER } from "./gateway.js";
+export { clearIdentity, decodeIdentity, encodeIdentity, IDENTITY_STORAGE_KEY, loadOrCreateIdentity, peerIdOf, readIdentity, } from "./identity.js";
+export { decodeJoinBlob, encodeJoinBlob, invitationFromQrText, JOIN_BLOB_PARAM, joinUrl, readJoinInputFromSearch, readJoinInputFromText, } from "./join-blob.js";
+export { parseMeshConfig } from "./mesh-config.js";
+export { createMeshMemory, MESH_STORAGE_KEY, } from "./mesh-memory.js";
+export { peerRequest } from "./peer-request.js";
+/**
+ * The session machine — ISOMORPHIC, and exported from the root on purpose.
+ *
+ * It used to be the browser peer's private business. Everything platform-bound
+ * in it is now injected (the platform, the two stores, the reload), so a Node
+ * member that wants resume-or-redeem and the same four operator controls gets
+ * them here rather than reimplementing them. `./browser`'s `createSession` is
+ * the same thing with a page's defaults filled in.
+ */
+export { createIdentityStore, createPeerSession, DEFAULT_HTTPEERS_CONFIG_URL, describeMeshDrift, } from "./session.js";
+export { MemberJoinError, startMember, } from "./start-member.js";

package/dist/join-blob.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The join blob: everything a page needs to join a mesh whose hub is
+ * ANOTHER BROWSER PAGE, in one copyable string.
+ *
+ * WHY IT HAS TO EXIST. Every page in this stack has so far learned the mesh
+ * from `httpeers.json` -- `{ relayAddrs, hubPeerId }`, written once by
+ * `pnpm bootstrap` (`../setup/main.ts`) and served by both origins. That
+ * works because the Node hub's identity comes from a key file generated at
+ * bootstrap, so its peerId is knowable BEFORE it runs. The hub page's is
+ * not: it generates (or reloads) its identity in IndexedDB, in a tab, after
+ * `pnpm bootstrap` has already been and gone. Nothing on disk can name it.
+ * So the hub page hands its peerId out at runtime, alongside the relay it
+ * reserved through and a single-use invitation id -- and this module is the
+ * shape of that hand-off.
+ *
+ * ONE INVITATION PER PAGE, NOT ONE PER MESH. Invitations are single-use by
+ * construction (`../hub/hub-state.ts`'s `redeem` moves the id to
+ * `spentInvitationIds`, and the spent check runs first, unconditionally), so
+ * a blob shared between two pages lets exactly one in and fails the other
+ * with `already-redeemed`. `../pages/hub/main.ts` mints a fresh invitation
+ * per blob for that reason; this module only carries what it is given.
+ *
+ * THE ENCODING IS BASE64URL OF JSON, and it is a URL query parameter
+ * (`?join=`). Two properties matter and nothing else does: it survives a
+ * copy-paste through a terminal, a chat window and a browser address bar
+ * without needing quoting (base64url's alphabet is `A-Za-z0-9-_`, all
+ * URL-safe and none of it shell-special), and it is one token, so an
+ * operator cannot paste half of it. It is NOT encryption and not
+ * authentication -- anyone holding the blob can redeem the invitation
+ * inside it, which is exactly what an invitation is.
+ *
+ * NOT A HEADER, EVER. Same rule the rest of this app follows: human-facing
+ * text travels in a body or a URL, never a header (HTTP header values are
+ * latin1 -- see `../services/search.ts`'s own note).
+ */
+/** The invitation payload's shape (`../setup/main.ts`'s `HttpeersConfig`) plus the one-shot invitation id that goes with it. */
+export interface JoinBlob {
+    relayAddrs: string[];
+    hubPeerId: string;
+    invitationId: string;
+}
+/** The query parameter a join blob travels in. */
+export declare const JOIN_BLOB_PARAM = "join";
+/**
+ * Encode a blob. UTF-8 first, THEN base64: `btoa` throws on any code point
+ * above U+00FF, and while nothing in a blob is human text today (multiaddrs
+ * and peer ids are ASCII), a relay address is operator-supplied
+ * (`RELAY_HOST`) and a hostname can be an IDN.
+ */
+export declare function encodeJoinBlob(blob: JoinBlob): string;
+/**
+ * Decode a blob, validating every field rather than trusting the shape.
+ * Throws with a message naming what was wrong: this value was typed or
+ * pasted by a person, so a malformed one is an ordinary event, and "the
+ * link you pasted is missing its hub peer id" is a fixable complaint where
+ * `undefined is not an object` is not.
+ */
+export declare function decodeJoinBlob(text: string): JoinBlob;
+/** The join URL an operator copies: `pageOrigin` with this blob attached. `pageUrl` is a full URL (e.g. `http://127.0.0.1:5175/`). */
+export declare function joinUrl(pageUrl: string, blob: JoinBlob): string;
+/**
+ * What a page found in its own URL, or in what someone pasted into its
+ * join form.
+ *
+ * TWO CASES, AND THE DIFFERENCE IS WHICH MESH. A `join` blob carries its
+ * own `relayAddrs`/`hubPeerId`, so the page joins the mesh the blob names
+ * -- a hub page's. A bare `invite` id carries neither, so the page falls
+ * back to `httpeers.json` and joins the mesh the DEPLOYMENT names -- the
+ * Node hub's. Both are supported deliberately: the Node hub is not going
+ * anywhere (Task 24's first decision), and a page that silently preferred
+ * one would make the other unreachable with no way to say so.
+ */
+export type JoinInput = {
+    kind: "blob";
+    blob: JoinBlob;
+} | {
+    kind: "invitation-id";
+    invitationId: string;
+};
+/**
+ * Read a join input out of a page's `location.search`. Returns `null` when
+ * neither parameter is present -- the page then shows its paste-in form.
+ */
+export declare function readJoinInputFromSearch(search: string): JoinInput | null;
+/**
+ * Read a join input out of text a person pasted into a page's join form --
+ * a whole join URL, a bare blob, or a bare invitation id.
+ *
+ * ACCEPTS A WHOLE URL BECAUSE THAT IS WHAT GETS COPIED. The hub page's
+ * panel renders a complete link; an operator who copies it and pastes it
+ * into the form (rather than the address bar) has done nothing wrong, and a
+ * form that rejected it would be the page being pedantic about a
+ * distinction only it can see.
+ */
+export declare function readJoinInputFromText(text: string): JoinInput | null;
+/**
+ * The invitation inside a QR code's text, or `null` — a PREDICATE, not a
+ * parser.
+ *
+ * WHY IT NEVER THROWS, AND WHY IT IS STRICTER THAN `readJoinInputFromText`. A
+ * live scanner sees a poster, a wifi sticker and a payment code before it sees
+ * an invitation, and it has to keep scanning through all of them. So every
+ * "no" here is the same quiet `null`: a scan that stopped on the first wrong
+ * QR, or threw on a malformed URL, would be worse than one that carries on
+ * looking. `readJoinInputFromText` is the opposite and rightly so — somebody
+ * PASTED that, so they meant it, and a complaint is what they need.
+ *
+ * WHAT COUNTS. A bare string must be SHAPED like a join blob (base64url of a
+ * JSON object, so `eyJ` and nothing outside the base64url alphabet); a bare
+ * invitation id does NOT count, because from a QR there is nothing to tell one
+ * from any other short string. In a LINK the parameter names itself, so both
+ * `?join=` and `?invite=` count — which is how a Node-hub deployment's
+ * invitation stays scannable.
+ *
+ * This is a shape check, not validation. The hub decides whether a code is
+ * real, current and unspent; all this does is tell "you scanned the wrong QR"
+ * apart from "the hub refused this code", which are different problems with
+ * different fixes.
+ *
+ * Lives here, not in `@statewalker/httpeers-qr`, because it is entirely about
+ * the JOIN format — and a QR package that knew the join format could not be
+ * used for anything else.
+ */
+export declare function invitationFromQrText(text: string): string | null;
+//# sourceMappingURL=join-blob.d.ts.map

package/dist/join-blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-blob.d.ts","sourceRoot":"","sources":["../src/join-blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gIAAgI;AAChI,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,SAAS,CAAC;AAkBtC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAwBrD;AAED,sIAAsI;AACtI,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAI/D;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAWxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAqBpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBhE"}

package/dist/join-blob.js

@@ -0,0 +1,195 @@
+/**
+ * The join blob: everything a page needs to join a mesh whose hub is
+ * ANOTHER BROWSER PAGE, in one copyable string.
+ *
+ * WHY IT HAS TO EXIST. Every page in this stack has so far learned the mesh
+ * from `httpeers.json` -- `{ relayAddrs, hubPeerId }`, written once by
+ * `pnpm bootstrap` (`../setup/main.ts`) and served by both origins. That
+ * works because the Node hub's identity comes from a key file generated at
+ * bootstrap, so its peerId is knowable BEFORE it runs. The hub page's is
+ * not: it generates (or reloads) its identity in IndexedDB, in a tab, after
+ * `pnpm bootstrap` has already been and gone. Nothing on disk can name it.
+ * So the hub page hands its peerId out at runtime, alongside the relay it
+ * reserved through and a single-use invitation id -- and this module is the
+ * shape of that hand-off.
+ *
+ * ONE INVITATION PER PAGE, NOT ONE PER MESH. Invitations are single-use by
+ * construction (`../hub/hub-state.ts`'s `redeem` moves the id to
+ * `spentInvitationIds`, and the spent check runs first, unconditionally), so
+ * a blob shared between two pages lets exactly one in and fails the other
+ * with `already-redeemed`. `../pages/hub/main.ts` mints a fresh invitation
+ * per blob for that reason; this module only carries what it is given.
+ *
+ * THE ENCODING IS BASE64URL OF JSON, and it is a URL query parameter
+ * (`?join=`). Two properties matter and nothing else does: it survives a
+ * copy-paste through a terminal, a chat window and a browser address bar
+ * without needing quoting (base64url's alphabet is `A-Za-z0-9-_`, all
+ * URL-safe and none of it shell-special), and it is one token, so an
+ * operator cannot paste half of it. It is NOT encryption and not
+ * authentication -- anyone holding the blob can redeem the invitation
+ * inside it, which is exactly what an invitation is.
+ *
+ * NOT A HEADER, EVER. Same rule the rest of this app follows: human-facing
+ * text travels in a body or a URL, never a header (HTTP header values are
+ * latin1 -- see `../services/search.ts`'s own note).
+ */
+/** The query parameter a join blob travels in. */
+export const JOIN_BLOB_PARAM = "join";
+function toBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+    const base64 = text.replaceAll("-", "+").replaceAll("_", "/");
+    // `atob` requires the padding `toBase64Url` stripped.
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * Encode a blob. UTF-8 first, THEN base64: `btoa` throws on any code point
+ * above U+00FF, and while nothing in a blob is human text today (multiaddrs
+ * and peer ids are ASCII), a relay address is operator-supplied
+ * (`RELAY_HOST`) and a hostname can be an IDN.
+ */
+export function encodeJoinBlob(blob) {
+    return toBase64Url(new TextEncoder().encode(JSON.stringify(blob)));
+}
+/**
+ * Decode a blob, validating every field rather than trusting the shape.
+ * Throws with a message naming what was wrong: this value was typed or
+ * pasted by a person, so a malformed one is an ordinary event, and "the
+ * link you pasted is missing its hub peer id" is a fixable complaint where
+ * `undefined is not an object` is not.
+ */
+export function decodeJoinBlob(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(fromBase64Url(text.trim())));
+    }
+    catch (err) {
+        throw new Error("join blob: this is not a join link from a hub page -- it did not decode. Copy the whole " +
+            `link, including the "?${JOIN_BLOB_PARAM}=" part. Cause: ${String(err)}`, { cause: err });
+    }
+    const blob = parsed;
+    const relayAddrs = blob.relayAddrs;
+    if (!Array.isArray(relayAddrs) || relayAddrs.length === 0) {
+        throw new Error("join blob: no relayAddrs -- there is nothing to dial.");
+    }
+    if (typeof blob.hubPeerId !== "string" || blob.hubPeerId === "") {
+        throw new Error("join blob: no hubPeerId -- this page would not know which mesh to join.");
+    }
+    if (typeof blob.invitationId !== "string" || blob.invitationId === "") {
+        throw new Error("join blob: no invitationId -- this page would have nothing to redeem.");
+    }
+    return { relayAddrs, hubPeerId: blob.hubPeerId, invitationId: blob.invitationId };
+}
+/** The join URL an operator copies: `pageOrigin` with this blob attached. `pageUrl` is a full URL (e.g. `http://127.0.0.1:5175/`). */
+export function joinUrl(pageUrl, blob) {
+    const url = new URL(pageUrl);
+    url.searchParams.set(JOIN_BLOB_PARAM, encodeJoinBlob(blob));
+    return url.toString();
+}
+/**
+ * Read a join input out of a page's `location.search`. Returns `null` when
+ * neither parameter is present -- the page then shows its paste-in form.
+ */
+export function readJoinInputFromSearch(search) {
+    const params = new URLSearchParams(search);
+    const blobParam = params.get(JOIN_BLOB_PARAM);
+    if (blobParam != null && blobParam.trim() !== "") {
+        return { kind: "blob", blob: decodeJoinBlob(blobParam) };
+    }
+    const invite = params.get("invite");
+    if (invite != null && invite.trim() !== "") {
+        return { kind: "invitation-id", invitationId: invite.trim() };
+    }
+    return null;
+}
+/**
+ * Read a join input out of text a person pasted into a page's join form --
+ * a whole join URL, a bare blob, or a bare invitation id.
+ *
+ * ACCEPTS A WHOLE URL BECAUSE THAT IS WHAT GETS COPIED. The hub page's
+ * panel renders a complete link; an operator who copies it and pastes it
+ * into the form (rather than the address bar) has done nothing wrong, and a
+ * form that rejected it would be the page being pedantic about a
+ * distinction only it can see.
+ */
+export function readJoinInputFromText(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return null;
+    if (trimmed.includes("://") || trimmed.includes(`${JOIN_BLOB_PARAM}=`)) {
+        // A URL, or at least something with a query string in it. `new URL`
+        // needs a base for the second case; the base is never used for anything
+        // but parsing, and the blob inside carries the real addresses.
+        const url = new URL(trimmed, "http://join.invalid/");
+        const found = readJoinInputFromSearch(url.search);
+        if (found != null)
+            return found;
+        throw new Error(`join: that link carries no "${JOIN_BLOB_PARAM}" or "invite" parameter -- is it the whole link?`);
+    }
+    // A bare value. A blob is base64url of a JSON object, which always starts
+    // `{"` -> `eyJ`; an invitation id is a UUID (`../hub/main.ts`'s
+    // `randomUUID`) and never does.
+    if (trimmed.startsWith("eyJ"))
+        return { kind: "blob", blob: decodeJoinBlob(trimmed) };
+    return { kind: "invitation-id", invitationId: trimmed };
+}
+/**
+ * The invitation inside a QR code's text, or `null` — a PREDICATE, not a
+ * parser.
+ *
+ * WHY IT NEVER THROWS, AND WHY IT IS STRICTER THAN `readJoinInputFromText`. A
+ * live scanner sees a poster, a wifi sticker and a payment code before it sees
+ * an invitation, and it has to keep scanning through all of them. So every
+ * "no" here is the same quiet `null`: a scan that stopped on the first wrong
+ * QR, or threw on a malformed URL, would be worse than one that carries on
+ * looking. `readJoinInputFromText` is the opposite and rightly so — somebody
+ * PASTED that, so they meant it, and a complaint is what they need.
+ *
+ * WHAT COUNTS. A bare string must be SHAPED like a join blob (base64url of a
+ * JSON object, so `eyJ` and nothing outside the base64url alphabet); a bare
+ * invitation id does NOT count, because from a QR there is nothing to tell one
+ * from any other short string. In a LINK the parameter names itself, so both
+ * `?join=` and `?invite=` count — which is how a Node-hub deployment's
+ * invitation stays scannable.
+ *
+ * This is a shape check, not validation. The hub decides whether a code is
+ * real, current and unspent; all this does is tell "you scanned the wrong QR"
+ * apart from "the hub refused this code", which are different problems with
+ * different fixes.
+ *
+ * Lives here, not in `@statewalker/httpeers-qr`, because it is entirely about
+ * the JOIN format — and a QR package that knew the join format could not be
+ * used for anything else.
+ */
+export function invitationFromQrText(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return null;
+    if (trimmed.includes("://") || trimmed.includes("?")) {
+        try {
+            const params = new URL(trimmed, "http://scan.invalid/").searchParams;
+            const blob = params.get(JOIN_BLOB_PARAM)?.trim();
+            if (blob != null && blob !== "")
+                return blob;
+            const invite = params.get("invite")?.trim();
+            return invite != null && invite !== "" ? invite : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return looksLikeJoinBlob(trimmed) ? trimmed : null;
+}
+/** `eyJ` is `{"` in base64; 40 is well below a real blob and well above a stray word. */
+function looksLikeJoinBlob(value) {
+    return value.startsWith("eyJ") && /^[A-Za-z0-9_-]{40,}$/.test(value);
+}