@agent-native/core 0.80.11 → 0.81.0

package/dist/cli/design-connect.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import http from "node:http";
@@ -84,6 +85,13 @@ export function parseDesignConnectArgs(argv) {
         else if (arg.startsWith("--route-manifest=")) {
             parsed.routeManifest = arg.slice("--route-manifest=".length);
         }
+        else if (arg === "--app-url") {
+            parsed.appUrl = stringFlagValue(args, index, arg);
+            index += 1;
+        }
+        else if (arg.startsWith("--app-url=")) {
+            parsed.appUrl = arg.slice("--app-url=".length);
+        }
         else if (arg === "--json") {
             parsed.json = true;
             parsed.once = true;
@@ -298,21 +306,15 @@ export async function prepareDesignConnectManifest(options = {}) {
         generatedAt,
         capabilities: BRIDGE_OPERATIONS.map((operation) => ({
             operation,
-            status: operation === "readFile" ||
-                operation === "applyEdit" ||
-                operation === "writeFile"
-                ? "planned"
-                : "available",
-            reason: operation === "writeFile"
-                ? "The bridge advertises the contract before enabling local file writes."
-                : operation === "resolveNodeToFile"
-                    ? // resolveNodeToFile maps a runtime DOM node id (from the editor's
-                        // 'select' payload) to { file, line, component } provenance.  The
-                        // bridge endpoint exists; per-element provenance data must be
-                        // emitted by the connected app at build time — see the provenance
-                        // note in the help text below.
-                        "Requires the connected app to emit data-source-file / data-source-line / data-component-name attributes (e.g. via @vitejs/plugin-react jsxDEV or a Babel source plugin)."
-                    : undefined,
+            status: "available",
+            reason: operation === "resolveNodeToFile"
+                ? // resolveNodeToFile maps a runtime DOM node id (from the editor's
+                    // 'select' payload) to { file, line, component } provenance.  The
+                    // bridge endpoint exists; per-element provenance data must be
+                    // emitted by the connected app at build time — see the provenance
+                    // note in the help text below.
+                    "Requires the connected app to emit data-source-file / data-source-line / data-component-name attributes (e.g. via @vitejs/plugin-react jsxDEV or a Babel source plugin)."
+                : undefined,
         })),
     };
 }
@@ -320,19 +322,88 @@ function sendJson(res, statusCode, body) {
     res.writeHead(statusCode, {
         "content-type": "application/json; charset=utf-8",
         "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, OPTIONS",
-        "access-control-allow-headers": "content-type",
+        "access-control-allow-methods": "GET, POST, OPTIONS",
+        "access-control-allow-headers": "content-type, x-bridge-token",
         "access-control-allow-private-network": "true",
     });
     res.end(`${JSON.stringify(body, null, 2)}\n`);
 }
+/** Read the full request body as a UTF-8 string. */
+async function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/**
+ * Resolve `targetDir` under `rootPath` with realpath so that symlinks and
+ * traversal sequences (../../etc) cannot escape the root.  Throws if the
+ * resolved path does not start with the resolved root.
+ */
+async function assertPathInside(rootPath, targetPath) {
+    const resolvedRoot = await fs.realpath(rootPath).catch(() => {
+        throw new Error(`Bridge root path does not exist: ${rootPath}`);
+    });
+    // Resolve the parent directory (the file itself may not exist yet for writes).
+    const targetParent = path.dirname(path.resolve(rootPath, targetPath));
+    const resolvedParent = await fs.realpath(targetParent).catch(async () => {
+        // Parent may not exist yet; walk up until we find a real ancestor.
+        let candidate = targetParent;
+        for (let i = 0; i < 32; i++) {
+            const up = path.dirname(candidate);
+            if (up === candidate)
+                break;
+            candidate = up;
+            try {
+                return await fs.realpath(candidate);
+            }
+            catch {
+                // keep walking
+            }
+        }
+        throw new Error(`Cannot resolve parent directory: ${targetParent}`);
+    });
+    if (!resolvedParent.startsWith(resolvedRoot + path.sep) &&
+        resolvedParent !== resolvedRoot) {
+        throw new Error(`Path traversal detected: resolved target is outside root`);
+    }
+}
+/** Allowed file extensions for write/apply-edit operations. */
+const ALLOWED_WRITE_EXTENSIONS = new Set([".html", ".htm", ".css"]);
+function assertAllowedExtension(relPath) {
+    const ext = path.extname(relPath).toLowerCase();
+    if (!ALLOWED_WRITE_EXTENSIONS.has(ext)) {
+        throw new Error(`Write rejected: only .html, .htm, and .css files may be written via the bridge (got ${ext || "(no extension)"})`);
+    }
+}
+function countOccurrences(haystack, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        if (count > 1)
+            return count;
+        index = haystack.indexOf(needle, index + 1);
+    }
+    return count;
+}
 export async function startDesignConnectBridge(manifest) {
+    // Mint a cryptographically random per-rootPath bridge token.  This token is
+    // kept in-process only and is never emitted via the public GET routes so that
+    // an unauthenticated caller cannot read it.  The server-side grant action
+    // obtains it out-of-band (via the exported bridge reference).
+    const bridgeToken = crypto.randomBytes(32).toString("hex");
     const server = http.createServer((req, res) => {
         if (req.method === "OPTIONS") {
             sendJson(res, 204, {});
             return;
         }
         const pathname = new URL(req.url ?? "/", manifest.bridgeUrl).pathname;
+        // ── Public read-only routes (no token required) ──────────────────────
         if (pathname === "/" || pathname === "/manifest.json") {
             sendJson(res, 200, manifest);
             return;
@@ -352,6 +423,164 @@ export async function startDesignConnectBridge(manifest) {
             sendJson(res, 200, { ok: true, source: manifest.source });
             return;
         }
+        // ── Token-gated write endpoints (POST only) ───────────────────────────
+        if (pathname === "/read-file" ||
+            pathname === "/write-file" ||
+            pathname === "/apply-edit") {
+            if (req.method !== "POST") {
+                sendJson(res, 405, { ok: false, error: "method not allowed" });
+                return;
+            }
+            // Authenticate with constant-time comparison to prevent timing attacks.
+            const tokenHeader = req.headers["x-bridge-token"];
+            const providedToken = typeof tokenHeader === "string" ? tokenHeader : "";
+            let tokenValid = false;
+            try {
+                tokenValid =
+                    providedToken.length === bridgeToken.length &&
+                        crypto.timingSafeEqual(Buffer.from(providedToken, "utf8"), Buffer.from(bridgeToken, "utf8"));
+            }
+            catch {
+                tokenValid = false;
+            }
+            if (!tokenValid) {
+                sendJson(res, 401, {
+                    ok: false,
+                    error: "invalid or missing bridge token",
+                });
+                return;
+            }
+            // Handle asynchronously so we can use await.
+            void (async () => {
+                try {
+                    const raw = await readRequestBody(req);
+                    const body = JSON.parse(raw);
+                    const relPath = typeof body["relPath"] === "string" ? body["relPath"] : undefined;
+                    if (!relPath) {
+                        sendJson(res, 400, { ok: false, error: "relPath is required" });
+                        return;
+                    }
+                    await assertPathInside(manifest.rootPath, relPath);
+                    const absolutePath = path.resolve(manifest.rootPath, relPath);
+                    if (pathname === "/read-file") {
+                        // Read-file: no extension restriction — agents need to read any file.
+                        let content;
+                        try {
+                            content = await fs.readFile(absolutePath, "utf8");
+                        }
+                        catch (err) {
+                            const code = err instanceof Error &&
+                                "code" in err &&
+                                err.code;
+                            if (code === "ENOENT") {
+                                sendJson(res, 404, { ok: false, error: "file not found" });
+                            }
+                            else {
+                                sendJson(res, 500, {
+                                    ok: false,
+                                    error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+                                });
+                            }
+                            return;
+                        }
+                        sendJson(res, 200, { ok: true, content });
+                        return;
+                    }
+                    // write-file and apply-edit only allow .html/.htm/.css.
+                    assertAllowedExtension(relPath);
+                    if (pathname === "/write-file") {
+                        const content = typeof body["content"] === "string"
+                            ? body["content"]
+                            : undefined;
+                        if (content === undefined) {
+                            sendJson(res, 400, {
+                                ok: false,
+                                error: "content is required for write-file",
+                            });
+                            return;
+                        }
+                        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+                        await fs.writeFile(absolutePath, content, "utf8");
+                        sendJson(res, 200, { ok: true, relPath });
+                        return;
+                    }
+                    // /apply-edit: supports either full replace ({content}) or
+                    // search-and-replace ({search, replace}).
+                    if (typeof body["content"] === "string") {
+                        // Full-file replace via apply-edit — same as write-file but keeps
+                        // the endpoint semantically separate for callers that want to
+                        // distinguish intent.
+                        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+                        await fs.writeFile(absolutePath, body["content"], "utf8");
+                        sendJson(res, 200, { ok: true, relPath, method: "replace" });
+                        return;
+                    }
+                    const search = typeof body["search"] === "string" ? body["search"] : undefined;
+                    const replace = typeof body["replace"] === "string" ? body["replace"] : undefined;
+                    if (search === undefined || replace === undefined) {
+                        sendJson(res, 400, {
+                            ok: false,
+                            error: "apply-edit requires either {content} for a full replace, or {search, replace} for a patch",
+                        });
+                        return;
+                    }
+                    let existing;
+                    try {
+                        existing = await fs.readFile(absolutePath, "utf8");
+                    }
+                    catch (err) {
+                        const code = err instanceof Error &&
+                            "code" in err &&
+                            err.code;
+                        if (code === "ENOENT") {
+                            sendJson(res, 404, {
+                                ok: false,
+                                error: "file not found — use write-file to create new files",
+                            });
+                        }
+                        else {
+                            sendJson(res, 500, {
+                                ok: false,
+                                error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+                            });
+                        }
+                        return;
+                    }
+                    if (search.length === 0) {
+                        sendJson(res, 400, {
+                            ok: false,
+                            error: "search string must not be empty",
+                        });
+                        return;
+                    }
+                    const occurrenceCount = countOccurrences(existing, search);
+                    if (occurrenceCount === 0) {
+                        sendJson(res, 422, {
+                            ok: false,
+                            error: "search string not found in file",
+                        });
+                        return;
+                    }
+                    if (occurrenceCount > 1) {
+                        sendJson(res, 422, {
+                            ok: false,
+                            error: "search string is ambiguous; it appears more than once in the file",
+                        });
+                        return;
+                    }
+                    const updated = existing.replace(search, replace);
+                    await fs.writeFile(absolutePath, updated, "utf8");
+                    sendJson(res, 200, { ok: true, relPath, method: "patch" });
+                }
+                catch (err) {
+                    sendJson(res, 500, {
+                        ok: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            })();
+            return;
+        }
         sendJson(res, 404, { ok: false, error: "not found" });
     });
     await new Promise((resolve, reject) => {
@@ -361,7 +590,105 @@ export async function startDesignConnectBridge(manifest) {
             resolve();
         });
     });
-    return { server, manifest };
+    return { server, manifest, bridgeToken };
+}
+/**
+ * Resolve the design app URL from an explicit value or environment variables.
+ * Returns undefined when no URL is configured (registration is optional).
+ */
+export function resolveAppUrl(explicit) {
+    const raw = explicit ||
+        process.env["AGENT_NATIVE_URL"] ||
+        process.env["DESIGN_APP_URL"] ||
+        process.env["APP_URL"] ||
+        process.env["VITE_APP_URL"] ||
+        process.env["BETTER_AUTH_URL"] ||
+        process.env["VITE_BETTER_AUTH_URL"];
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = new URL(raw.trim());
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return undefined;
+        }
+        return parsed.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a bearer token from environment variables for authenticating the
+ * self-registration POST.  The CLI does not perform a device-code flow — it
+ * relies on a pre-minted token supplied via env var (e.g. the same token
+ * already written into the agent's MCP config).
+ */
+function resolveAuthToken() {
+    return (process.env["AGENT_NATIVE_TOKEN"] ||
+        process.env["DESIGN_ACCESS_TOKEN"] ||
+        process.env["ACCESS_TOKEN"] ||
+        undefined);
+}
+/**
+ * POST to the design app's `connect-localhost` action endpoint to register
+ * (or refresh) the bridge connection and persist the real bridge token on the
+ * server row.  This is a best-effort call: failures are logged but do not
+ * abort the bridge process.
+ *
+ * @param appUrl - Deployed design app base URL (e.g. https://design.agent-native.com)
+ * @param bridge - The running bridge returned by startDesignConnectBridge
+ * @param authToken - Optional bearer token for the authenticated action route
+ */
+export async function registerConnectionWithServer(appUrl, bridge, authToken) {
+    const endpoint = `${appUrl}/_agent-native/actions/connect-localhost`;
+    const { manifest, bridgeToken } = bridge;
+    const payload = {
+        devServerUrl: manifest.devServerUrl,
+        bridgeUrl: manifest.bridgeUrl,
+        rootPath: manifest.rootPath,
+        capabilities: manifest.capabilities,
+        routeManifest: {
+            version: 1,
+            sourceType: "localhost",
+            devServerUrl: manifest.devServerUrl,
+            rootPath: manifest.rootPath,
+            routes: manifest.routes,
+            generatedAt: manifest.generatedAt,
+        },
+        // Include the real bridge token so the server stores it on the connection
+        // row.  grant-localhost-write-consent then reads it from the row instead of
+        // minting its own unrelated token, which would always produce a 401.
+        bridgeToken,
+        status: "connected",
+    };
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (authToken) {
+        headers["authorization"] = `Bearer ${authToken}`;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const message = await res.text().catch(() => res.statusText);
+            throw new Error(`${res.status} ${message || res.statusText}`);
+        }
+    }
+    catch (error) {
+        // Best-effort: network errors or auth issues are non-fatal, but make the
+        // problem discoverable before the user tries "Apply to source".
+        console.error(`[design connect] Could not register bridge with ${endpoint}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
 }
 function printHelp() {
     console.log(`Usage:
@@ -372,6 +699,8 @@ Options:
   --port <number>         Local bridge port (default ${DEFAULT_BRIDGE_PORT})
   --root <path>           App/repo root for route discovery (default cwd)
   --route-manifest <path> Non-destructive route manifest output path
+  --app-url <url>         Deployed design app URL for self-registration
+                          (also reads AGENT_NATIVE_URL / DESIGN_APP_URL env)
   --json                  Print the manifest JSON and exit
   --once                  Prepare/scaffold the manifest and exit
   --dry-run               Print what would be exposed without writing files
@@ -423,6 +752,16 @@ export async function runDesign(argv) {
     console.error(`Manifest: ${manifest.bridgeUrl}/manifest.json`);
     console.error(`Routes:   ${manifest.routeCount}`);
     console.error(`Dev URL:  ${manifest.devServerUrl}`);
+    // Self-register with the design app server (best-effort).  When an app URL
+    // is available (via --app-url or env var) the CLI POSTs the bridge token to
+    // connect-localhost so the server row stores the real token.  Without this
+    // step grant-localhost-write-consent would mint a different token, causing
+    // every bridge write to return 401.
+    const appUrl = resolveAppUrl(parsed.appUrl);
+    if (appUrl) {
+        const authToken = resolveAuthToken();
+        void registerConnectionWithServer(appUrl, bridge, authToken);
+    }
     return await new Promise((resolve) => {
         const stop = () => {
             bridge.server.close(() => resolve(0));