@geohar/un-bien 0.7.0

package/dist/mcp/mesh_server.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+/**
+ * MCP server that bridges Claude Code to the un-bien agent mesh.
+ *
+ * Spawned by Claude Code as an MCP server subprocess (stdio).
+ * Joins the mesh through the shared `MeshNode` abstraction — the SAME
+ * composition the Pi extension uses — so Claude is a first-class mesh
+ * participant: it can lead the local UDS broker when no Pi/daemon is up,
+ * and (as leader) bring up its own cross-PC relay bridge with its own
+ * Pi-key. As a follower it rides the existing leader's bridge.
+ *
+ * Launched by `unbien claude` (registers this in Claude's local MCP
+ * scope). Args: [--cwd <path>] [--name <agentName>] [--no-bridge]
+ * Env: UNBIEN_MCP_CWD, UNBIEN_MCP_NAME
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MeshNode } from "../session/mesh_node.js";
+import { loadLocalConfig, defaultAgentName, localConfigExists, } from "../session/local_config.js";
+import { formatMeshAckResult } from "./mesh_result.js";
+import { sessionSockPath, sessionAuditPath, LOCAL_SESSION_NAME, } from "../session/global_config.js";
+import { resolveRelayUrl } from "../config.js";
+import { acquireCwdLock } from "../session/cwd_lock.js";
+import { realpathSync } from "node:fs";
+// ── Args / config ─────────────────────────────────────────────────────────────
+const _argv = process.argv.slice(2);
+// This agent's folder = the dir the `claude` session was launched in, which
+// Claude sets as this subprocess's `process.cwd()`. We deliberately do NOT use
+// CLAUDE_PROJECT_DIR: that's the git repo root, which would collapse every
+// monorepo subproject (app/, relay/, …) into one identity + one lock. The
+// `unbien claude` launcher therefore registers us WITHOUT a baked `--cwd`,
+// so one shared local-scope entry self-identifies per session. `--cwd` and
+// UNBIEN_MCP_CWD remain as explicit overrides (tests / manual launches).
+let _cwd = process.env["UNBIEN_MCP_CWD"] ?? process.cwd();
+let _nameOverride = process.env["UNBIEN_MCP_NAME"];
+let _bridgeEnabled = true;
+for (let i = 0; i < _argv.length; i++) {
+    if (_argv[i] === "--cwd" && _argv[i + 1]) {
+        _cwd = _argv[++i];
+    }
+    else if (_argv[i] === "--name" && _argv[i + 1]) {
+        _nameOverride = _argv[++i];
+    }
+    else if (_argv[i] === "--no-bridge") {
+        _bridgeEnabled = false;
+    }
+}
+const _cfg = loadLocalConfig(_cwd);
+const AGENT_NAME = _nameOverride ?? _cfg.agent_name ?? defaultAgentName(_cwd);
+// Platform-aware (plan/40): POSIX → broker.sock file; Windows → named pipe.
+const BROKER_SOCK = sessionSockPath(LOCAL_SESSION_NAME);
+const AUDIT_PATH = sessionAuditPath(LOCAL_SESSION_NAME);
+const inbox = [];
+// ── Mesh node ─────────────────────────────────────────────────────────────────
+const { url: relayUrl } = resolveRelayUrl();
+// Diagnostics go to STDERR — stdout is the JSON-RPC channel, so writing there
+// would corrupt the MCP protocol. Claude Code captures an MCP server's stderr
+// into its mcp-logs, which is where these land for debugging.
+function logErr(msg) {
+    process.stderr.write(`[un-bien-mesh ${isoNow()}] ${msg}\n`);
+}
+// Survive stray async failures. This process runs background work (relay WS
+// churn, UDS failover, the MCP SDK) whose errors previously had NO global
+// handler — a single unhandled rejection or exception silently killed this
+// stdio subprocess, and Claude surfaced the MCP as "disconnected" with no
+// trace. None of that background work is fatal to serving tools over stdio, so
+// log loudly and keep running instead of dying. (We intentionally do NOT
+// process.exit here: the tools stay available even if the mesh is degraded.)
+process.on("unhandledRejection", (reason) => {
+    logErr(`unhandledRejection: ${reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)}`);
+});
+process.on("uncaughtException", (err) => {
+    logErr(`uncaughtException: ${err.stack ?? err.message}`);
+});
+// Canonicalize so the (cwd, name) the broker keys us by matches roomIdForCwd
+// and the Pi extension's own register (symlinked cwds map to one identity).
+let _canonCwd = _cwd;
+try {
+    _canonCwd = realpathSync(_cwd);
+}
+catch {
+    /* cwd missing — use raw path */
+}
+const mesh = new MeshNode({
+    sockPath: BROKER_SOCK,
+    name: AGENT_NAME,
+    cwd: _canonCwd, // plan/38: register with (cwd, name) → address `<cwd>@<name>`
+    auditPath: AUDIT_PATH,
+    // Own Pi-key cross-PC bridge — active only when this node leads (no Pi /
+    // daemon already hosting the broker for this cwd). As a follower the
+    // bridge stays dormant and cross-PC rides the existing leader.
+    ...(_bridgeEnabled && relayUrl !== null
+        ? { bridge: { relayUrl, cwd: _cwd } }
+        : {}),
+    // Silent: stdout is the MCP JSON-RPC channel and stderr noise isn't wanted.
+    // Real failures still surface via the global handlers / fail-loud below.
+    log: () => {
+        /* no-op */
+    },
+});
+let meshReady = false;
+// When the mesh isn't joined, this explains why (folder busy / connecting), so
+// the tools return something actionable instead of a generic "not connected".
+let degradedReason = "connecting to the mesh…";
+// ── MCP server setup ──────────────────────────────────────────────────────────
+const mcp = new McpServer({ name: "un-bien-mesh", version: "0.4.3" }, {
+    capabilities: { experimental: { "claude/channel": {} } },
+    instructions: [
+        `You are connected to the un-bien agent mesh as "${AGENT_NAME}".`,
+        "At the start of each turn call get_messages to check for incoming messages from other agents.",
+        "Use list_peers to discover available agents.",
+        "Use agent_send to send messages — pass the exact address returned by list_peers (form `<cwd>@<name>`, `<pc>:` prefix cross-PC) VERBATIM; never build one by hand.",
+        'Use "broadcast" as the target to send to all peers in your folder (cwd) at once.',
+        "Follow the agent-network protocol (in your system prompt) for the full details (ACK statuses, replies via re, `<cwd>@<name>` addresses, cross-PC `<pc>:` prefix).",
+    ].join("\n"),
+});
+function notReady() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Mesh not available yet — ${degradedReason}`,
+            },
+        ],
+        isError: true,
+    };
+}
+mcp.registerTool("list_peers", {
+    description: "List all agents currently in the mesh (local + remote PCs).",
+    inputSchema: {},
+}, async () => {
+    if (!meshReady)
+        return notReady();
+    try {
+        const peers = await mesh.listPeers();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: peers.length > 0 ? peers.join("\n") : "(no peers)",
+                },
+            ],
+        };
+    }
+    catch (e) {
+        return {
+            content: [
+                { type: "text", text: `list_peers failed: ${String(e)}` },
+            ],
+            isError: true,
+        };
+    }
+});
+mcp.registerTool("agent_send", {
+    description: 'Send a message to another agent. Use "broadcast" to send to all peers.',
+    inputSchema: {
+        to: z
+            .string()
+            .describe('Peer address from list_peers (form "<cwd>@<name>", or "<pc>:<cwd>@<name>" cross-PC) echoed verbatim, or "broadcast"'),
+        body: z.unknown().describe("Message body — any JSON value"),
+        re: z
+            .string()
+            .optional()
+            .describe("Optional: id of the message you are replying to"),
+    },
+}, async ({ to, body, re }) => {
+    if (!meshReady)
+        return notReady();
+    if (to === mesh.address() || to === mesh.name()) {
+        return {
+            content: [{ type: "text", text: "Cannot send to yourself" }],
+            isError: true,
+        };
+    }
+    try {
+        if (to === "broadcast") {
+            await mesh.send(to, body, re ?? null);
+            return { content: [{ type: "text", text: "Broadcast sent" }] };
+        }
+        const ack = await mesh.sendWithAck(to, body, re ?? null);
+        return formatMeshAckResult(to, ack);
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `send failed: ${String(e)}` }],
+            isError: true,
+        };
+    }
+});
+mcp.registerTool("get_messages", {
+    description: "Return and clear all pending incoming messages from other agents. Call at the start of each turn.",
+    inputSchema: {},
+}, async () => {
+    const msgs = inbox.splice(0);
+    if (msgs.length === 0)
+        return { content: [{ type: "text", text: "(no messages)" }] };
+    const lines = msgs.map((m) => `[${m.at}] from=${m.from}${m.re ? ` re=${m.re}` : ""}\nid=${m.id}\n${JSON.stringify(m.body, null, 2)}`);
+    return { content: [{ type: "text", text: lines.join("\n\n") }] };
+});
+// ── Main ──────────────────────────────────────────────────────────────────────
+function isoNow() {
+    return new Date().toISOString();
+}
+// Background lock+join state. The cwd lock enforces the per-folder singleton
+// (at most one un-bien agent — Pi OR Claude — per folder; a second peer with
+// the same cwd-derived name would be a ghost).
+//
+// We retry only briefly — just enough to ride out a restart RACE (the previous
+// MCP for this folder is still tearing down when Claude respawns us). After a
+// short grace we FAIL LOUD (exit non-zero) rather than degrade forever: a
+// silent connected-but-idle MCP hides the real problem (you launched claude in
+// the wrong folder, or this folder already has a live agent — a duplicate
+// session). Failing makes Claude show the MCP as errored so you actually see it.
+const JOIN_RETRY_MS = 2_000;
+const MAX_JOIN_ATTEMPTS = 4; // ~6–8s grace for a restart race, then fail loud
+let _lock = null;
+let _lockRetryTimer = null;
+let _lockAttempt = 0;
+let _joined = false;
+let _shuttingDown = false;
+async function main() {
+    // Subscribe BEFORE connecting so we don't miss early envelopes. The
+    // SessionPeer swallows broker ACKs / system events itself, so handlers
+    // only see real peer messages (and replies, which carry `re`).
+    mesh.onMessage((env) => {
+        // plan/34 (passive presence): broker control/system envelopes
+        // (`peer_joined` / `peer_left` / `list_peers_reply`) are presence signals,
+        // NOT agent messages. Never push them to the inbox or the claude/channel —
+        // otherwise a peer joining/leaving would wake this agent's turn. Discovery
+        // is pull-based via `list_peers`. (Real broker ACKs and `re` replies are
+        // already swallowed upstream by SessionPeer.)
+        if (env.from === "broker" || env.from.endsWith(":broker"))
+            return;
+        const msg = {
+            from: env.from,
+            body: env.body,
+            id: env.id,
+            re: env.re,
+            at: isoNow(),
+        };
+        inbox.push(msg);
+        // Push via claude/channel so Claude wakes immediately (when the session
+        // was launched with --dangerously-load-development-channels server:un-bien-mesh).
+        void mcp.server
+            .notification({
+            method: "notifications/claude/channel",
+            params: {
+                content: `📨 Message from ${msg.from}:\n${JSON.stringify(msg.body, null, 2)}`,
+            },
+        })
+            .catch(() => {
+            /* channels not enabled — get_messages polling covers it */
+        });
+    });
+    // Connect the stdio transport FIRST and unconditionally, so Claude Code
+    // always sees this server as connected and the tools stay reachable — even
+    // before (or entirely without) a mesh join. The mesh join is layered on
+    // best-effort below; a busy folder no longer kills the MCP.
+    const transport = new StdioServerTransport();
+    transport.onclose = shutdown;
+    process.stdin.on("end", shutdown);
+    process.stdin.on("close", shutdown);
+    await mcp.connect(transport);
+    // Only join the mesh if this folder is an actual un-bien agent — i.e. it
+    // has a local config (written by the `unbien claude` wizard) or an
+    // explicit name override. `-s local` MCP registrations are inherited by
+    // EVERY claude session in the git repo, so without this gate a plain claude
+    // opened in any subfolder would auto-grab that folder's lock and join as a
+    // stray agent — colliding with the real agent. No config ⇒ stay connected
+    // but idle (tools report why); don't lock, don't join, don't retry.
+    if (localConfigExists(_cwd) || _nameOverride !== undefined) {
+        // Kick off the lock+join in the background. Never awaited — the MCP is
+        // already serving; mesh availability arrives (and recovers) asynchronously.
+        void tryJoinMesh();
+    }
+    else {
+        degradedReason =
+            `this folder is not a un-bien agent (no config). Run "unbien claude" ` +
+                `here to make it one. Mesh tools are idle.`;
+    }
+}
+/** Acquire the per-cwd lock, then join the mesh. Retries briefly to absorb a
+ *  restart race; if the lock or join still fails after MAX_JOIN_ATTEMPTS, FAIL
+ *  LOUD (exit) so the failure is visible instead of silently degrading. */
+async function tryJoinMesh() {
+    if (_joined || _shuttingDown)
+        return;
+    const res = await acquireCwdLock(_cwd);
+    if (!res.ok) {
+        _lockAttempt++;
+        if (_lockAttempt >= MAX_JOIN_ATTEMPTS) {
+            _failLoud(`folder already served by another un-bien agent (lock: ${res.lockPath})`);
+        }
+        degradedReason = `folder busy (lock ${res.lockPath}); attempt ${_lockAttempt}/${MAX_JOIN_ATTEMPTS}`;
+        _scheduleJoinRetry(JOIN_RETRY_MS);
+        return;
+    }
+    _lock = res;
+    try {
+        await mesh.connect();
+        meshReady = true;
+        _joined = true;
+        _lockAttempt = 0;
+    }
+    catch (e) {
+        // Got the lock but the broker join failed (e.g. socket churn). Release the
+        // lock so another contender isn't starved, then retry / fail loud.
+        _lockAttempt++;
+        try {
+            _lock.release();
+        }
+        catch {
+            /* best-effort */
+        }
+        _lock = null;
+        if (_lockAttempt >= MAX_JOIN_ATTEMPTS) {
+            _failLoud(`mesh join failed: ${String(e)}`);
+        }
+        degradedReason = `mesh join failed (attempt ${_lockAttempt}/${MAX_JOIN_ATTEMPTS}): ${String(e)}`;
+        _scheduleJoinRetry(JOIN_RETRY_MS);
+    }
+}
+function _scheduleJoinRetry(delayMs) {
+    if (_lockRetryTimer || _joined || _shuttingDown)
+        return;
+    const t = setTimeout(() => {
+        _lockRetryTimer = null;
+        void tryJoinMesh();
+    }, delayMs);
+    // Don't let the retry timer alone keep the process alive past stdin close.
+    t.unref?.();
+    _lockRetryTimer = t;
+}
+/** Exit non-zero with a loud, specific reason so Claude surfaces the MCP as
+ *  errored (visible) instead of a silent connected-but-idle peer. */
+function _failLoud(reason) {
+    logErr(`FATAL: ${reason}. Exiting so the failure is visible. cwd=${_cwd}. ` +
+        `Most likely you launched claude in the WRONG FOLDER, or this folder ` +
+        `already has a running un-bien agent (a duplicate session). ` +
+        `Launch one agent per folder via "unbien claude" from the project dir.`);
+    process.exit(1);
+}
+// Exit cleanly when Claude Code disconnects. The MeshNode keeps a UDS socket
+// (and, when leader, a relay WS) open, so without this the process would linger
+// after Claude exits — orphaning the mesh peer (it keeps showing "online" with
+// nothing attached). We leave the mesh, then exit. Triggered by the MCP
+// transport closing or stdin hitting EOF (whichever the host does first).
+function shutdown() {
+    if (_shuttingDown)
+        return;
+    _shuttingDown = true;
+    if (_lockRetryTimer) {
+        clearTimeout(_lockRetryTimer);
+        _lockRetryTimer = null;
+    }
+    try {
+        _lock?.release();
+    }
+    catch {
+        /* OS frees the UDS lock on exit anyway */
+    }
+    void Promise.resolve(mesh.close())
+        .catch(() => {
+        /* best-effort */
+    })
+        .finally(() => process.exit(0));
+}
+main().catch((err) => {
+    process.stderr.write(`[un-bien-mesh] fatal: ${String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=mesh_server.js.map

package/dist/mcp/mesh_server.js.map

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

package/dist/mesh/canonical.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JCS-like canonical JSON encoder for the mesh membership protocol.
+ *
+ * **Spec**: plan/24-mesh-membership.md — "chaves ordenadas alfabeticamente +
+ * separadores `,` e `:` sem espaços. Mesma regra em Dart, Rust, TypeScript."
+ *
+ * **Bit-compatibility contract** (must hold across the 3 implementations):
+ *   - Object keys sorted lexicographically by UTF-16 code unit order
+ *     (matches Dart's String compareTo, Rust's BTreeMap<String, _>, and
+ *     JS's Array.prototype.sort() default).
+ *   - No whitespace between any tokens.
+ *   - Arrays preserve insertion order (caller's responsibility to sort if
+ *     determinism across producers matters — verifier doesn't enforce).
+ *   - Numbers serialized via JSON.stringify default (no trailing zeros).
+ *     Mesh schema only carries integers (`version`, `issued_at`), so the
+ *     fragile float-formatting space is avoided by design.
+ *   - Strings UTF-8 encoded, JSON-escape rules per RFC 8259 (control chars
+ *     and `\\`, `"` escaped; raw UTF-8 for printable code points). Matches
+ *     `dart:convert.jsonEncode` and `serde_json::to_string` defaults.
+ *   - `null` preserved; `undefined`/functions/symbols dropped (mirrors
+ *     JSON.stringify).
+ *
+ * Verification path: receiver canonicalizes nothing — it verifies the
+ * raw blob bytes as-received against the signature. This module is used
+ * only on the *sender* side, and on the *test* side to construct fixtures
+ * for `verify.test.ts`.
+ */
+export declare function canonicalize(value: unknown): string;
+/** Canonical JSON string as UTF-8 bytes. The exact bytes that get signed. */
+export declare function canonicalBytes(value: unknown): Uint8Array;

package/dist/mesh/canonical.js

@@ -0,0 +1,63 @@
+/**
+ * JCS-like canonical JSON encoder for the mesh membership protocol.
+ *
+ * **Spec**: plan/24-mesh-membership.md — "chaves ordenadas alfabeticamente +
+ * separadores `,` e `:` sem espaços. Mesma regra em Dart, Rust, TypeScript."
+ *
+ * **Bit-compatibility contract** (must hold across the 3 implementations):
+ *   - Object keys sorted lexicographically by UTF-16 code unit order
+ *     (matches Dart's String compareTo, Rust's BTreeMap<String, _>, and
+ *     JS's Array.prototype.sort() default).
+ *   - No whitespace between any tokens.
+ *   - Arrays preserve insertion order (caller's responsibility to sort if
+ *     determinism across producers matters — verifier doesn't enforce).
+ *   - Numbers serialized via JSON.stringify default (no trailing zeros).
+ *     Mesh schema only carries integers (`version`, `issued_at`), so the
+ *     fragile float-formatting space is avoided by design.
+ *   - Strings UTF-8 encoded, JSON-escape rules per RFC 8259 (control chars
+ *     and `\\`, `"` escaped; raw UTF-8 for printable code points). Matches
+ *     `dart:convert.jsonEncode` and `serde_json::to_string` defaults.
+ *   - `null` preserved; `undefined`/functions/symbols dropped (mirrors
+ *     JSON.stringify).
+ *
+ * Verification path: receiver canonicalizes nothing — it verifies the
+ * raw blob bytes as-received against the signature. This module is used
+ * only on the *sender* side, and on the *test* side to construct fixtures
+ * for `verify.test.ts`.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("canonical: non-finite number cannot be JSON-encoded");
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        // Inside arrays, undefined → null (mirrors JSON.stringify).
+        const items = value.map((v) => v === undefined ? "null" : canonicalize(v));
+        return "[" + items.join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort();
+        const pairs = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
+        return "{" + pairs.join(",") + "}";
+    }
+    // undefined / functions / symbols at the root → JSON.stringify returns
+    // undefined; we surface as "null" for callers that wrap us.
+    return "null";
+}
+const TEXT_ENCODER = new TextEncoder();
+/** Canonical JSON string as UTF-8 bytes. The exact bytes that get signed. */
+export function canonicalBytes(value) {
+    return TEXT_ENCODER.encode(canonicalize(value));
+}
+//# sourceMappingURL=canonical.js.map

package/dist/mesh/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/mesh/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,4DAA4D;QAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5B,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAC3C,CAAC;QACF,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;aACnC,IAAI,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACtD,CAAC;QACF,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,uEAAuE;IACvE,4DAA4D;IAC5D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;AAEvC,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,YAAY,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/dist/mesh/client.d.ts

@@ -0,0 +1,18 @@
+import type { MeshEnvelope } from "./types.js";
+export declare class MeshFetchUnavailableError extends Error {
+    readonly name = "MeshFetchUnavailableError";
+}
+export declare class MeshFetchInvalidResponseError extends Error {
+    readonly name = "MeshFetchInvalidResponseError";
+}
+export interface MeshClientOptions {
+    /** Finite deadline covering response headers and body parsing. */
+    readonly requestTimeoutMs?: number;
+}
+/** Finite-deadline HTTP client for Relay mesh membership envelopes. */
+export declare class MeshClient {
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    constructor(relayUrl: string, options?: MeshClientOptions);
+    get(hash: string, since?: number): Promise<MeshEnvelope | null>;
+}

package/dist/mesh/client.js

@@ -0,0 +1,127 @@
+export class MeshFetchUnavailableError extends Error {
+    name = "MeshFetchUnavailableError";
+}
+export class MeshFetchInvalidResponseError extends Error {
+    name = "MeshFetchInvalidResponseError";
+}
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+const ED25519_SIGNATURE_BYTES = 64;
+function invalidResponse() {
+    return new MeshFetchInvalidResponseError("mesh response is invalid");
+}
+function unavailable() {
+    return new MeshFetchUnavailableError("mesh request is unavailable");
+}
+function decodeStrictBase64(raw) {
+    if (raw.length === 0)
+        throw invalidResponse();
+    const hasStandardOnlyCharacters = /[+/]/.test(raw);
+    const hasUrlSafeOnlyCharacters = /[-_]/.test(raw);
+    if (hasStandardOnlyCharacters && hasUrlSafeOnlyCharacters) {
+        throw invalidResponse();
+    }
+    const firstPaddingIndex = raw.indexOf("=");
+    const body = firstPaddingIndex === -1 ? raw : raw.slice(0, firstPaddingIndex);
+    const padding = firstPaddingIndex === -1 ? "" : raw.slice(firstPaddingIndex);
+    const bodyPattern = hasUrlSafeOnlyCharacters
+        ? /^[A-Za-z0-9_-]+$/
+        : /^[A-Za-z0-9+/]+$/;
+    if (!bodyPattern.test(body) ||
+        (padding !== "" && !/^={1,2}$/.test(padding))) {
+        throw invalidResponse();
+    }
+    const requiredPaddingLength = (4 - (body.length % 4)) % 4;
+    if (requiredPaddingLength === 3 ||
+        (padding.length > 0 && padding.length !== requiredPaddingLength)) {
+        throw invalidResponse();
+    }
+    const normalizedBody = body.replaceAll("-", "+").replaceAll("_", "/");
+    const bytes = new Uint8Array(Buffer.from(normalizedBody + "=".repeat(requiredPaddingLength), "base64"));
+    const canonicalPadded = Buffer.from(bytes).toString("base64");
+    const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+    const normalizedInput = normalizedBody + padding;
+    if (normalizedInput !== canonicalPadded &&
+        normalizedInput !== canonicalUnpadded) {
+        throw invalidResponse();
+    }
+    return bytes;
+}
+/** Finite-deadline HTTP client for Relay mesh membership envelopes. */
+export class MeshClient {
+    baseUrl;
+    requestTimeoutMs;
+    constructor(relayUrl, options = {}) {
+        const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+            throw new RangeError("requestTimeoutMs must be finite and positive");
+        }
+        this.baseUrl = relayUrl.replace(/\/+$/, "");
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    async get(hash, since) {
+        const query = since === undefined ? "" : `?since=${encodeURIComponent(since)}`;
+        const url = `${this.baseUrl}/mesh/${encodeURIComponent(hash)}${query}`;
+        const controller = new AbortController();
+        let rejectOnAbort = null;
+        const aborted = new Promise((_resolve, reject) => {
+            rejectOnAbort = () => reject(unavailable());
+            controller.signal.addEventListener("abort", rejectOnAbort, {
+                once: true,
+            });
+        });
+        const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            let response;
+            try {
+                response = await Promise.race([
+                    fetch(url, { method: "GET", signal: controller.signal }),
+                    aborted,
+                ]);
+            }
+            catch (error) {
+                if (error instanceof MeshFetchUnavailableError)
+                    throw error;
+                throw unavailable();
+            }
+            if (response.status === 304 || response.status === 404)
+                return null;
+            if (response.status === 408 ||
+                response.status === 425 ||
+                response.status === 429 ||
+                (response.status >= 500 && response.status <= 599)) {
+                throw unavailable();
+            }
+            if (response.status !== 200)
+                throw invalidResponse();
+            let payload;
+            try {
+                payload = await Promise.race([response.json(), aborted]);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    throw invalidResponse();
+                throw unavailable();
+            }
+            if (!payload ||
+                typeof payload !== "object" ||
+                typeof payload.blob !== "string" ||
+                typeof payload.sig !== "string") {
+                throw invalidResponse();
+            }
+            const body = payload;
+            const blob = decodeStrictBase64(body.blob);
+            const sig = decodeStrictBase64(body.sig);
+            if (blob.length === 0 || sig.length !== ED25519_SIGNATURE_BYTES) {
+                throw invalidResponse();
+            }
+            return { blob, sig };
+        }
+        finally {
+            clearTimeout(timeout);
+            if (rejectOnAbort) {
+                controller.signal.removeEventListener("abort", rejectOnAbort);
+            }
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/mesh/client.js.map

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