@mysten-incubation/memwal-mcp 0.0.13 → 0.0.14-dev.0

package/dist/recovery.js

@@ -0,0 +1,227 @@
+/**
+ * Recovery for a login that was interrupted after the browser registered our
+ * delegate key on-chain but before the callback could save it (WALM-332).
+ *
+ * `loginFlow` write-aheads the keypair to `login-pending.json` before the
+ * browser can act, so the key itself survives losing the process. What does
+ * not survive is the metadata the callback would have carried — `accountId`,
+ * `walletAddress`, `packageId` — and `credentials.json` is not loadable
+ * without them. `GET /api/whoami` closes that gap: the relayer resolves the
+ * account from the delegate key during authentication anyway, so it can hand
+ * back the identity the key already proves.
+ */
+import { randomUUID, createHash } from "node:crypto";
+import { loadCreds, saveCreds, loadPendingLogin, clearPendingLogin } from "./auth.js";
+import { signMessage } from "./crypto.js";
+import { log } from "./logger.js";
+/** Same wall-clock budget as a normal cold-start probe: recovery must never
+ * be the reason a client hangs at startup. */
+const WHOAMI_TIMEOUT_MS = 10_000;
+/** `x-auth-error` value the relayer sets when it could not reach Sui to check
+ *  the key at all. Named in `services/server/src/auth.rs`. */
+const AUTH_UPSTREAM_UNAVAILABLE = "AUTH_UPSTREAM_UNAVAILABLE";
+function isWhoami(o) {
+    if (!o || typeof o !== "object")
+        return false;
+    const w = o;
+    return (typeof w.account_id === "string" &&
+        /^0x[0-9a-fA-F]{64}$/.test(w.account_id) &&
+        typeof w.owner === "string" &&
+        typeof w.package_id === "string");
+}
+/**
+ * Build the exact string the relayer will rebuild and verify against.
+ *
+ * `services/server/src/auth.rs` calls itself the single source of truth for
+ * this format, and it is reproduced here rather than imported because the two
+ * live in different languages. That duplication is the risk: get it subtly
+ * wrong — a trimmed trailing separator, a missing empty field — and every
+ * recovery attempt fails with an opaque 401 that no type checker would have
+ * caught. Exported so a test can pin it against the identical literal asserted
+ * in `routes::accounts::tests::whoami_recovery_request_canonical_message_is_stable`.
+ *
+ * `accountId` is empty for recovery: not knowing it is the reason we are here,
+ * and the server defaults its hint to `""` when the header is absent.
+ */
+export function canonicalRequestMessage(parts) {
+    const { timestamp, method, path, bodyHash, nonce, accountId = "" } = parts;
+    return `${timestamp}.${method}.${path}.${bodyHash}.${nonce}.${accountId}`;
+}
+/** sha256 of an empty body. A GET sends none; the server hashes it anyway. */
+export const EMPTY_BODY_SHA256 = createHash("sha256").update("").digest("hex");
+/**
+ * Ask the relayer who this delegate key belongs to.
+ *
+ * The account id is signed as an empty string and its header omitted, because
+ * not knowing it is the entire reason we are here. The server defaults the
+ * hint to `""` when the header is absent, so both sides build the same
+ * canonical message.
+ *
+ * Returns null only when the request never produced a response at all.
+ */
+async function whoami(relayerUrl, privateKeyHex, publicKeyHex) {
+    const path = "/api/whoami";
+    // SECONDS. `services/server/src/auth.rs` freshness-checks `x-timestamp`
+    // against `chrono::Utc::now().timestamp()` within a drift window of a few
+    // minutes, so a millisecond value (~10^12) is always outside it and every
+    // request 401s with ERR_TIMESTAMP_OUT_OF_BOUNDS.
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const nonce = randomUUID();
+    const message = canonicalRequestMessage({
+        timestamp,
+        method: "GET",
+        path,
+        bodyHash: EMPTY_BODY_SHA256,
+        nonce,
+    });
+    const signature = await signMessage(privateKeyHex, message);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WHOAMI_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const resp = await fetch(`${relayerUrl.replace(/\/+$/, "")}${path}`, {
+            method: "GET",
+            headers: {
+                "x-public-key": publicKeyHex,
+                "x-signature": signature,
+                "x-timestamp": timestamp,
+                "x-nonce": nonce,
+            },
+            signal: controller.signal,
+        });
+        const text = await resp.text();
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            /* non-JSON error page — status is what matters */
+        }
+        return {
+            status: resp.status,
+            body,
+            authError: resp.headers.get("x-auth-error"),
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Attempt to turn a stranded pending login into usable credentials.
+ *
+ * Never throws, and never deletes a record that might still be recoverable —
+ * a stranded key is the user's paid-for property, and the cost of keeping it
+ * around until its TTL is a file that grants nothing.
+ */
+export async function recoverPendingLogin() {
+    const pending = loadPendingLogin();
+    if (!pending)
+        return { outcome: "no-pending" };
+    // Ordering guard. If a later sign-in already succeeded, its credentials
+    // are the user's current intent and must not be rolled back to an older
+    // stranded key. Note this compares against the *pending* record's start
+    // time, so a login begun after the last successful one still wins.
+    const existing = loadCreds();
+    if (existing && Date.parse(existing.createdAt) >= Date.parse(pending.createdAt)) {
+        log.warn("login.pending.superseded", {
+            publicKey: pending.delegatePublicKeyHex,
+        });
+        clearPendingLogin();
+        return { outcome: "superseded", strandedPublicKey: pending.delegatePublicKeyHex };
+    }
+    const res = await whoami(pending.relayerUrl, pending.delegatePrivateKey, pending.delegatePublicKeyHex);
+    if (res === null) {
+        log.warn("login.pending.relayer_unreachable", {
+            publicKey: pending.delegatePublicKeyHex,
+        });
+        return { outcome: "unavailable", strandedPublicKey: pending.delegatePublicKeyHex };
+    }
+    if (res.status !== 200 || !isWhoami(res.body)) {
+        // `rejected` is reserved for the relayer actually denying this
+        // identity, because that is the only outcome whose advice — sign in
+        // again, after removing the key from the dashboard if it was already
+        // registered — is worth giving. During a transient upstream
+        // failure that advice is worse than silence: the key is still good, and
+        // `unavailable` correctly says the next start retries it with no action
+        // from the user.
+        //
+        // So only 401/403 is a denial. A 503 carrying
+        // `x-auth-error: AUTH_UPSTREAM_UNAVAILABLE` is Sui RPC being down, and
+        // 429 / 5xx / a 404 from a relayer too old to serve this route are all
+        // "ask again later" — as is a 200 whose body is not a whoami, which
+        // means we are not talking to the endpoint we think we are.
+        const denied = (res.status === 401 || res.status === 403) &&
+            res.authError !== AUTH_UPSTREAM_UNAVAILABLE;
+        const outcome = denied ? "rejected" : "unavailable";
+        // Non-destructive either way. A 401 is ambiguous even when it IS a
+        // denial: on testnet the registry scan is disabled outright and a
+        // genuinely registered key is refused for want of an x-account-id hint
+        // (services/server/src/auth.rs — "x-account-id is required for
+        // delegate-key authentication on testnet"). Clearing here would destroy
+        // a recoverable key in exactly that environment, so the record is
+        // always left for its TTL to retire.
+        log.warn(`login.pending.${outcome}`, {
+            publicKey: pending.delegatePublicKeyHex,
+            status: res.status,
+            authError: res.authError,
+        });
+        return { outcome, strandedPublicKey: pending.delegatePublicKeyHex };
+    }
+    const creds = {
+        delegatePrivateKey: pending.delegatePrivateKey,
+        delegatePublicKeyHex: pending.delegatePublicKeyHex,
+        delegateAddress: pending.delegateAddress,
+        walletAddress: res.body.owner,
+        accountId: res.body.account_id,
+        packageId: res.body.package_id,
+        relayerUrl: pending.relayerUrl,
+        label: pending.label,
+        createdAt: new Date().toISOString(),
+        version: 1,
+    };
+    saveCreds(creds);
+    clearPendingLogin();
+    log.info("login.pending.recovered", {
+        accountId: creds.accountId,
+        delegateAddress: creds.delegateAddress,
+    });
+    return { outcome: "recovered", credentials: creds };
+}
+/**
+ * The line to show the user when a stranded key could not be reclaimed.
+ *
+ * Names the key so the user can find the registration they paid for in the
+ * dashboard. Signing in again reuses this key, and the dashboard's
+ * `add_delegate_key` aborts on one that is already registered, so a key the
+ * user approved has to be removed there before a new sign-in can finish. A
+ * user told only "login failed" can do neither.
+ */
+export function formatStrandedLoginNotice(result) {
+    if (!result.strandedPublicKey)
+        return null;
+    if (result.outcome === "recovered" || result.outcome === "no-pending")
+        return null;
+    const key = result.strandedPublicKey;
+    const lines = [
+        `⚠️  Your last Walrus Memory sign-in did not finish.`,
+        ``,
+        `A delegate key may have been registered on-chain without being saved locally:`,
+        `  ${key}`,
+        ``,
+    ];
+    if (result.outcome === "superseded") {
+        lines.push(`You have since signed in again, so your current credentials are fine.`, `Revoke the key above from the dashboard if you don't recognise it.`);
+    }
+    else if (result.outcome === "unavailable") {
+        lines.push(`The relayer could not be reached to check. This will be retried on the`, `next start — no action needed yet.`);
+    }
+    else {
+        lines.push(`The relayer did not accept it. If you never approved the wallet step, run`, `\`memwal_login\`: it reuses this key. If you did, remove the key above from`, `the dashboard first and then run \`memwal_login\`, because the wallet step`, `cannot register a key that is already there. This is expected on Testnet,`, `where the relayer cannot confirm a registered key at start.`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAqBlC;8CAC8C;AAC9C,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC;8DAC8D;AAC9D,MAAM,yBAAyB,GAAG,2BAA2B,CAAC;AAQ9D,SAAS,QAAQ,CAAC,CAAU;IACxB,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,CAAC,GAAG,CAA4B,CAAC;IACvC,OAAO,CACH,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;QAChC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;QACxC,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CACnC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAOvC;IACG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC;IAC3E,OAAO,GAAG,SAAS,IAAI,MAAM,IAAI,IAAI,IAAI,QAAQ,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;AAC9E,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAE/E;;;;;;;;;GASG;AACH,KAAK,UAAU,MAAM,CACjB,UAAkB,EAClB,aAAqB,EACrB,YAAoB;IAEpB,MAAM,IAAI,GAAG,aAAa,CAAC;IAC3B,wEAAwE;IACxE,0EAA0E;IAC1E,0EAA0E;IAC1E,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,uBAAuB,CAAC;QACpC,SAAS;QACT,MAAM,EAAE,KAAK;QACb,IAAI;QACJ,QAAQ,EAAE,iBAAiB;QAC3B,KAAK;KACR,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAE5D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,iBAAiB,CAAC,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;YACjE,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACL,cAAc,EAAE,YAAY;gBAC5B,aAAa,EAAE,SAAS;gBACxB,aAAa,EAAE,SAAS;gBACxB,SAAS,EAAE,KAAK;aACnB;YACD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC5B,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,IAAI,GAAY,IAAI,CAAC;QACzB,IAAI,CAAC;YACD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACL,kDAAkD;QACtD,CAAC;QACD,OAAO;YACH,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;SAC9C,CAAC;IACN,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;YAAS,CAAC;QACP,YAAY,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACrC,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAE/C,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;IAC7B,IAAI,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9E,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE;YACjC,SAAS,EAAE,OAAO,CAAC,oBAAoB;SAC1C,CAAC,CAAC;QACH,iBAAiB,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;IACtF,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,MAAM,CACpB,OAAO,CAAC,UAAU,EAClB,OAAO,CAAC,kBAAkB,EAC1B,OAAO,CAAC,oBAAoB,CAC/B,CAAC;IAEF,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,mCAAmC,EAAE;YAC1C,SAAS,EAAE,OAAO,CAAC,oBAAoB;SAC1C,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;IACvF,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,+DAA+D;QAC/D,oEAAoE;QACpE,qEAAqE;QACrE,4DAA4D;QAC5D,wEAAwE;QACxE,wEAAwE;QACxE,iBAAiB;QACjB,EAAE;QACF,8CAA8C;QAC9C,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,4DAA4D;QAC5D,MAAM,MAAM,GACR,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC;YAC1C,GAAG,CAAC,SAAS,KAAK,yBAAyB,CAAC;QAChD,MAAM,OAAO,GAAoB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC;QACrE,mEAAmE;QACnE,kEAAkE;QAClE,uEAAuE;QACvE,+DAA+D;QAC/D,wEAAwE;QACxE,kEAAkE;QAClE,qCAAqC;QACrC,GAAG,CAAC,IAAI,CAAC,iBAAiB,OAAO,EAAE,EAAE;YACjC,SAAS,EAAE,OAAO,CAAC,oBAAoB;YACvC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS,EAAE,GAAG,CAAC,SAAS;SAC3B,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,KAAK,GAAsB;QAC7B,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,aAAa,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;QAC7B,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU;QAC9B,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,CAAC;KACb,CAAC;IACF,SAAS,CAAC,KAAK,CAAC,CAAC;IACjB,iBAAiB,EAAE,CAAC;IACpB,GAAG,CAAC,IAAI,CAAC,yBAAyB,EAAE;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,eAAe,EAAE,KAAK,CAAC,eAAe;KACzC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAsB;IAC5D,IAAI,CAAC,MAAM,CAAC,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW,IAAI,MAAM,CAAC,OAAO,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAEnF,MAAM,GAAG,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACrC,MAAM,KAAK,GAAG;QACV,qDAAqD;QACrD,EAAE;QACF,+EAA+E;QAC/E,KAAK,GAAG,EAAE;QACV,EAAE;KACL,CAAC;IACF,IAAI,MAAM,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CACN,uEAAuE,EACvE,oEAAoE,CACvE,CAAC;IACN,CAAC;SAAM,IAAI,MAAM,CAAC,OAAO,KAAK,aAAa,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CACN,wEAAwE,EACxE,oCAAoC,CACvC,CAAC;IACN,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CACN,2EAA2E,EAC3E,6EAA6E,EAC7E,4EAA4E,EAC5E,2EAA2E,EAC3E,6DAA6D,CAChE,CAAC;IACN,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/dist/streamable.d.ts

@@ -0,0 +1,48 @@
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import type { MemWalCredentials } from "./auth.js";
+/** Which relayer transport the bridge dials. */
+export type TransportKind = "sse" | "http";
+/**
+ * Resolve the transport from `MEMWAL_MCP_TRANSPORT`.
+ *
+ * Defaults to `sse`, the transport every released bridge has used. Streamable
+ * HTTP is opt-in until it has production mileage: this runs on users' machines
+ * against their real memories, so the new path proves itself before it becomes
+ * the one that runs by default.
+ *
+ * An unrecognised value falls back rather than throwing — a typo in a user's
+ * MCP config must not stop their memory from working.
+ */
+export declare function resolveTransport(raw: string | undefined): TransportKind;
+/**
+ * The Streamable HTTP endpoint for a relayer base URL.
+ *
+ * `/api/mcp` — the same base the SSE transport hangs `/api/mcp/sse` and
+ * `/api/mcp/messages` off, minus the split.
+ */
+export declare function streamableUrl(relayerUrl: string): string;
+/**
+ * A live relayer session. Deliberately the same shape the SSE handshake
+ * returns, so `runBridge` can hold either without branching on transport
+ * everywhere it forwards a message.
+ */
+export interface RelaySession {
+    /** Endpoint this session talks to. Logging only. */
+    postUrl: string;
+    /**
+     * Forward one JSON-RPC message. Resolves with an HTTP-ish status the
+     * caller can act on: 200 for accepted, 404 when the relayer says the
+     * session does not exist (the message provably did not run, so the
+     * caller may retry it without risking a duplicate write).
+     */
+    send(msg: JSONRPCMessage, 
+    /** Unused here — headers are bound when the session opens. Present so
+     * this matches the SSE handshake's `send`, which signs per POST. */
+    creds?: MemWalCredentials, extra?: Record<string, string>): Promise<number>;
+    /** Incoming messages from the relayer. */
+    iter: AsyncIterator<JSONRPCMessage>;
+    /** Tear the session down. */
+    abort: () => void;
+}
+export declare function openStreamableSession(relayerUrl: string, creds: MemWalCredentials, extraHeaders?: Record<string, string>): Promise<RelaySession>;
+//# sourceMappingURL=streamable.d.ts.map

package/dist/streamable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable.d.ts","sourceRoot":"","sources":["../src/streamable.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CASvE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CACA,GAAG,EAAE,cAAc;IACnB;wEACoE;IACpE,KAAK,CAAC,EAAE,iBAAiB,EACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACpC,6BAA6B;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAC;CACrB;AAQD,wBAAsB,qBAAqB,CACvC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,iBAAiB,EACxB,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC1C,OAAO,CAAC,YAAY,CAAC,CA+EvB"}

package/dist/streamable.js

@@ -0,0 +1,136 @@
+/**
+ * Streamable HTTP transport for the stdio bridge.
+ *
+ * The legacy transport splits a call in two: POST to `/api/mcp/messages`, then
+ * wait for the reply to arrive on a separate `/api/mcp/sse` stream. Everything
+ * expensive in `bridge.ts` follows from that split — the `inFlight` map, the
+ * `sent` flag, the 404-means-never-ran reset, the idle watchdog, and the
+ * replay-on-reconnect path — because a POST can succeed while its reply is
+ * lost, and the bridge cannot tell that from a call still running.
+ *
+ * Streamable HTTP (MCP 2025-06) collapses that: one endpoint, and the reply
+ * comes back on the same request. The relayer has served it since
+ * `mcp_proxy.rs:751` ("Single endpoint that supersedes the SSE+POST split");
+ * only the bridge was still on the old transport.
+ *
+ * This module wraps the MCP SDK's own client transport rather than hand-rolling
+ * the protocol: session-id round-tripping, the optional SSE upgrade on a POST
+ * response, and resumption tokens are all spec details that are easy to get
+ * subtly wrong and that the SDK already implements.
+ */
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { log } from "./logger.js";
+/**
+ * Resolve the transport from `MEMWAL_MCP_TRANSPORT`.
+ *
+ * Defaults to `sse`, the transport every released bridge has used. Streamable
+ * HTTP is opt-in until it has production mileage: this runs on users' machines
+ * against their real memories, so the new path proves itself before it becomes
+ * the one that runs by default.
+ *
+ * An unrecognised value falls back rather than throwing — a typo in a user's
+ * MCP config must not stop their memory from working.
+ */
+export function resolveTransport(raw) {
+    const value = raw?.trim().toLowerCase();
+    if (!value)
+        return "sse";
+    if (value === "http" || value === "streamable" || value === "streamable-http") {
+        return "http";
+    }
+    if (value === "sse")
+        return "sse";
+    log.warn("bridge.transport_unrecognized", { value, using: "sse" });
+    return "sse";
+}
+/**
+ * The Streamable HTTP endpoint for a relayer base URL.
+ *
+ * `/api/mcp` — the same base the SSE transport hangs `/api/mcp/sse` and
+ * `/api/mcp/messages` off, minus the split.
+ */
+export function streamableUrl(relayerUrl) {
+    return `${relayerUrl.replace(/\/+$/, "")}/api/mcp`;
+}
+/** HTTP status carried on the SDK's transport error, when it has one. */
+function statusOf(err) {
+    const code = err?.code;
+    return typeof code === "number" ? code : 0;
+}
+export async function openStreamableSession(relayerUrl, creds, extraHeaders = {}) {
+    const url = streamableUrl(relayerUrl);
+    // Queue + waiter rather than an event emitter, so a message that arrives
+    // before `runBridge` pulls from the iterator is buffered instead of
+    // dropped. The SSE path does the same thing for the same reason.
+    const queue = [];
+    let wake = null;
+    let closed = false;
+    const push = (msg) => {
+        queue.push(msg);
+        const resume = wake;
+        wake = null;
+        resume?.();
+    };
+    const finish = () => {
+        closed = true;
+        const resume = wake;
+        wake = null;
+        resume?.();
+    };
+    const transport = new StreamableHTTPClientTransport(new URL(url), {
+        requestInit: {
+            headers: {
+                authorization: `Bearer ${creds.delegatePrivateKey}`,
+                "x-memwal-account-id": creds.accountId,
+                ...extraHeaders,
+            },
+        },
+    });
+    transport.onmessage = push;
+    transport.onclose = finish;
+    transport.onerror = (err) => {
+        log.warn("bridge.streamable_error", { err: String(err) });
+        // Not `finish()` — the SDK transport reconnects its own stream, and
+        // tearing the session down on a transient read error is what the SSE
+        // watchdog did wrong.
+    };
+    await transport.start();
+    const iter = {
+        async next() {
+            while (queue.length === 0) {
+                if (closed)
+                    return { value: undefined, done: true };
+                await new Promise((resolve) => (wake = resolve));
+            }
+            return { value: queue.shift(), done: false };
+        },
+    };
+    return {
+        postUrl: url,
+        async send(msg) {
+            try {
+                await transport.send(msg);
+                return 200;
+            }
+            catch (err) {
+                const status = statusOf(err);
+                log.warn("bridge.streamable_send_failed", {
+                    status,
+                    err: String(err),
+                });
+                // Surface the status rather than throwing: `postIfCurrent`
+                // routes on it, and a 404 specifically means the message was
+                // discarded rather than run.
+                return status;
+            }
+        },
+        iter,
+        abort: () => {
+            void transport.close().catch(() => {
+                /* already gone */
+            });
+            finish();
+        },
+    };
+}
+//# sourceMappingURL=streamable.js.map

package/dist/streamable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable.js","sourceRoot":"","sources":["../src/streamable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAInG,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAKlC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAuB;IACpD,MAAM,KAAK,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,YAAY,IAAI,KAAK,KAAK,iBAAiB,EAAE,CAAC;QAC5E,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAClC,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC5C,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC;AACvD,CAAC;AA6BD,yEAAyE;AACzE,SAAS,QAAQ,CAAC,GAAY;IAC1B,MAAM,IAAI,GAAI,GAAiC,EAAE,IAAI,CAAC;IACtD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACvC,UAAkB,EAClB,KAAwB,EACxB,eAAuC,EAAE;IAEzC,MAAM,GAAG,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAEtC,yEAAyE;IACzE,oEAAoE;IACpE,iEAAiE;IACjE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,IAAI,GAAG,CAAC,GAAmB,EAAE,EAAE;QACjC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,GAAG,IAAI,CAAC;QACZ,MAAM,EAAE,EAAE,CAAC;IACf,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,GAAG,EAAE;QAChB,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,GAAG,IAAI,CAAC;QACZ,MAAM,EAAE,EAAE,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE;QAC9D,WAAW,EAAE;YACT,OAAO,EAAE;gBACL,aAAa,EAAE,UAAU,KAAK,CAAC,kBAAkB,EAAE;gBACnD,qBAAqB,EAAE,KAAK,CAAC,SAAS;gBACtC,GAAG,YAAY;aAClB;SACJ;KACJ,CAAC,CAAC;IAEH,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC;IAC3B,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAC3B,SAAS,CAAC,OAAO,GAAG,CAAC,GAAG,EAAE,EAAE;QACxB,GAAG,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1D,oEAAoE;QACpE,qEAAqE;QACrE,sBAAsB;IAC1B,CAAC,CAAC;IAEF,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;IAExB,MAAM,IAAI,GAAkC;QACxC,KAAK,CAAC,IAAI;YACN,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,IAAI,MAAM;oBAAE,OAAO,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBAC7D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;YAC3D,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAClD,CAAC;KACJ,CAAC;IAEF,OAAO;QACH,OAAO,EAAE,GAAG;QACZ,KAAK,CAAC,IAAI,CAAC,GAAG;YACV,IAAI,CAAC;gBACD,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC1B,OAAO,GAAG,CAAC;YACf,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAC7B,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE;oBACtC,MAAM;oBACN,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC;iBACnB,CAAC,CAAC;gBACH,2DAA2D;gBAC3D,6DAA6D;gBAC7D,6BAA6B;gBAC7B,OAAO,MAAM,CAAC;YAClB,CAAC;QACL,CAAC;QACD,IAAI;QACJ,KAAK,EAAE,GAAG,EAAE;YACR,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC9B,kBAAkB;YACtB,CAAC,CAAC,CAAC;YACH,MAAM,EAAE,CAAC;QACb,CAAC;KACJ,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten-incubation/memwal-mcp",
-  "version": "0.0.13",
+  "version": "0.0.14-dev.0",
   "description": "Walrus Memory MCP client — single-binary stdio MCP server that bridges Cursor / Claude Desktop / Antigravity / Claude Code to the Walrus Memory relayer. Handles browser-based wallet login on first run.",
   "type": "module",
   "engines": {