shadow-claw 1.23.4 → 1.24.1

package/src/server/routes/backup.test.ts

@@ -0,0 +1,277 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import express from "express";
+import { openClientStore, closeClientStore } from "../client-registry.js";
+import { registerBackupRoutes } from "./backup.js";
+import type { AddressInfo } from "node:net";
+
+function makeHttpRequest(options: {
+  method?: string;
+  path: string;
+  port: number;
+  headers?: Record<string, string>;
+  body?: any;
+}): Promise<{ status: number; data: any; headers: http.IncomingHttpHeaders }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        hostname: "127.0.0.1",
+        port: options.port,
+        path: options.path,
+        method: options.method || "GET",
+        headers: {
+          "Content-Type": "application/json",
+          ...options.headers,
+        },
+      },
+      (res) => {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => {
+          let parsed = body;
+          try {
+            parsed = JSON.parse(body);
+          } catch (_) {}
+          resolve({
+            status: res.statusCode || 0,
+            data: parsed,
+            headers: res.headers,
+          });
+        });
+      },
+    );
+    req.on("error", reject);
+    if (options.body) {
+      req.write(
+        typeof options.body === "string"
+          ? options.body
+          : JSON.stringify(options.body),
+      );
+    }
+    req.end();
+  });
+}
+
+describe("backup routes", () => {
+  let app: express.Express;
+  let server: http.Server;
+  let port: number;
+  let token: string;
+  let testBackupsDir: string;
+
+  beforeEach(async () => {
+    openClientStore(":memory:");
+    token = "backup-test-token";
+    testBackupsDir = path.join(
+      process.cwd(),
+      ".cache",
+      "test-backups-" + Date.now(),
+    );
+
+    app = express();
+    app.use(express.json({ limit: "50mb" }));
+    registerBackupRoutes(app, {
+      backupsDir: testBackupsDir,
+      token,
+    });
+
+    server = http.createServer(app);
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => {
+        port = (server.address() as AddressInfo).port;
+        resolve();
+      });
+    });
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+    closeClientStore();
+    try {
+      if (fs.existsSync(testBackupsDir)) {
+        fs.rmSync(testBackupsDir, { recursive: true, force: true });
+      }
+    } catch (_) {}
+  });
+
+  it("rejects unauthorized external requests without token", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/list",
+      headers: { host: "127.0.0.1", origin: "https://attacker.com" },
+    });
+
+    expect(res.status).toBe(401);
+  });
+
+  it("allows same-origin browser requests without explicit token header", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/list",
+      headers: {
+        host: `127.0.0.1:${port}`,
+        origin: `http://127.0.0.1:${port}`,
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.data.backups).toBeDefined();
+  });
+
+  it("allows GitHub Pages origin requests without explicit token header", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/list",
+      headers: {
+        host: `127.0.0.1:${port}`,
+        origin: "https://xt-ml.github.io",
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.data.backups).toBeDefined();
+  });
+
+  it("uploads a file and verifies on disk", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/upload",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-ipad",
+        backupId: "bk-01",
+        path: "workspace/MEMORY.md",
+        content: "# Client Memory\nHello from iPad",
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.data.success).toBe(true);
+
+    const savedFilePath = path.join(
+      testBackupsDir,
+      "client-ipad",
+      "bk-01",
+      "workspace",
+      "MEMORY.md",
+    );
+    expect(fs.existsSync(savedFilePath)).toBe(true);
+    expect(fs.readFileSync(savedFilePath, "utf-8")).toBe(
+      "# Client Memory\nHello from iPad",
+    );
+  });
+
+  it("prevents directory traversal in backup upload paths", async () => {
+    const res = await makeHttpRequest({
+      port,
+      path: "/api/backup/upload",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-ipad",
+        backupId: "bk-01",
+        path: "../../../etc/passwd",
+        content: "malicious content",
+      },
+    });
+
+    expect(res.status).toBe(400);
+    expect(res.data.error).toContain("Invalid path");
+  });
+
+  it("finalizes backup and records in SQLite database", async () => {
+    // 1. Upload a file
+    await makeHttpRequest({
+      port,
+      path: "/api/backup/upload",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-ipad",
+        backupId: "bk-01",
+        path: "notes.txt",
+        content: "note content",
+      },
+    });
+
+    // 2. Complete backup
+    const completeRes = await makeHttpRequest({
+      port,
+      path: "/api/backup/complete",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-ipad",
+        backupId: "bk-01",
+        fileCount: 1,
+        totalBytes: 12,
+      },
+    });
+
+    expect(completeRes.status).toBe(200);
+    expect(completeRes.data.success).toBe(true);
+    expect(completeRes.data.backupId).toBe("bk-01");
+
+    // 3. List backups
+    const listRes = await makeHttpRequest({
+      port,
+      path: "/api/backup/list?clientId=client-ipad",
+      headers: { "x-control-token": token },
+    });
+
+    expect(listRes.status).toBe(200);
+    expect(listRes.data.backups).toHaveLength(1);
+    expect(listRes.data.backups[0].id).toBe("bk-01");
+    expect(listRes.data.backups[0].fileCount).toBe(1);
+  });
+
+  it("deletes a backup from disk and registry", async () => {
+    await makeHttpRequest({
+      port,
+      path: "/api/backup/upload",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-del",
+        backupId: "bk-del-01",
+        path: "file.txt",
+        content: "to be deleted",
+      },
+    });
+
+    await makeHttpRequest({
+      port,
+      path: "/api/backup/complete",
+      method: "POST",
+      headers: { "x-control-token": token },
+      body: {
+        clientId: "client-del",
+        backupId: "bk-del-01",
+        fileCount: 1,
+        totalBytes: 13,
+      },
+    });
+
+    const delRes = await makeHttpRequest({
+      port,
+      path: "/api/backup/bk-del-01?clientId=client-del",
+      method: "DELETE",
+      headers: { "x-control-token": token },
+    });
+
+    expect(delRes.status).toBe(200);
+    expect(delRes.data.success).toBe(true);
+
+    const listRes = await makeHttpRequest({
+      port,
+      path: "/api/backup/list?clientId=client-del",
+      headers: { "x-control-token": token },
+    });
+
+    expect(listRes.data.backups).toHaveLength(0);
+  });
+});

package/src/server/routes/backup.ts

@@ -0,0 +1,291 @@
+/**
+ * ShadowClaw — Backup REST Routes
+ *
+ * Provides endpoints for uploading workspace files from connected clients
+ * (e.g. iPad, remote browsers) to the server filesystem and tracking
+ * backup manifests in SQLite.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { URL } from "node:url";
+import type { Express, Request, Response, NextFunction } from "express";
+import {
+  getOrCreateControlToken,
+  recordBackup,
+  listBackups,
+  deleteBackup,
+} from "../client-registry.js";
+
+export interface BackupRoutesOptions {
+  backupsDir: string;
+  token?: string;
+  allowedOrigins?: Set<string>;
+  corsMode?: "localhost" | "private" | "all";
+}
+
+function isSafeRelativePath(relPath: string): boolean {
+  if (!relPath || typeof relPath !== "string") {
+    return false;
+  }
+  const normalized = path.normalize(relPath).replace(/^(\.\.[\/\\])+/, "");
+  if (
+    path.isAbsolute(relPath) ||
+    relPath.startsWith("..") ||
+    normalized !== relPath
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function isSameOriginBrowser(
+  req: Request,
+  options?: BackupRoutesOptions,
+): boolean {
+  const host = req.headers.host || "127.0.0.1";
+  const origin = req.headers.origin;
+  const referer = req.headers.referer;
+
+  const isTrustedUrl = (urlStr: string): boolean => {
+    try {
+      const parsed = new URL(urlStr);
+      if (parsed.host === host) {
+        return true;
+      }
+
+      const hostname = parsed.hostname.toLowerCase();
+      if (
+        hostname === "127.0.0.1" ||
+        hostname === "localhost" ||
+        hostname === "::1" ||
+        hostname === "[::1]"
+      ) {
+        return true;
+      }
+
+      if (
+        hostname === "github.com" ||
+        hostname.endsWith(".github.io") ||
+        hostname.endsWith(".pages.dev")
+      ) {
+        return true;
+      }
+
+      if (options?.corsMode === "all") {
+        return true;
+      }
+
+      if (
+        options?.allowedOrigins &&
+        options.allowedOrigins.has(parsed.origin)
+      ) {
+        return true;
+      }
+
+      if (
+        options?.corsMode === "private" &&
+        /^(127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(hostname)
+      ) {
+        return true;
+      }
+    } catch (_) {}
+    return false;
+  };
+
+  if (origin && isTrustedUrl(origin)) {
+    return true;
+  }
+
+  if (referer && isTrustedUrl(referer)) {
+    return true;
+  }
+
+  const secFetchSite = req.headers["sec-fetch-site"];
+  if (secFetchSite === "same-origin" || secFetchSite === "same-site") {
+    return true;
+  }
+
+  return false;
+}
+
+export function registerBackupRoutes(
+  app: Express,
+  options: BackupRoutesOptions,
+): void {
+  const { backupsDir } = options;
+  const token = options.token || getOrCreateControlToken();
+
+  // Authentication middleware
+  const authMiddleware = (req: Request, res: Response, next: NextFunction) => {
+    const host = req.headers.host || "127.0.0.1";
+    const parsedUrl = new URL(req.url, `http://${host}`);
+    const queryToken = parsedUrl.searchParams.get("token");
+    const headerToken = req.headers["x-control-token"];
+    const authHeader = req.headers["authorization"];
+    const bearerToken =
+      authHeader && authHeader.startsWith("Bearer ")
+        ? authHeader.slice(7).trim()
+        : null;
+
+    const providedToken = queryToken || headerToken || bearerToken;
+
+    const isAuthValid = providedToken
+      ? providedToken === token
+      : isSameOriginBrowser(req, options);
+
+    if (!isAuthValid) {
+      res.status(401).json({ error: "Unauthorized: Invalid control token" });
+      return;
+    }
+    next();
+  };
+
+  /**
+   * Upload a single file into a backup snapshot.
+   */
+  app.post(
+    "/api/backup/upload",
+    authMiddleware,
+    (req: Request, res: Response) => {
+      const {
+        clientId,
+        backupId,
+        path: filePath,
+        content,
+        encoding,
+      } = req.body || {};
+
+      if (!clientId || !backupId || !filePath) {
+        res
+          .status(400)
+          .json({ error: "clientId, backupId, and path are required" });
+        return;
+      }
+
+      if (!isSafeRelativePath(filePath)) {
+        res.status(400).json({ error: `Invalid path: ${filePath}` });
+        return;
+      }
+
+      const clientDir = path.resolve(backupsDir, clientId, backupId);
+      const targetFile = path.resolve(clientDir, filePath);
+
+      // Guard against directory traversal
+      if (
+        !targetFile.startsWith(clientDir + path.sep) &&
+        targetFile !== clientDir
+      ) {
+        res.status(400).json({ error: `Invalid path: ${filePath}` });
+        return;
+      }
+
+      try {
+        const parentDir = path.dirname(targetFile);
+        if (!fs.existsSync(parentDir)) {
+          fs.mkdirSync(parentDir, { recursive: true });
+        }
+
+        const buffer =
+          encoding === "base64"
+            ? Buffer.from(content || "", "base64")
+            : Buffer.from(content || "", "utf-8");
+
+        fs.writeFileSync(targetFile, buffer);
+
+        res.json({
+          success: true,
+          path: filePath,
+          bytesWritten: buffer.length,
+        });
+      } catch (err: any) {
+        res.status(500).json({ error: `Failed to write file: ${err.message}` });
+      }
+    },
+  );
+
+  /**
+   * Finalize and record a backup snapshot.
+   */
+  app.post(
+    "/api/backup/complete",
+    authMiddleware,
+    (req: Request, res: Response) => {
+      const { clientId, backupId, fileCount, totalBytes, manifest } =
+        req.body || {};
+
+      if (!clientId || !backupId) {
+        res.status(400).json({ error: "clientId and backupId are required" });
+        return;
+      }
+
+      try {
+        const record = recordBackup({
+          id: backupId,
+          clientId,
+          fileCount: Number(fileCount) || 0,
+          totalBytes: Number(totalBytes) || 0,
+          manifest,
+        });
+
+        res.json({
+          success: true,
+          backupId: record.id,
+          clientId: record.clientId,
+          timestamp: record.timestamp,
+          fileCount: record.fileCount,
+          totalBytes: record.totalBytes,
+        });
+      } catch (err: any) {
+        res
+          .status(500)
+          .json({ error: `Failed to complete backup: ${err.message}` });
+      }
+    },
+  );
+
+  /**
+   * List backups for a client.
+   */
+  app.get("/api/backup/list", authMiddleware, (req: Request, res: Response) => {
+    const clientId = (req.query.clientId as string) || undefined;
+    const backups = listBackups(clientId);
+    res.json({ backups });
+  });
+
+  /**
+   * Delete a backup snapshot.
+   */
+  app.delete(
+    "/api/backup/:id",
+    authMiddleware,
+    (req: Request, res: Response) => {
+      const backupId = Array.isArray(req.params.id)
+        ? req.params.id[0]
+        : req.params.id;
+      const clientId =
+        (req.query.clientId as string) || (req.body?.clientId as string);
+
+      if (!backupId) {
+        res.status(400).json({ error: "Backup id is required" });
+        return;
+      }
+
+      try {
+        if (clientId) {
+          const snapshotDir = path.resolve(backupsDir, clientId, backupId);
+          if (fs.existsSync(snapshotDir)) {
+            fs.rmSync(snapshotDir, { recursive: true, force: true });
+          }
+        }
+
+        deleteBackup(backupId, clientId);
+        res.json({ success: true, deleted: backupId });
+      } catch (err: any) {
+        res
+          .status(500)
+          .json({ error: `Failed to delete backup: ${err.message}` });
+      }
+    },
+  );
+}