@masons/agent-network 0.5.13 → 0.5.15

package/dist/cli-setup.js

@@ -1,776 +1,164 @@
-/**
- * CLI Login Path — Stripe-style browser-mediated loopback handoff.
- *
- * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
- *     api.registerChannel({ plugin: { ..., auth: { login } } })
- *
- * Invoked by `openclaw channels login --channel agent-network`. CLI dispatch
- * at `dist/channels-cli-Cc40S0aS.js:85` reads `plugin.auth?.login` and throws
- * `"Channel ... does not support login"` if absent. See WhatsApp + Feishu
- * bundled extensions for reference implementations of the same contract.
- *
- * Flow (W4 PR 3 — `loopbackHandoffFlow`):
- *
- *   1. Bind a one-shot HTTP listener on `127.0.0.1:0` (OS-assigned ephemeral
- *      port). The listener serves a single `POST /handoff` plus the matching
- *      CORS preflight, then closes.
- *   2. Generate a 24-byte (32-char base64url) URL-safe random nonce. The
- *      nonce travels in the URL fragment (`#nonce=…`), never the query
- *      string — fragments do not reach `apps/web` access logs nor referer
- *      headers (Alt W4-B2 lock).
- *   3. Open the user's browser to the handoff URL (no-handle path uses
- *      `${idpBaseUrl}/console/handoff?port=<port>#nonce=<nonce>`; with
- *      `--handle` the per-handle deep-link variant is the entry).
- *   4. The user authenticates against Better Auth on `apps/web`, picks (or
- *      creates) an agent, and the page POSTs `{token, agent, key, nonce}`
- *      to the listener. The listener verifies the body's `nonce` matches
- *      the value it placed in the fragment, accepts the token, and closes.
- *   5. Persist `{connectorUrl, token}` to `openclaw.json` via
- *      `writeCredentials()`. `connectorUrl` is derived from `apiHost`
- *      (`wss://<apiHost>/gateway`) for cloud / preview deployments; self-
- *      hosted users keep an explicit `connectorUrl` in their `openclaw.json`
- *      and the legacy value is preserved across the handoff (see
- *      `loadExistingConnectorUrl()`).
- *
- * Why move off device flow:
- *
- *   - One step shorter (no `user_code` to type into the browser).
- *   - No periodic IdP polling (was 5s default, 5+s on `slow_down`).
- *   - Browser remains fully authenticated across login and key issuance —
- *     same Better Auth session is reused, so the user never re-types their
- *     password mid-flow.
- *   - The runtime API key carrier (`masons_rt_…`) replaces the legacy
- *     connector-minted `sk-…` carrier; W4 PR 1 substrate plus the connector
- *     mirror wiring earlier in this PR make both carriers verifiable through
- *     plugin v0.5.13's life until the W6 cleanup retires the legacy path.
- *
- * The legacy device-flow helpers (`deviceCodeFlow`, `pollUntilAuthorized`,
- * `agentSetup`, `createAgentLoop`) remain in this file as
- * `@deprecated` references for the W6 cleanup window. They have no call
- * site after the migration and should not be invoked by any new code.
- *
- * See #1264 for original design rationale (single-driver Node semantic —
- * re-running this flow rotates the runtime key and evicts any previously-
- * connected Runtime); see the W4 strategic-pass at
- * `#1466 issuecomment-4362892782` for the loopback handoff lock.
- */
-import { randomBytes } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { createServer, } from "node:http";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { cancel, confirm as clackConfirm, select as clackSelect, text as clackText, isCancel, } from "@clack/prompts";
-import { writeCredentials } from "./config.js";
-import { DEFAULT_API_HOST, onboard, PlatformApiError, } from "./platform-client.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * Better Auth IdP base URL. Default targets the preview environment.
- *
- * TODO: flip to the production URL when W8 (api.masons.ai consolidation)
- * lands. Plugins shipped with this default before that flip will still
- * work — the user can override by setting `idpBaseUrl` in their
- * `openclaw.json` channel config (or by re-running setup which writes
- * whatever is current).
- */
+import { createDecipheriv, constants as cryptoConstants, generateKeyPairSync, privateDecrypt, } from "node:crypto";
+import { readExistingConnectorUrl, writeCredentials } from "./config.js";
+import { DEFAULT_API_HOST, DEFAULT_CONNECTOR_URL, PlatformApiError, } from "./platform-client.js";
 const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
-/**
- * OAuth client_id registered for OpenClaw at the IdP — see
- * `apps/web/scripts/seed.ts`. Hardcoded because there's only one OpenClaw
- * client today; if multiple wrappers (e.g. self-hosted vs Claude Desktop
- * variant) ever need distinct client_ids, expose this via the channel
- * config schema.
- */
-const OAUTH_CLIENT_ID = "openclaw";
-/**
- * Scopes requested at device-flow initiation. `openid` + `profile` + `email`
- * are the standard OIDC scopes; `offline_access` requests a refresh token
- * (Better Auth uses session tokens here, not OAuth opaque tokens — the
- * scope is mostly indicative). Stays in sync with the scopes registered on
- * the `oauthProvider` plugin at apps/web/lib/auth.ts.
- */
-const SCOPE = "openid profile email offline_access";
-/** Default polling interval if the IdP does not return one. */
-const DEFAULT_POLL_INTERVAL_S = 5;
-const CREATE_NEW_OPTION = "Create new agent";
-// Handle pre-validation regex — strict subset of the server's authoritative
-// `validateHandle` (packages/db/src/utils/handle-validation.ts:3). Used to
-// fail-fast in the terminal before round-tripping the server. Kept inline
-// because the published npm plugin can't import @workspace/db.
-//
-// Server contract: `/^[a-z][a-z0-9_-]{2,14}$/` against the lowercased input.
-// MUST be a strict subset (false-negatives OK, false-positives forbidden) —
-// otherwise the user sees "passed client check" then "server rejected" for
-// the same input, which is confusing.
-//
-// Reserved-handle check (e.g., "masons", "openclaw") is server-only — too
-// volatile for the plugin to track; the round-trip is acceptable for that.
 const HANDLE_REGEX = /^[a-z][a-z0-9_-]{2,14}$/;
-/**
- * Path under the loopback origin where `apps/web` POSTs the handoff payload.
- * The listener accepts a CORS preflight on the same path. Pinning to a
- * single path lets the listener reject any other request URL — defense in
- * depth against a malicious local process binding the same port between
- * the listener `listen()` and the browser POST.
- */
-const HANDOFF_PATH = "/handoff";
-/**
- * Hard cap on how long the listener waits for the browser POST. Long
- * enough for the user to walk through sign-in + agent picker + handoff,
- * short enough that a wedged listener doesn't sit on a port forever.
- */
 const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
-/** Bytes of entropy in the one-time fragment nonce. */
-const HANDOFF_NONCE_BYTES = 24;
-/**
- * Run the Stripe-style loopback handoff. Returns the runtime API key
- * + the agent identity the browser issued it for. The listener stops
- * after a single successful POST; subsequent reuse of the URL is
- * rejected.
- *
- * `channelInput` is the optional argument from
- * `openclaw channels login --channel agent-network -- <input>`. When
- * the input parses as a handle (`^[a-z][a-z0-9_-]{2,14}$`) the flow
- * uses the per-handle deep-link entry; otherwise it falls back to the
- * picker. Anything that isn't a handle prints a warning and falls
- * through to the picker.
- */
-async function loopbackHandoffFlow(idpBaseUrl, runtime, channelInput) {
-    const nonce = randomBytes(HANDOFF_NONCE_BYTES).toString("base64url");
-    // Bind the listener BEFORE printing the URL — the URL must carry the
-    // OS-assigned port and the listener must be ready to accept the POST
-    // before the user has any chance of opening the link.
-    const { server, port } = await bindLoopbackListener();
-    // The Promise we hand the inner request handler — resolved on a
-    // valid POST. The reject path is owned by the timeout race below
-    // (`Promise.race`); the request handler never produces a "fatal"
-    // error worth rejecting the outer promise — invalid bodies / wrong
-    // nonces / duplicate posts respond 4xx and let the listener keep
-    // running until the timeout or a valid POST wins.
-    let resolveResult = null;
-    const handoffPromise = new Promise((res) => {
-        resolveResult = res;
+const HANDOFF_POLL_INTERVAL_MS = 2000;
+class SetupFlowError extends Error {
+}
+async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInput) {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
     });
-    const browserOriginAllowList = computeAllowedBrowserOrigins(idpBaseUrl);
-    let dispatched = false;
-    server.on("request", (req, res) => {
-        // Two distinct security boundaries are layered on this listener and
-        // it's worth keeping them straight:
-        //
-        //   - The browser-origin allow-list (`computeAllowedBrowserOrigins`
-        //     + ACAO echo) closes the cross-origin browser-scrape surface
-        //     where a malicious page in the user's already-authenticated
-        //     browser tries to read the listener's response. ACAO is what
-        //     stops the browser from delivering the response to a non-
-        //     apps/web origin.
-        //   - The fragment nonce closes the local-process-race surface
-        //     where another process on the same machine binds the same
-        //     port between `server.listen()` and the browser POST. A
-        //     malicious local process can fake any `Origin` header at
-        //     will, but it cannot guess the 24-byte URL-fragment nonce
-        //     the listener generated.
-        //
-        // CORS preflight (`OPTIONS /handoff`) is browser-only — non-browser
-        // local processes do not preflight. We answer 204 with ACAO pinned
-        // to the request's origin if it is in the allow-list; otherwise
-        // 403 with no headers (browser blocks the subsequent POST).
-        const origin = req.headers.origin ?? "";
-        if (req.method === "OPTIONS" && req.url === HANDOFF_PATH) {
-            if (browserOriginAllowList.has(origin)) {
-                res.writeHead(204, {
-                    "Access-Control-Allow-Origin": origin,
-                    "Access-Control-Allow-Methods": "POST, OPTIONS",
-                    "Access-Control-Allow-Headers": "content-type",
-                    "Access-Control-Max-Age": "60",
-                });
-            }
-            else {
-                res.writeHead(403);
-            }
-            res.end();
-            return;
+    const cliPubkeySpki = publicKey
+        .export({ type: "spki", format: "der" })
+        .toString("base64url");
+    const apiBase = normalizeHttpBase(apiHost);
+    let session_id;
+    try {
+        const initRes = await fetch(`${apiBase}/v1/cli-handoff/init`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ cli_pubkey: cliPubkeySpki }),
+        });
+        if (!initRes.ok) {
+            throw new SetupFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
         }
-        if (req.method !== "POST" || req.url !== HANDOFF_PATH) {
-            res.writeHead(404);
-            res.end();
-            return;
+        const initBody = (await initRes.json());
+        if (typeof initBody.session_id !== "string" ||
+            initBody.session_id.length === 0) {
+            throw new SetupFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
         }
-        if (!browserOriginAllowList.has(origin)) {
-            res.writeHead(403);
-            res.end();
-            return;
-        }
-        // Read the POST body with a hard cap. The expected payload is
-        // ~1 KB; reject anything larger as protection against a wedged
-        // attacker streaming bytes into the listener.
-        const MAX_BODY = 64 * 1024;
-        const chunks = [];
-        let total = 0;
-        let aborted = false;
-        req.on("data", (chunk) => {
-            if (aborted)
-                return;
-            total += chunk.length;
-            if (total > MAX_BODY) {
-                aborted = true;
-                // Origin already validated against the allow-list above; ACAO
-                // is therefore safe to echo and lets the browser surface the
-                // 413 status to the page (rather than an opaque CORS error).
-                res.writeHead(413, { "Access-Control-Allow-Origin": origin });
-                res.end();
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => {
-            if (aborted)
-                return;
-            let parsed = null;
-            try {
-                parsed = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
-            }
-            catch {
-                res.writeHead(400, { "Access-Control-Allow-Origin": origin });
-                res.end();
-                return;
-            }
-            if (!parsed ||
-                typeof parsed.token !== "string" ||
-                typeof parsed.nonce !== "string" ||
-                !parsed.agent ||
-                typeof parsed.agent.agentId !== "string" ||
-                typeof parsed.agent.handle !== "string") {
-                res.writeHead(400, { "Access-Control-Allow-Origin": origin });
-                res.end();
-                return;
-            }
-            if (parsed.nonce !== nonce) {
-                // Wrong nonce — possibly a stale browser tab from an earlier
-                // login attempt that lost the race for the port, or a
-                // malicious local process. Reject without revealing why.
-                res.writeHead(403, { "Access-Control-Allow-Origin": origin });
-                res.end();
-                return;
-            }
-            if (dispatched) {
-                // The listener is one-shot. Any subsequent POST after the
-                // first valid one is suspect — the browser succeeded once
-                // already; nothing else should be hitting this URL.
-                res.writeHead(409, { "Access-Control-Allow-Origin": origin });
-                res.end();
-                return;
-            }
-            dispatched = true;
-            res.writeHead(200, { "Access-Control-Allow-Origin": origin });
-            res.end();
-            resolveResult?.({
-                token: parsed.token,
-                agent: {
-                    agentId: parsed.agent.agentId,
-                    handle: parsed.agent.handle,
-                    name: typeof parsed.agent.name === "string"
-                        ? parsed.agent.name
-                        : parsed.agent.handle,
-                },
-            });
-        });
-        req.on("error", () => {
-            if (!dispatched) {
-                // Connection-level error before we got a body. Log nothing —
-                // half-formed requests are noisy and usually irrelevant.
-            }
-        });
-    });
-    // The handoff URL the user (or `open`/`xdg-open`) navigates to. The
-    // nonce sits in the fragment so it never lands in apps/web access
-    // logs nor referer headers.
+        session_id = initBody.session_id;
+    }
+    catch (err) {
+        if (err instanceof SetupFlowError)
+            throw err;
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new SetupFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
+    }
     const handle = parseHandleFromInput(channelInput);
-    const baseUrl = handle
-        ? `${idpBaseUrl}/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
-        : `${idpBaseUrl}/console/handoff`;
-    const url = `${baseUrl}?port=${port}#nonce=${nonce}`;
+    const handoffPath = handle
+        ? `/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
+        : `/console/handoff`;
+    const handoffUrl = `${idpBaseUrl}${handoffPath}?session=${encodeURIComponent(session_id)}`;
     runtime.writeStdout([
         "",
-        "Open this link in your browser to finish the handoff:",
-        `  ${url}`,
+        "Open this link in your browser to finish setup:",
+        `  ${handoffUrl}`,
         "",
-        "Waiting for the browser to deliver the runtime key…",
+        "Waiting for the runtime key to be issued and delivered…",
         "",
     ].join("\n"));
-    // Best-effort spawn `open` / `xdg-open` / `start` so the browser
-    // pops automatically. Failure is non-fatal — the printed URL is the
-    // documented fallback.
-    void tryOpenBrowser(url, runtime);
-    // Race the listener against the timeout. Unwrap whichever wins.
-    const timeoutPromise = new Promise((_, rej) => {
-        setTimeout(() => {
-            rej(new DeviceFlowError("Loopback handoff timed out without receiving the runtime key. " +
-                "Re-run setup; if your browser cannot reach 127.0.0.1, copy the " +
-                "URL into a browser on the same machine."));
-        }, HANDOFF_TIMEOUT_MS).unref();
-    });
-    try {
-        return await Promise.race([handoffPromise, timeoutPromise]);
-    }
-    finally {
-        // Closing the listener after the first valid POST mirrors the
-        // "one-shot accept" discipline. Outstanding sockets (e.g., a
-        // preflight that arrived after the dispatch) are dropped on close.
-        server.close();
-    }
-}
-async function bindLoopbackListener() {
-    return await new Promise((resolve, reject) => {
-        const server = createServer();
-        server.on("error", reject);
-        // `127.0.0.1` (not `0.0.0.0`) — only the local machine can reach
-        // the listener. Browsers permit cross-origin fetch from HTTPS to
-        // 127.0.0.1 because it is a "potentially trustworthy origin"
-        // (W3C secure-contexts spec).
-        server.listen(0, "127.0.0.1", () => {
-            const addr = server.address();
-            if (!addr || typeof addr === "string") {
-                reject(new Error("Failed to bind loopback listener — no address"));
-                return;
-            }
-            resolve({ server, port: addr.port });
-        });
-    });
-}
-/**
- * Compute the allowed browser origins for the cross-origin POST. The
- * allow-list pins to the exact apps/web origin (scheme + host + port)
- * so a local malicious process bound to a different origin cannot
- * scrape the listener even if it happens to discover the port.
- *
- * Both the bare `idpBaseUrl` and (for development) `http://localhost:3007`
- * are allowed when `idpBaseUrl` resolves to a localhost hostname so the
- * `pnpm dev` workflow works without flag-flipping.
- */
-function computeAllowedBrowserOrigins(idpBaseUrl) {
-    const origins = new Set();
+    const envelope = await pollForCompletion(apiBase, session_id);
+    let payload;
     try {
-        const url = new URL(idpBaseUrl);
-        origins.add(url.origin);
-        if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
-            origins.add("http://localhost:3007");
-            origins.add("http://127.0.0.1:3007");
-        }
-    }
-    catch {
-        // Malformed idpBaseUrl — fall through with an empty allow-list.
-        // Every browser POST will be 403'd; the user sees a timeout.
-    }
-    return origins;
-}
-/**
- * Best-effort browser launch. Returns immediately; failures are
- * surfaced as a quiet log rather than a thrown error — the user has
- * the printed URL as a documented fallback.
- */
-async function tryOpenBrowser(url, runtime) {
-    const { spawn } = await import("node:child_process");
-    const platform = process.platform;
-    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-    try {
-        const child = spawn(cmd, args, {
-            detached: true,
-            stdio: "ignore",
-        });
-        child.on("error", (err) => {
-            runtime.log(`(could not auto-open browser: ${err.message} — copy the link above)`);
-        });
-        child.unref();
+        payload = decryptBridgeEnvelope(privateKey, envelope);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : "unknown error";
-        runtime.log(`(could not auto-open browser: ${message} — copy the link above)`);
+        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
     }
-}
-/**
- * Parse `channelInput` as a handle. Returns the lowercased handle on
- * match, `undefined` otherwise. Mirrors the `HANDLE_REGEX` used in the
- * legacy device flow's create form.
- */
-function parseHandleFromInput(input) {
-    if (typeof input !== "string")
-        return undefined;
-    const trimmed = input.trim().toLowerCase();
-    if (!HANDLE_REGEX.test(trimmed))
-        return undefined;
-    return trimmed;
-}
-/**
- * Read the existing `accounts.default.connectorUrl` from `openclaw.json`
- * if present. Used to preserve the self-hosted user's deployment-specific
- * connector URL across the handoff — the loopback flow does not learn
- * it from `apps/api` (issuance is decoupled from connector topology),
- * but we don't want to clobber a user-set value.
- *
- * Returns `undefined` when the file is absent, malformed, or doesn't
- * contain a connectorUrl. Caller falls back to `deriveCloudConnectorUrl`.
- */
-async function loadExistingConnectorUrl() {
-    const home = process.env.OPENCLAW_HOME || join(homedir(), ".openclaw");
-    const path = join(home, "openclaw.json");
-    try {
-        const raw = await readFile(path, "utf-8");
-        const config = JSON.parse(raw);
-        const channels = config.channels;
-        const network = channels?.["agent-network"];
-        const accounts = network?.accounts;
-        const def = accounts?.default;
-        const value = def?.connectorUrl;
-        if (typeof value === "string" && value.length > 0)
-            return value;
-    }
-    catch {
-        // file missing / malformed / unreadable → fall through to derivation
+    if (typeof payload.token !== "string" ||
+        !payload.token.startsWith("masons_rt_v1_") ||
+        typeof payload.agent?.handle !== "string" ||
+        typeof payload.agent?.agentId !== "string") {
+        throw new SetupFlowError("Handoff payload is missing required fields. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
     }
-    return undefined;
-}
-/**
- * Derive the WebSocket connector URL from the apiHost. Matches the
- * connector's `CONNECTOR_PLUGIN_URL` env default
- * (`wss://<host>/gateway`) for cloud and preview deployments.
- *
- * Self-hosted users running a non-standard topology should set
- * `accounts.default.connectorUrl` explicitly in `openclaw.json`; the
- * loopback flow preserves that value via `loadExistingConnectorUrl`.
- */
-function deriveCloudConnectorUrl(apiHost) {
-    // Strip any incidental scheme so we never produce `wss://https://…`.
-    const host = apiHost.replace(/^https?:\/\//, "");
-    return `wss://${host}/gateway`;
-}
-class DeviceFlowError extends Error {
-}
-class DeviceFlowExpired extends Error {
-}
-/**
- * User pressed Ctrl+C at any prompter step. Subclass of `DeviceFlowError`
- * so the existing throw/catch chain still works, but distinguished so the
- * `login` handler can skip the redundant `runtime.error` call (clack's
- * `cancel()` already emitted the canonical "cancelled" UI).
- */
-class CancelError extends DeviceFlowError {
+    return {
+        token: payload.token,
+        agent: {
+            agentId: payload.agent.agentId,
+            handle: payload.agent.handle,
+            name: typeof payload.agent.name === "string"
+                ? payload.agent.name
+                : payload.agent.handle,
+        },
+    };
 }
-/**
- * Run the RFC 8628 device flow loop. Returns the access_token on success.
- * On expiration, restarts the loop transparently (user gets a fresh code).
- *
- * @deprecated W6 cleanup — superseded by `loopbackHandoffFlow`. No call
- * site after the W4 PR 3 migration; the function is kept as legacy
- * reference until the W6 cleanup retires the connector-side device-flow
- * verifier (`apps/connector/src/core/verify-device-session-token.ts`)
- * and the IdP-side `oauth/device/` route. Do not invoke from new code.
- */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function deviceCodeFlow(idpBaseUrl, prompter) {
-    for (;;) {
-        const init = await initDeviceCode(idpBaseUrl);
-        await prompter.text([
-            "",
-            `Setup code: ${init.user_code}`,
-            "",
-            `Open this link to authorize: ${init.verification_uri_complete ?? `${init.verification_uri}?user_code=${init.user_code}`}`,
-            "",
-            "Press Enter after you've authorized in the browser",
-        ].join("\n"));
+async function pollForCompletion(apiBase, sessionId) {
+    const start = Date.now();
+    while (Date.now() - start < HANDOFF_TIMEOUT_MS) {
+        let res;
         try {
-            const accessToken = await pollUntilAuthorized(idpBaseUrl, init.device_code, init.interval ?? DEFAULT_POLL_INTERVAL_S, prompter);
-            return accessToken;
+            res = await fetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
         }
-        catch (err) {
-            if (err instanceof DeviceFlowExpired) {
-                await prompter.text("Setup code expired. Press Enter for a new one.");
-                continue;
-            }
-            throw err;
-        }
-    }
-}
-async function initDeviceCode(idpBaseUrl) {
-    const params = new URLSearchParams();
-    params.set("client_id", OAUTH_CLIENT_ID);
-    params.set("scope", SCOPE);
-    const res = await fetch(`${idpBaseUrl}/api/auth/device/code`, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params.toString(),
-    });
-    if (!res.ok) {
-        // 4xx at initiation → likely a misconfigured client_id or scope. Surface
-        // a clear message rather than retrying — this is a setup error, not a
-        // transient one.
-        const body = (await res.json().catch(() => ({})));
-        const code = typeof body.error === "string" ? body.error : "unknown";
-        const description = typeof body.error_description === "string"
-            ? body.error_description
-            : `IdP returned ${res.status}`;
-        throw new DeviceFlowError(`Device code initiation failed (${code}): ${description}. ` +
-            `Verify that "${OAUTH_CLIENT_ID}" is registered with the device_code grant ` +
-            `and is in the deviceAuthorization plugin's allowlist at the IdP.`);
-    }
-    return (await res.json());
-}
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function pollUntilAuthorized(idpBaseUrl, deviceCode, intervalSeconds, prompter) {
-    let interval = intervalSeconds;
-    for (;;) {
-        const params = new URLSearchParams();
-        params.set("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
-        params.set("device_code", deviceCode);
-        params.set("client_id", OAUTH_CLIENT_ID);
-        const res = await fetch(`${idpBaseUrl}/api/auth/device/token`, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: params.toString(),
-        });
-        if (res.ok) {
-            const success = (await res.json());
-            return success.access_token;
-        }
-        const body = (await res.json().catch(() => ({})));
-        if (body.error === "authorization_pending") {
-            // User hasn't approved yet — wait and ask if they want to continue.
-            const retry = await prompter.confirm("Not authorized yet. Have you entered the code in your browser?");
-            if (!retry) {
-                // User gave up on this code — same recovery as expiration: ask
-                // the outer loop to restart with a fresh code. Throwing
-                // DeviceFlowExpired (rather than a separate "abandoned" sentinel)
-                // is intentional — both paths recover identically.
-                throw new DeviceFlowExpired();
-            }
-            await sleep(interval * 1000);
+        catch (_err) {
+            await sleep(HANDOFF_POLL_INTERVAL_MS);
             continue;
         }
-        if (body.error === "slow_down") {
-            // RFC 8628 §3.5 — server requests we slow down. Bump interval +5s.
-            interval += 5;
-            await sleep(interval * 1000);
-            continue;
-        }
-        if (body.error === "expired_token") {
-            throw new DeviceFlowExpired();
+        if (res.status === 404) {
+            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
         }
-        if (body.error === "access_denied") {
-            throw new DeviceFlowError("Authorization was denied. Re-run setup if this was a mistake.");
+        if (!res.ok) {
+            await sleep(HANDOFF_POLL_INTERVAL_MS);
+            continue;
         }
-        // Unknown error — bail with whatever we got from the server.
-        throw new DeviceFlowError(`Device token poll failed: ${body.error ?? "unknown"} ` +
-            `(${body.error_description ?? "no description"})`);
-    }
+        const body = (await res.json());
+        if (body.status === "completed" && body.payload) {
+            return body.payload;
+        }
+        await sleep(HANDOFF_POLL_INTERVAL_MS);
+    }
+    throw new SetupFlowError("Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
+}
+function decryptBridgeEnvelope(privateKey, envelope) {
+    const wrappedKey = Buffer.from(envelope.wrapped_key, "base64url");
+    const iv = Buffer.from(envelope.iv, "base64url");
+    const fullCiphertext = Buffer.from(envelope.ciphertext, "base64url");
+    if (fullCiphertext.length < 17) {
+        throw new Error("ciphertext shorter than auth tag");
+    }
+    const tagOffset = fullCiphertext.length - 16;
+    const ciphertext = fullCiphertext.subarray(0, tagOffset);
+    const authTag = fullCiphertext.subarray(tagOffset);
+    const aesKey = privateDecrypt({
+        key: privateKey,
+        padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: "sha256",
+    }, wrappedKey);
+    if (aesKey.length !== 32) {
+        throw new Error(`unexpected AES key length: ${aesKey.length}`);
+    }
+    const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return JSON.parse(plaintext.toString("utf-8"));
+}
+function normalizeHttpBase(apiHost) {
+    const trimmed = apiHost.replace(/\/+$/, "");
+    if (/^https?:\/\//.test(trimmed))
+        return trimmed;
+    return `https://${trimmed}`;
+}
+function parseHandleFromInput(input) {
+    if (typeof input !== "string")
+        return undefined;
+    const trimmed = input.trim().toLowerCase();
+    if (!HANDLE_REGEX.test(trimmed))
+        return undefined;
+    return trimmed;
 }
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
-// ---------------------------------------------------------------------------
-// Onboard (agent select / create)
-// ---------------------------------------------------------------------------
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function agentSetup(apiHost, accessToken, prompter) {
-    const platformCfg = { apiHost };
-    // First call: empty body. The server's list mode is intentionally
-    // non-mutating — it returns 412 (no agents) or 422 (here are your agents,
-    // pick one). Rotation only happens on the explicit `{agentId}` call after
-    // the user picks. Even with a single agent, the picker shows so the user
-    // explicitly confirms before any existing Runtime is evicted.
-    const listResult = await onboard(platformCfg, accessToken, {});
-    if (listResult.kind === "ok") {
-        // List mode never returns 200 by contract. If a future server version
-        // changes that, surface explicitly rather than silently accepting a
-        // rotation the user didn't confirm.
-        throw new DeviceFlowError("Server returned an unexpected 200 from the list call — refusing " +
-            "to use it without explicit user selection. Please report this.");
-    }
-    if (listResult.data.code === "no_agents") {
-        // Zero agents — prompt for handle to create one.
-        return await createAgentLoop(platformCfg, accessToken, prompter);
-    }
-    if (listResult.data.code === "agent_required") {
-        // Show picker. Single-agent case still goes through the picker (one
-        // agent + "Create new" choice) so the user explicitly confirms which
-        // agent this Runtime is claiming. The selection triggers api_key
-        // rotation — see "single-driver Node semantic" in CHANGELOG.
-        const agents = listResult.data.agents;
-        const choices = [
-            ...agents.map((a) => a.name ? `@${a.handle} (${a.name})` : `@${a.handle}`),
-            CREATE_NEW_OPTION,
-        ];
-        const promptLabel = agents.length === 1
-            ? "You have one agent. Confirm to claim it for this Runtime " +
-                "(its api_key will be rotated; any previously-connected Runtime " +
-                "for this agent will be disconnected):"
-            : "You have multiple agents. Pick one to claim for this Runtime " +
-                "(its api_key will be rotated; any previously-connected Runtime " +
-                "for the chosen agent will be disconnected):";
-        const selected = await prompter.select(promptLabel, choices);
-        if (selected === CREATE_NEW_OPTION) {
-            return await createAgentLoop(platformCfg, accessToken, prompter);
-        }
-        const idx = choices.indexOf(selected);
-        const agent = agents[idx];
-        if (!agent) {
-            throw new DeviceFlowError("Picker returned an unrecognized choice. Please re-run setup.");
-        }
-        const selectResult = await onboard(platformCfg, accessToken, {
-            agentId: agent.id,
-        });
-        if (selectResult.kind !== "ok") {
-            throw new DeviceFlowError(`Agent selection failed: ${selectResult.data.code}`);
-        }
-        return selectResult.data;
-    }
-    // invalid_handle / handle_taken can only happen on a `create` call —
-    // not from an empty `{}` first call.
-    throw new DeviceFlowError(`Unexpected onboard error on initial list call: ${listResult.data.code}`);
-}
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function createAgentLoop(platformCfg, accessToken, prompter) {
-    for (;;) {
-        const handle = await prompter.text("Choose a handle for your Agent (3-15 chars, start with a letter, then letters/numbers/hyphens/underscores):");
-        // Lowercase + trim mirrors the server's normalizeHandle step. If the user
-        // typed "Alice", we test "alice" against the regex — same outcome the
-        // server would produce. Prevents the false-negative case where a valid
-        // handle is rejected client-side just for case.
-        const normalized = handle.trim().toLowerCase();
-        // Client-side fail-fast — saves a server round-trip on obvious mistakes.
-        // Server's validateHandle is the authoritative source for both format
-        // and the reserved-handle list.
-        if (!HANDLE_REGEX.test(normalized)) {
-            await prompter.text(`"${handle}" must be 3-15 chars, start with a letter, then only letters/numbers/hyphens/underscores. Press Enter to try again.`);
-            continue;
-        }
-        const result = await onboard(platformCfg, accessToken, {
-            create: { handle: normalized },
-        });
-        if (result.kind === "ok") {
-            return result.data;
-        }
-        if (result.data.code === "handle_taken") {
-            await prompter.text(`"${normalized}" is already taken. Press Enter to try another.`);
-            continue;
-        }
-        if (result.data.code === "invalid_handle") {
-            await prompter.text(`"${normalized}" failed server validation: ${result.data.message}. Press Enter to try again.`);
-            continue;
-        }
-        // Other structured errors shouldn't reach here on a create call —
-        // surface with whatever we got.
-        throw new DeviceFlowError(`Unexpected onboard error on create: ${result.data.code}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Clack-backed Prompter adapter
-// ---------------------------------------------------------------------------
-/**
- * Build a Prompter backed by `@clack/prompts` (the same library OpenClaw CLI
- * uses internally, so the terminal UX is consistent with other channel
- * plugins). Cancel sentinels (user Ctrl+C) are mapped to `DeviceFlowError`
- * so the login function can treat cancels as a clean exit condition.
- *
- * @deprecated W6 cleanup — only the `@deprecated` device-flow helpers
- * consume this. The active loopback handoff uses `clack` indirectly
- * via the spinner-style stdout writes in `loopbackHandoffFlow`.
- */
-// biome-ignore lint/correctness/noUnusedVariables: retained for the @deprecated device-flow helpers
-function createClackPrompter() {
-    const abortOnCancel = (result) => {
-        if (isCancel(result)) {
-            // Emit clack's canonical cancel UI (bracketed red "cancelled") here so
-            // the user sees a clean exit indicator, then throw `CancelError` so the
-            // outer `login` catch returns silently (avoids printing the same line
-            // twice — UI from `cancel()` + a redundant `runtime.error` afterwards).
-            cancel("Setup cancelled.");
-            throw new CancelError("Setup cancelled by user.");
-        }
-    };
-    return {
-        async text(label) {
-            // `text(label, opts?.default)` previously mapped `opts.default` to clack's
-            // `placeholder` — but clack's `placeholder` is hint-only (not auto-submitted
-            // on empty input), and no current caller passes `opts.default`. Dropped
-            // the mapping until a real default-value need surfaces; revisit by
-            // implementing `clackText({ message, defaultValue })` then.
-            const result = await clackText({ message: label });
-            abortOnCancel(result);
-            return result;
-        },
-        async confirm(label) {
-            const result = await clackConfirm({ message: label });
-            abortOnCancel(result);
-            return result;
-        },
-        async select(label, choices) {
-            // Narrow the generic — we use `string` values throughout the flow.
-            const result = await clackSelect({
-                message: label,
-                options: choices.map((choice) => ({ value: choice, label: choice })),
-            });
-            abortOnCancel(result);
-            return result;
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Public hook — `plugin.auth.login` (OpenClaw 2026.4.x contract)
-// ---------------------------------------------------------------------------
-/**
- * Channel login hook — invoked by `openclaw channels login --channel agent-network`.
- *
- * Unlike the legacy `configureInteractive` contract (which returned a config
- * object for the CLI to persist), the 2026.4.x `auth.login` contract returns
- * void and expects the plugin to persist any config changes itself. We use
- * `writeCredentials()` in config.ts, which writes `openclaw.json` atomically
- * and bumps the state-cache generation so Layer B's dynamic context re-reads
- * on the next turn.
- *
- * Flow (W4 PR 3):
- *   1. Run `loopbackHandoffFlow` against `apps/web` — a Stripe-style
- *      browser-mediated runtime-key issuance that delivers the plaintext
- *      `masons_rt_…` token to a one-shot loopback listener bound at
- *      `127.0.0.1:0` with a fragment-nonce cross-origin discipline.
- *   2. Resolve the connector URL — preserve any user-set
- *      `accounts.default.connectorUrl` from `openclaw.json` (for self-
- *      hosted topologies); fall back to the cloud derivation
- *      `wss://<apiHost>/gateway` matching the connector's
- *      `CONNECTOR_PLUGIN_URL` env default.
- *   3. Persist `{connectorUrl, token}` atomically.
- *
- * Errors during the handoff are surfaced via `ctx.runtime.error` (not
- * thrown) so OpenClaw CLI doesn't display a stack trace — matches the
- * WhatsApp/Feishu pattern.
- */
 export async function login(ctx) {
-    // Channel-level config (`cfg.apiHost`, `cfg.idpBaseUrl`) — both have
-    // defaults. Existing values from openclaw.json are preserved on re-run.
     const apiHost = typeof ctx.cfg.apiHost === "string" ? ctx.cfg.apiHost : DEFAULT_API_HOST;
     const idpBaseUrl = typeof ctx.cfg.idpBaseUrl === "string"
         ? ctx.cfg.idpBaseUrl
         : DEFAULT_IDP_BASE_URL;
     let handoff;
     try {
-        handoff = await loopbackHandoffFlow(idpBaseUrl, ctx.runtime, ctx.channelInput);
+        handoff = await serverBridgeHandoffFlow(apiHost, idpBaseUrl, ctx.runtime, ctx.channelInput);
     }
     catch (err) {
-        if (err instanceof CancelError) {
-            // User pressed Ctrl+C — clack already emitted the cancel UI.
-            return;
-        }
-        if (err instanceof DeviceFlowError) {
-            // Loopback error with a human-friendly message. Print and return
-            // cleanly — CLI shows nothing else on a return. (The class name
-            // is `DeviceFlowError` for legacy reasons; it serves as a
-            // generic "expected setup failure" sentinel for both flows.)
+        if (err instanceof SetupFlowError) {
             ctx.runtime.error(err.message);
             return;
         }
@@ -778,16 +166,11 @@ export async function login(ctx) {
             ctx.runtime.error(`Setup failed (HTTP ${err.status} ${err.code}): ${err.message}`);
             return;
         }
-        // Unknown error — let CLI surface the stack. Surfaces platform bugs
-        // that aren't covered by our structured error types.
         throw err;
     }
-    // `connectorUrl` is decoupled from `apps/api` (the issuance host) by
-    // design — apps/api does not know about connector deployment topology.
-    // Preserve any explicit user-set value (self-hosted) and fall back to
-    // the well-known cloud / preview shape (`wss://<apiHost>/gateway`).
-    const existingConnectorUrl = await loadExistingConnectorUrl();
-    const connectorUrl = existingConnectorUrl ?? deriveCloudConnectorUrl(apiHost);
+    const existingConnectorUrl = await readExistingConnectorUrl();
+    const configuredConnectorUrl = typeof ctx.cfg.connectorUrl === "string" ? ctx.cfg.connectorUrl : undefined;
+    const connectorUrl = existingConnectorUrl ?? configuredConnectorUrl ?? DEFAULT_CONNECTOR_URL;
     await writeCredentials({ connectorUrl, token: handoff.token }, apiHost, idpBaseUrl);
     ctx.runtime.log(`✓ Connected as @${handoff.agent.handle}`);
 }