@decocms/tanstack 7.0.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@decocms/tanstack",
+  "version": "7.0.0",
+  "type": "module",
+  "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./vite": "./src/vite/plugin.js",
+    "./daemon": "./src/daemon/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/tanstack/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.0.0",
+    "@decocms/blocks-admin": "7.0.0",
+    "@decocms/blocks-cli": "7.0.0",
+    "@deco-cx/warp-node": "^0.3.16",
+    "fast-json-patch": "^3.1.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "@tanstack/react-start": ">=1.0.0",
+    "@tanstack/store": ">=0.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": ">=6.0.0 || >=7.0.0 || >=8.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.96.0",
+    "@tanstack/store": "^0.9.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.18.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0",
+    "vite": ">=6.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/cms/kvBlockSource.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { computeRevision, KV_KEYS, type KVNamespace } from "@decocms/blocks/cms";
+import { KVBlockSource } from "./kvBlockSource";
+
+function makeKV(initial: Record<string, string> = {}): KVNamespace {
+  const store = new Map<string, string>(Object.entries(initial));
+  return {
+    get: (k) => Promise.resolve(store.get(k) ?? null),
+    put: (k, v) => {
+      store.set(k, v);
+      return Promise.resolve();
+    },
+    delete: (k) => {
+      store.delete(k);
+      return Promise.resolve();
+    },
+  };
+}
+
+describe("KVBlockSource.loadSnapshot", () => {
+  it("returns null when the snapshot key is missing", async () => {
+    const src = new KVBlockSource(makeKV());
+    await expect(src.loadSnapshot()).resolves.toBeNull();
+  });
+
+  it("returns blocks with the stored revision", async () => {
+    const blocks = { Site: { name: "x" } };
+    const src = new KVBlockSource(
+      makeKV({
+        [KV_KEYS.SNAPSHOT]: JSON.stringify(blocks),
+        [KV_KEYS.REVISION]: "stored-rev",
+      }),
+    );
+    await expect(src.loadSnapshot()).resolves.toEqual({ blocks, revision: "stored-rev" });
+  });
+
+  it("recomputes the revision when only the snapshot is stored", async () => {
+    const blocks = { Site: { name: "x" } };
+    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: JSON.stringify(blocks) }));
+    await expect(src.loadSnapshot()).resolves.toEqual({
+      blocks,
+      revision: computeRevision(blocks),
+    });
+  });
+
+  it("throws on a non-object snapshot (treated as KV-unavailable by callers)", async () => {
+    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: "[1,2,3]" }));
+    await expect(src.loadSnapshot()).rejects.toThrow();
+  });
+
+  it("throws on malformed JSON", async () => {
+    const src = new KVBlockSource(makeKV({ [KV_KEYS.SNAPSHOT]: "{not json" }));
+    await expect(src.loadSnapshot()).rejects.toThrow();
+  });
+});
+
+describe("KVBlockSource.getRevision", () => {
+  it("returns the stored revision", async () => {
+    const src = new KVBlockSource(makeKV({ [KV_KEYS.REVISION]: "r1" }));
+    await expect(src.getRevision()).resolves.toBe("r1");
+  });
+
+  it("returns null when absent", async () => {
+    const src = new KVBlockSource(makeKV());
+    await expect(src.getRevision()).resolves.toBeNull();
+  });
+});

package/src/cms/kvBlockSource.ts

@@ -0,0 +1,54 @@
+/**
+ * KVBlockSource — a `BlockSource` backed by a Cloudflare KV namespace.
+ *
+ * Reads the whole decofile snapshot (`decofile:current`) and its revision
+ * (`index:revision`) from KV. Used by the runtime hydration path
+ * (`src/sdk/kvHydration.ts`) on cold start and during revision polling, and by
+ * the write-through path (`src/admin/decofile.ts`) which writes the same keys.
+ *
+ * This class is intentionally thin — error handling (KV outages, JSON parse
+ * failures) is the caller's responsibility so the framework can fall back to
+ * the bundled snapshot. See `kvHydration.ts`.
+ */
+
+import {
+  type BlockSnapshot,
+  type BlockSource,
+  computeRevision,
+  KV_KEYS,
+  type KVNamespace,
+} from "@decocms/blocks/cms";
+
+export class KVBlockSource implements BlockSource {
+  constructor(private readonly kv: KVNamespace) {}
+
+  /**
+   * Read and parse the full decofile snapshot from KV.
+   *
+   * Returns `null` when no snapshot is present (key missing) so the caller
+   * keeps whatever blocks are already in memory (the bundled fallback).
+   *
+   * The stored revision is preferred; if it's absent we recompute it from the
+   * blocks so the result is always self-consistent. A malformed snapshot
+   * (invalid JSON / non-object) throws — the caller treats that as "KV
+   * unavailable" and falls back.
+   */
+  async loadSnapshot(): Promise<BlockSnapshot | null> {
+    const raw = await this.kv.get(KV_KEYS.SNAPSHOT);
+    if (raw === null) return null;
+
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`[CMS/KV] ${KV_KEYS.SNAPSHOT} is not a JSON object`);
+    }
+    const blocks = parsed as Record<string, unknown>;
+
+    const storedRevision = await this.kv.get(KV_KEYS.REVISION);
+    return { blocks, revision: storedRevision ?? computeRevision(blocks) };
+  }
+
+  /** Cheap revision probe for change detection (no full snapshot transfer). */
+  getRevision(): Promise<string | null> {
+    return this.kv.get(KV_KEYS.REVISION);
+  }
+}

package/src/daemon/auth.ts

@@ -0,0 +1,204 @@
+/**
+ * JWT verification for admin.deco.cx requests.
+ * Uses Web Crypto only — no external dependencies.
+ *
+ * Ported from: deco-cx/deco daemon/auth.ts + commons/jwt/*
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+// ---------------------------------------------------------------------------
+// Public key — same key used by all sites (from commons/jwt/trusted.ts)
+// ---------------------------------------------------------------------------
+
+const ADMIN_PUBLIC_KEY =
+  process.env.DECO_ADMIN_PUBLIC_KEY ??
+  "eyJrdHkiOiJSU0EiLCJhbGciOiJSUzI1NiIsIm4iOiJ1N0Y3UklDN19Zc3ljTFhEYlBvQ1pUQnM2elZ6VjVPWkhXQ0M4akFZeFdPUnByem9WNDJDQ1JBVkVOVjJldzk1MnJOX2FTMmR3WDlmVGRvdk9zWl9jX2RVRXctdGlPN3hJLXd0YkxsanNUbUhoNFpiYXU0aUVoa0o1VGNHc2VaelhFYXNOSEhHdUo4SzY3WHluRHJSX0h4Ym9kQ2YxNFFJTmc5QnJjT3FNQmQyMUl4eUctVVhQampBTnRDTlNici1rXzFKeTZxNmtPeVJ1ZmV2Mjl0djA4Ykh5WDJQenp5Tnp3RWpjY0lROWpmSFdMN0JXX2tzdFpOOXU3TUtSLWJ4bjlSM0FKMEpZTHdXR3VnZGpNdVpBRnk0dm5BUXZzTk5Cd3p2YnFzMnZNd0dDTnF1ZE1tVmFudlNzQTJKYkE3Q0JoazI5TkRFTXRtUS1wbmo1cUlYSlEiLCJlIjoiQVFBQiIsImtleV9vcHMiOlsidmVyaWZ5Il0sImV4dCI6dHJ1ZX0";
+
+const BYPASS_JWT =
+  process.env.DANGEROUSLY_ALLOW_PUBLIC_ACCESS === "true";
+
+// ---------------------------------------------------------------------------
+// JWT types
+// ---------------------------------------------------------------------------
+
+export interface JwtPayload {
+  [key: string]: unknown;
+  iss?: string;
+  sub?: string;
+  aud?: string | string[];
+  exp?: number;
+  nbf?: number;
+  iat?: number;
+  jti?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Crypto helpers — ported from commons/jwt/keys.ts
+// ---------------------------------------------------------------------------
+
+const ALG = "RSASSA-PKCS1-v1_5";
+const HASH = "SHA-256";
+
+function parseJWK(b64: string): JsonWebKey {
+  return JSON.parse(atob(b64));
+}
+
+let cachedKey: Promise<CryptoKey> | null = null;
+
+function getAdminPublicKey(): Promise<CryptoKey> {
+  cachedKey ??= crypto.subtle.importKey(
+    "jwk",
+    parseJWK(ADMIN_PUBLIC_KEY),
+    { name: ALG, hash: HASH },
+    false,
+    ["verify"],
+  );
+  return cachedKey;
+}
+
+// ---------------------------------------------------------------------------
+// JWT verification — ported from commons/jwt/jwt.ts
+// ---------------------------------------------------------------------------
+
+function base64UrlDecode(str: string): Uint8Array {
+  const b64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
+  const binary = atob(b64 + pad);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export async function verifyAdminJwt(
+  token: string,
+): Promise<JwtPayload | null> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+  const signingInput = new TextEncoder().encode(
+    `${headerB64}.${payloadB64}`,
+  );
+  const signature = base64UrlDecode(signatureB64);
+
+  try {
+    const key = await getAdminPublicKey();
+    const valid = await crypto.subtle.verify(
+      ALG,
+      key,
+      new Uint8Array(signature),
+      new Uint8Array(signingInput),
+    );
+    if (!valid) return null;
+  } catch {
+    return null;
+  }
+
+  try {
+    const payload: JwtPayload = JSON.parse(
+      new TextDecoder().decode(base64UrlDecode(payloadB64)),
+    );
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// URN matching — ported from commons/jwt/engine.ts
+// ---------------------------------------------------------------------------
+
+function matchPart(urnPart: string, otherPart: string): boolean {
+  return urnPart === "*" || otherPart === urnPart;
+}
+
+function matchParts(urn: string[], resource: string[]): boolean {
+  return urn.every((part, idx) => matchPart(part, resource[idx]));
+}
+
+function matches(urnParts: string[]) {
+  return (resourceUrn: string) => {
+    const resourceParts = resourceUrn.split(":");
+    if (resourceParts.length > urnParts.length) return false;
+    const lastIdx = resourceParts.length - 1;
+    return resourceParts.every((part, idx) => {
+      if (part === "*") return true;
+      if (lastIdx === idx) {
+        return matchParts(part.split("/"), urnParts[idx].split("/"));
+      }
+      return part === urnParts[idx];
+    });
+  };
+}
+
+export function tokenIsValid(site: string, jwt: JwtPayload): boolean {
+  const { iss, sub, exp } = jwt;
+  if (!iss || !sub) return false;
+  if (exp && exp * 1000 <= Date.now()) return false;
+  const siteUrn = `urn:deco:site:*:${site}:deployment/*`;
+  return matches(sub.split(":"))(siteUrn);
+}
+
+// ---------------------------------------------------------------------------
+// Auth middleware for Connect (Vite dev server)
+// ---------------------------------------------------------------------------
+
+function extractToken(req: IncomingMessage): string | null {
+  const auth = req.headers.authorization;
+  if (auth) {
+    const parts = auth.split(/\s+/);
+    if (parts.length === 2) return parts[1];
+  }
+  // Fallback: ?token= query param
+  try {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const t = url.searchParams.get("token");
+    if (t) return t;
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+export type NextFn = () => void;
+
+/**
+ * Returns a Connect-style middleware that verifies JWT on every request.
+ * If invalid, responds 401/403. If valid (or bypass enabled), calls next().
+ */
+export function createAuthMiddleware(site: string) {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: NextFn,
+  ): Promise<void> => {
+    if (BYPASS_JWT) {
+      next();
+      return;
+    }
+
+    const token = extractToken(req);
+    if (!token) {
+      res.writeHead(401);
+      res.end();
+      return;
+    }
+
+    const jwt = await verifyAdminJwt(token);
+    if (!jwt) {
+      res.writeHead(401);
+      res.end();
+      return;
+    }
+
+    if (!tokenIsValid(site, jwt)) {
+      res.writeHead(403);
+      res.end();
+      return;
+    }
+
+    next();
+  };
+}

package/src/daemon/fs.ts

@@ -0,0 +1,238 @@
+/**
+ * Filesystem REST API — read, patch, delete .deco/ files.
+ *
+ * The admin UI reads individual files via GET /fs/file/<path>.
+ * This is separate from the volumes/realtime WebSocket API.
+ *
+ * Ported from: deco-cx/deco daemon/fs/api.ts
+ */
+import { readFile, writeFile, rm, stat, mkdir } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import fjp from "fast-json-patch";
+import type { Operation } from "fast-json-patch";
+import { inferMetadata, broadcastFSEvent, type Metadata } from "./watch";
+
+const cwd = process.cwd();
+const toPosix = (p: string) => p.replaceAll(sep, "/");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function safePath(untrusted: string): string | null {
+  const resolved = resolve(cwd, untrusted.startsWith("/") ? `.${untrusted}` : untrusted);
+  if (!resolved.startsWith(cwd + sep) && resolved !== cwd) return null;
+  return resolved;
+}
+
+function extractFilePath(url: string): string {
+  // URL: /fs/file/.deco/blocks/site.json
+  const [, ...segments] = url.split("/file");
+  return segments.join("/file") || "/";
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+async function mtimeFor(filepath: string): Promise<number> {
+  try {
+    const stats = await stat(filepath);
+    return stats.mtimeMs;
+  } catch {
+    return Date.now();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Patch application — matches daemon/fs/common.ts
+// ---------------------------------------------------------------------------
+
+interface Patch {
+  type: "json" | "text";
+  payload: Operation[];
+}
+
+function applyPatch(
+  content: string | null,
+  patch: Patch,
+): { conflict: boolean; content?: string } {
+  try {
+    if (patch.type === "json") {
+      const result = patch.payload.reduce(
+        fjp.applyReducer,
+        JSON.parse(content ?? "{}"),
+      );
+      return { conflict: false, content: JSON.stringify(result, null, 2) };
+    }
+    if (patch.type === "text") {
+      const result = patch.payload.reduce(
+        fjp.applyReducer,
+        content?.split("\n") ?? [],
+      );
+      return { conflict: false, content: (result as string[]).join("\n") };
+    }
+  } catch (err: unknown) {
+    if (
+      err instanceof fjp.JsonPatchError &&
+      err.name === "TEST_OPERATION_FAILED"
+    ) {
+      return { conflict: true };
+    }
+    throw err;
+  }
+  return { conflict: true };
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+export function createFSHandler() {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: () => void,
+  ): Promise<void> => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const { pathname } = url;
+
+    // Only handle /fs/file/* paths
+    if (!pathname.startsWith("/fs/file")) {
+      // Also handle /fs/grep (admin search)
+      if (pathname === "/fs/grep") {
+        // Minimal grep stub — return empty results
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ matches: [], totalMatches: 0 }));
+        return;
+      }
+      next();
+      return;
+    }
+
+    const filePath = extractFilePath(pathname);
+    const systemPath = safePath(filePath);
+
+    if (!systemPath) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Path traversal denied" }));
+      return;
+    }
+
+    // GET /fs/file/* — read file
+    if (req.method === "GET") {
+      try {
+        const [content, metadata, mtime] = await Promise.all([
+          readFile(systemPath, "utf-8"),
+          inferMetadata(systemPath),
+          mtimeFor(systemPath),
+        ]);
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ content, metadata, timestamp: mtime }));
+      } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ timestamp: Date.now() }));
+          return;
+        }
+        throw err;
+      }
+      return;
+    }
+
+    // PATCH /fs/file/* — apply JSON patch
+    if (req.method === "PATCH") {
+      const raw = await readBody(req);
+      let body: { patch: Patch; timestamp: number };
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON" }));
+        return;
+      }
+
+      const mtimeBefore = await mtimeFor(systemPath);
+      let content: string | null;
+      try {
+        content = await readFile(systemPath, "utf-8");
+      } catch {
+        content = null;
+      }
+
+      const result = applyPatch(content, body.patch);
+
+      if (!result.conflict && result.content != null) {
+        const dir = join(systemPath, "..");
+        await mkdir(dir, { recursive: true });
+        await writeFile(systemPath, result.content, "utf-8");
+      }
+
+      const [metadata, mtimeAfter] = await Promise.all([
+        inferMetadata(systemPath),
+        mtimeFor(systemPath),
+      ]);
+
+      // Broadcast change for SSE listeners
+      broadcastFSEvent({
+        type: "fs-sync",
+        detail: {
+          metadata,
+          timestamp: mtimeAfter,
+          filepath: toPosix(systemPath.replace(cwd, "")),
+        },
+      });
+
+      const update = result.conflict
+        ? { conflict: true, metadata, timestamp: mtimeAfter, content }
+        : {
+            conflict: false,
+            metadata,
+            timestamp: mtimeAfter,
+            content: mtimeBefore !== body.timestamp ? result.content : undefined,
+          };
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(update));
+      return;
+    }
+
+    // DELETE /fs/file/*
+    if (req.method === "DELETE") {
+      try {
+        await rm(systemPath, { force: true });
+      } catch {
+        // ignore
+      }
+
+      broadcastFSEvent({
+        type: "fs-sync",
+        detail: {
+          metadata: null,
+          timestamp: Date.now(),
+          filepath: toPosix(systemPath.replace(cwd, "")),
+        },
+      });
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          conflict: false,
+          metadata: null,
+          timestamp: Date.now(),
+        }),
+      );
+      return;
+    }
+
+    res.writeHead(405);
+    res.end();
+  };
+}

package/src/daemon/index.ts

@@ -0,0 +1,8 @@
+export { startTunnel } from "./tunnel";
+export type { TunnelOptions, TunnelConnection } from "./tunnel";
+export { createAuthMiddleware, verifyAdminJwt, tokenIsValid } from "./auth";
+export type { JwtPayload } from "./auth";
+export { createDaemonMiddleware } from "./middleware";
+export type { DaemonOptions } from "./middleware";
+export { createVolumesHandler } from "./volumes";
+export { createWatchHandler, watchFS, broadcastFSEvent } from "./watch";