@agent-native/core 0.80.11 → 0.81.0

package/corpus/templates/design/server/lib/verify-write-grant.ts

@@ -0,0 +1,108 @@
+/**
+ * Server-side helper: resolve and validate a localhost write-consent grant.
+ *
+ * Security model
+ * ==============
+ * - The grant row is loaded by designId + connectionId for the authenticated
+ *   user.
+ * - An expired grant (grantedUntil < now) is rejected.
+ * - The target file path must be inside rootPath — validated using Node's
+ *   path.resolve so that ".." traversal and absolute-path injection are
+ *   blocked at this layer. The bridge also performs its own realpath check.
+ * - The function throws an Error with a descriptive message on any violation so
+ *   callers can surface it cleanly to the agent.
+ */
+
+import path from "node:path";
+
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+
+export interface WriteGrantContext {
+  designId: string;
+  connectionId: string;
+  /** Email of the currently authenticated user (from request context). */
+  ownerEmail: string;
+  /** Target path relative to rootPath (or absolute — validated either way). */
+  targetPath: string;
+}
+
+export interface WriteGrantResult {
+  rootPath: string;
+  bridgeToken: string;
+  grantId: string;
+}
+
+/**
+ * Resolve the active write-consent grant for a given design + connection.
+ * Throws if no valid grant exists or the target path escapes rootPath.
+ */
+export async function verifyWriteGrant(
+  ctx: WriteGrantContext,
+): Promise<WriteGrantResult> {
+  const { designId, connectionId, ownerEmail, targetPath } = ctx;
+
+  const db = getDb();
+  const [grant] = await db
+    .select()
+    .from(schema.designLocalhostWriteGrants)
+    .where(
+      and(
+        eq(schema.designLocalhostWriteGrants.designId, designId),
+        eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
+        eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
+      ),
+    )
+    .limit(1);
+
+  if (!grant) {
+    throw new Error(
+      "No localhost write-consent grant found for this design + connection. " +
+        "The user must approve writes via the LocalhostWriteConsentDialog first.",
+    );
+  }
+
+  const now = new Date().toISOString();
+  if (grant.grantedUntil < now) {
+    throw new Error(
+      `Localhost write-consent grant expired at ${grant.grantedUntil}. ` +
+        "Request a new grant via the LocalhostWriteConsentDialog.",
+    );
+  }
+
+  assertPathInside(grant.rootPath, targetPath);
+
+  return {
+    rootPath: grant.rootPath,
+    bridgeToken: grant.bridgeToken,
+    grantId: grant.id,
+  };
+}
+
+/**
+ * Assert that targetPath is inside rootPath using path.resolve to block ".."
+ * traversal and absolute-path injection.
+ *
+ * The final realpath confinement (symlink escape prevention) is performed
+ * bridge-side using fs.realpath; this layer handles the logical check.
+ *
+ * Throws if the resolved target is not a descendant of the resolved root.
+ */
+export function assertPathInside(rootPath: string, targetPath: string): void {
+  const resolvedRoot = path.resolve(rootPath);
+  // targetPath may be relative (to root) or absolute — resolve relative to root
+  const resolvedTarget = path.isAbsolute(targetPath)
+    ? path.resolve(targetPath)
+    : path.resolve(rootPath, targetPath);
+
+  if (
+    resolvedTarget !== resolvedRoot &&
+    !resolvedTarget.startsWith(resolvedRoot + path.sep)
+  ) {
+    throw new Error(
+      `Path "${targetPath}" is outside the consented root "${rootPath}". ` +
+        "Write access is restricted to files inside the granted root folder.",
+    );
+  }
+}

package/corpus/templates/design/server/plugins/db.ts

@@ -211,6 +211,45 @@ CREATE INDEX IF NOT EXISTS design_system_shares_resource_principal_idx ON design
     visibility TEXT NOT NULL DEFAULT 'private'
   )`,
     },
+    // v16: localhost source connections and write-consent grants. The schema
+    // existed before this migration in source, but fresh/existing DBs still
+    // need the concrete tables and the bridge_token column used by localhost
+    // write-back.
+    {
+      version: 16,
+      sql: `CREATE TABLE IF NOT EXISTS design_localhost_connections (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    source_type TEXT NOT NULL DEFAULT 'localhost',
+    dev_server_url TEXT NOT NULL,
+    bridge_url TEXT,
+    root_path TEXT,
+    route_manifest TEXT NOT NULL DEFAULT '{}',
+    capabilities TEXT NOT NULL DEFAULT '[]',
+    status TEXT NOT NULL DEFAULT 'connected',
+    last_seen_at TEXT,
+    bridge_token TEXT,
+    owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+    org_id TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+  );
+ALTER TABLE design_localhost_connections ADD COLUMN IF NOT EXISTS bridge_token TEXT;
+CREATE TABLE IF NOT EXISTS design_localhost_write_grants (
+    id TEXT PRIMARY KEY,
+    design_id TEXT NOT NULL,
+    connection_id TEXT NOT NULL,
+    root_path TEXT NOT NULL,
+    bridge_token TEXT NOT NULL,
+    granted_until TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+    org_id TEXT,
+    visibility TEXT NOT NULL DEFAULT 'private'
+  );
+CREATE INDEX IF NOT EXISTS design_localhost_connections_owner_idx ON design_localhost_connections (owner_email, org_id, updated_at);
+CREATE INDEX IF NOT EXISTS design_localhost_write_grants_lookup_idx ON design_localhost_write_grants (design_id, connection_id, owner_email)`,
+    },
   ],
   { table: "design_migrations" },
 );

package/corpus/templates/design/server/register-secrets.ts

@@ -43,3 +43,41 @@ registerRequiredSecret({
     }
   },
 });
+
+// Optional: enables browsing reusable Figma components/component sets in the
+// Design asset rail. The provider API injects this server-side as
+// X-Figma-Token; never pass it through action parameters or chat.
+registerRequiredSecret({
+  key: "FIGMA_ACCESS_TOKEN",
+  label: "Figma access token",
+  description:
+    "Optional. Enables browsing and inserting Figma library components from files you can access.",
+  docsUrl: "https://developers.figma.com/docs/rest-api/personal-access-tokens/",
+  scope: "user",
+  kind: "api-key",
+  required: false,
+  validator: async (value) => {
+    if (!value) return true;
+    try {
+      const res = await fetch("https://api.figma.com/v1/me", {
+        headers: {
+          "X-Figma-Token": value,
+          "User-Agent": "AgentNative/1.0",
+        },
+      });
+      if (res.ok) return true;
+      if (res.status === 401 || res.status === 403) {
+        return {
+          ok: false,
+          error: `Figma rejected this token (${res.status}). Check that it is active and has access to the file.`,
+        };
+      }
+      return { ok: false, error: `Figma returned ${res.status}.` };
+    } catch (err: any) {
+      return {
+        ok: false,
+        error: `Could not reach Figma: ${err?.message ?? err}`,
+      };
+    }
+  },
+});

package/corpus/templates/design/shared/board-file.ts

@@ -0,0 +1,228 @@
+/**
+ * Shared constants and helpers for the board file — a reserved design_file
+ * whose HTML document holds absolute-positioned board elements.
+ *
+ * The board file is identified by the filename "__board__.html" and its id is
+ * stored in designs.data.boardFileId.  Board elements are direct children of
+ * <body style="margin:0;position:relative;background:transparent;overflow:visible">
+ * each with an absolute position derived from their original BoardObjectEntry
+ * geometry.
+ *
+ * This module is imported by the editor UI, actions, and migration code.
+ * It must stay free of React, Nitro, and database imports.
+ */
+
+import type { BoardObjectEntry } from "./board-objects.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Reserved filename for the board overlay file. */
+export const BOARD_FILENAME = "__board__.html";
+
+// ---------------------------------------------------------------------------
+// isBoardFile
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when `filename` is the reserved board file.
+ * Comparison is case-sensitive to match the rest of the codebase.
+ */
+export function isBoardFile(filename: string): boolean {
+  return filename === BOARD_FILENAME;
+}
+
+// ---------------------------------------------------------------------------
+// emptyBoardHtml
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical empty-board document template.
+ *
+ * The <body> uses:
+ *   - margin:0 — no browser default whitespace
+ *   - position:relative — so absolute children are positioned within the body
+ *   - background:transparent — the board layer sits behind screen iframes
+ *   - overflow:visible — board elements may extend beyond the logical surface
+ */
+export function emptyBoardHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<style>
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; position: relative; background: transparent; overflow: visible; }
+</style>
+</head>
+<body>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// boardObjectEntryToHtmlFragment
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a BoardObjectEntry to an absolute-positioned HTML fragment for
+ * insertion into the board file's <body>.
+ *
+ * Negative left/top coordinates are intentionally preserved — board objects
+ * may live anywhere in the infinite canvas space, including at negative offsets
+ * (e.g. to the left of or above the primary frame cluster).
+ *
+ * The fragment sets `data-agent-native-node-id` so the bridge engine can
+ * select, style, and move elements exactly as it does for screen elements.
+ */
+export function boardObjectEntryToHtmlFragment(
+  entry: BoardObjectEntry,
+): string {
+  const {
+    id,
+    kind,
+    geometry,
+    fill,
+    stroke,
+    strokeWidth,
+    text,
+    pathData,
+    points,
+    name,
+  } = entry;
+  const x = Math.round(geometry.x);
+  const y = Math.round(geometry.y);
+  const width = Math.max(1, Math.round(geometry.width));
+  const height = Math.max(1, Math.round(geometry.height));
+
+  const nodeId = id;
+  const layerName = name ?? kindToLayerName(kind);
+
+  // Base inline style — negative left/top are kept as-is.
+  const baseStyle = [
+    "position:absolute",
+    `left:${x}px`,
+    `top:${y}px`,
+    `width:${width}px`,
+    `height:${height}px`,
+    ...(geometry.rotation ? [`transform:rotate(${geometry.rotation}deg)`] : []),
+    ...(typeof geometry.z === "number" ? [`z-index:${geometry.z}`] : []),
+  ].join(";");
+
+  const dataAttrs =
+    `data-agent-native-node-id="${escapeAttr(nodeId)}"` +
+    ` data-agent-native-layer-name="${escapeAttr(layerName)}"` +
+    // Kind marker so the layers panel renders a shape/text/frame icon for the
+    // primitive (a rectangle looks like a rectangle), matching in-screen drawn
+    // primitives, instead of the generic code/element glyph.
+    ` data-an-primitive="${escapeAttr(kind)}"`;
+
+  // Path / line / arrow kinds use an inline SVG.
+  if (kind === "path" || kind === "line" || kind === "arrow") {
+    const pts = points?.length
+      ? points
+      : [
+          { x: 0, y: height / 2 },
+          { x: width, y: height / 2 },
+        ];
+    const originX = Math.min(...pts.map((p) => p.x));
+    const originY = Math.min(...pts.map((p) => p.y));
+    const d =
+      pathData ??
+      pts
+        .map(
+          (p, i) =>
+            `${i === 0 ? "M" : "L"} ${Math.round(p.x - originX)} ${Math.round(p.y - originY)}`,
+        )
+        .join(" ");
+    const strokeColor = stroke ?? "var(--primary, #2563eb)";
+    const sw = strokeWidth ?? 3;
+
+    let markerDefs = "";
+    let markerEnd = "";
+    if (kind === "arrow") {
+      const markerId = `${nodeId}-arrow`;
+      markerDefs = `<defs><marker id="${escapeAttr(markerId)}" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto" markerUnits="strokeWidth"><path d="M 0 0 L 10 5 L 0 10 z" fill="${escapeAttr(strokeColor)}"/></marker></defs>`;
+      markerEnd = ` marker-end="url(#${escapeAttr(markerId)})"`;
+    }
+
+    return `<svg style="${baseStyle}" xmlns="http://www.w3.org/2000/svg" overflow="visible" ${dataAttrs}>${markerDefs}<path d="${escapeAttr(d)}" fill="none" stroke="${escapeAttr(strokeColor)}" stroke-width="${sw}" stroke-linecap="round" stroke-linejoin="round"${markerEnd}/></svg>`;
+  }
+
+  // Ellipse kind uses a <div> with border-radius.
+  if (kind === "ellipse") {
+    const bgColor = fill ?? "var(--primary, #2563eb)";
+    const borderStyle = stroke
+      ? `border:${strokeWidth ?? 1}px solid ${stroke};`
+      : "";
+    const style = `${baseStyle};background:${bgColor};border-radius:50%;${borderStyle}`;
+    return `<div style="${style}" ${dataAttrs}></div>`;
+  }
+
+  // Text kind uses a <div> with text content.
+  if (kind === "text") {
+    const color = fill ?? "inherit";
+    const style = `${baseStyle};color:${color};white-space:pre-wrap;`;
+    return `<div style="${style}" ${dataAttrs}>${text ? escapeHtml(text) : ""}</div>`;
+  }
+
+  // Frame / rectangle / polygon / star / default — basic colored <div>.
+  const bgColor =
+    fill ?? (kind === "frame" ? "transparent" : "var(--primary, #2563eb)");
+  const borderStyle = stroke
+    ? `border:${strokeWidth ?? 1}px solid ${stroke};`
+    : "";
+  const style = `${baseStyle};background:${bgColor};${borderStyle}`;
+
+  if (kind === "frame") {
+    return `<div style="${style}" ${dataAttrs}>${text ? escapeHtml(text) : ""}</div>`;
+  }
+
+  return `<div style="${style}" ${dataAttrs}>${text ? escapeHtml(text) : ""}</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function kindToLayerName(kind: BoardObjectEntry["kind"]): string {
+  switch (kind) {
+    case "frame":
+      return "Frame";
+    case "rectangle":
+      return "Rectangle";
+    case "ellipse":
+      return "Ellipse";
+    case "polygon":
+      return "Polygon";
+    case "star":
+      return "Star";
+    case "line":
+      return "Line";
+    case "arrow":
+      return "Arrow";
+    case "text":
+      return "Text";
+    case "path":
+      return "Path";
+    default:
+      return "Shape";
+  }
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}