@decocms/start 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -60,7 +60,8 @@
     "./scripts/generate-invoke": "./scripts/generate-invoke.ts",
     "./scripts/migrate": "./scripts/migrate.ts",
     "./scripts/tailwind-lint": "./scripts/tailwind-lint.ts",
-    "./vite": "./src/vite/plugin.js"
+    "./vite": "./src/vite/plugin.js",
+    "./daemon": "./src/daemon/index.ts"
   },
   "scripts": {
     "build": "tsc",
@@ -90,7 +91,10 @@
     "access": "public"
   },
   "dependencies": {
-    "tsx": "^4.19.0"
+    "@deco-cx/warp-node": "^0.3.16",
+    "fast-json-patch": "^3.1.0",
+    "tsx": "^4.19.0",
+    "ws": "^8.18.0"
   },
   "peerDependencies": {
     "@microlabs/otel-cf-workers": ">=1.0.0-rc.0",
@@ -119,6 +123,7 @@
     "@tanstack/react-query": "^5.96.0",
     "@tanstack/store": "^0.9.1",
     "@types/react": "^19.0.0",
+    "@types/ws": "^8.18.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^29.0.0",
     "knip": "^5.86.0",

package/src/admin/decofile.ts

@@ -1,6 +1,6 @@
-import { getRevision, loadBlocks, setBlocks } from "../cms/loader";
-import { clearLoaderCache } from "../sdk/cachedLoader";
-import { invalidateMetaCache } from "./meta";
+import { getRevision, loadBlocks, setBlocks } from "../cms/loader.ts";
+import { clearLoaderCache } from "../sdk/cachedLoader.ts";
+import { invalidateMetaCache } from "./meta.ts";
 
 export function handleDecofileRead(): Response {
   const blocks = loadBlocks();
@@ -20,14 +20,14 @@ export async function handleDecofileReload(
   request: Request,
   env?: Record<string, unknown>,
 ): Promise<Response> {
-  const authHeader = request.headers.get("authorization") || "";
+  const authHeader = request.headers.get("Authorization") || "";
   const expectedToken =
-    (env?.DECO_RELOAD_TOKEN as string | undefined) ??
+    (env?.DECO_RELEASE_RELOAD_TOKEN as string | undefined) ??
     (typeof globalThis.process !== "undefined"
-      ? globalThis.process.env?.DECO_RELOAD_TOKEN
+      ? globalThis.process.env?.DECO_RELEASE_RELOAD_TOKEN
       : undefined);
 
-  if (expectedToken && !authHeader.includes(expectedToken)) {
+  if (!expectedToken || authHeader !== expectedToken) {
     return new Response("Unauthorized", { status: 401 });
   }
 

package/src/admin/index.ts

@@ -16,9 +16,12 @@ export {
   composeMeta,
   getRegisteredLoaders,
   getRegisteredMatchers,
+  type ActionConfig,
   type LoaderConfig,
   type MatcherConfig,
   type MetaResponse,
+  registerActionSchema,
+  registerActionSchemas,
   registerLoaderSchema,
   registerLoaderSchemas,
   registerMatcherSchema,

package/src/admin/meta.ts

@@ -1,8 +1,30 @@
-import { djb2Hex } from "../sdk/djb2";
-import { composeMeta, type MetaResponse } from "./schema";
+import { djb2Hex } from "../sdk/djb2.ts";
+import { composeMeta, type MetaResponse } from "./schema.ts";
 
-let metaData: MetaResponse | null = null;
-let cachedEtag: string | null = null;
+// Use globalThis to share meta state across module instances.
+// The daemon middleware imports this module via native import() (outside Vite SSR),
+// while setup.ts calls setMetaData() via Vite SSR — these are different module instances.
+// globalThis bridges them so both see the same metaData.
+const G = globalThis as unknown as {
+  __deco_meta_data?: MetaResponse | null;
+  __deco_meta_etag?: string | null;
+};
+
+function getMetaData(): MetaResponse | null {
+  return G.__deco_meta_data ?? null;
+}
+
+function setMetaDataInternal(data: MetaResponse | null) {
+  G.__deco_meta_data = data;
+}
+
+function getCachedEtag(): string | null {
+  return G.__deco_meta_etag ?? null;
+}
+
+function setCachedEtag(etag: string | null) {
+  G.__deco_meta_etag = etag;
+}
 
 /**
  * Invalidate the cached ETag so the admin re-fetches meta after a
@@ -12,7 +34,7 @@ let cachedEtag: string | null = null;
  * needed here, keeping this module safe for client-side bundles.
  */
 export function invalidateMetaCache() {
-  cachedEtag = null;
+  setCachedEtag(null);
 }
 
 /**
@@ -21,8 +43,8 @@ export function invalidateMetaCache() {
  * on top of the site-generated section schemas.
  */
 export function setMetaData(data: MetaResponse) {
-  metaData = composeMeta(data);
-  cachedEtag = null;
+  setMetaDataInternal(composeMeta(data));
+  setCachedEtag(null);
 }
 
 /**
@@ -31,14 +53,17 @@ export function setMetaData(data: MetaResponse) {
  * results in a different ETag, forcing admin to re-fetch.
  */
 function getEtag(): string {
-  if (!cachedEtag) {
-    const str = JSON.stringify(metaData || {});
-    cachedEtag = `"meta-${djb2Hex(str)}"`;
+  let etag = getCachedEtag();
+  if (!etag) {
+    const str = JSON.stringify(getMetaData() || {});
+    etag = `"meta-${djb2Hex(str)}"`;
+    setCachedEtag(etag);
   }
-  return cachedEtag;
+  return etag;
 }
 
 export function handleMeta(request: Request): Response {
+  const metaData = getMetaData();
   if (!metaData) {
     return new Response(JSON.stringify({ error: "Schema not initialized" }), {
       status: 503,

package/src/admin/schema.ts

@@ -94,6 +94,64 @@ function getProductListLoaderKeys(): string[] {
   return loaderRegistry.filter((l) => l.tags?.includes("product-list")).map((l) => l.key);
 }
 
+// ---------------------------------------------------------------------------
+// Action definitions — dynamic registry
+// ---------------------------------------------------------------------------
+
+export interface ActionConfig {
+  key: string;
+  title: string;
+  namespace: string;
+  propsSchema: Record<string, any>;
+}
+
+const actionRegistry: ActionConfig[] = [];
+
+/** Register a single action schema for the admin. */
+export function registerActionSchema(config: ActionConfig) {
+  const idx = actionRegistry.findIndex((a) => a.key === config.key);
+  if (idx >= 0) {
+    actionRegistry[idx] = config;
+  } else {
+    actionRegistry.push(config);
+  }
+}
+
+/** Register multiple action schemas at once. */
+export function registerActionSchemas(configs: ActionConfig[]) {
+  for (const config of configs) registerActionSchema(config);
+}
+
+function buildActionDefinitions() {
+  const definitions: Record<string, any> = {};
+  const manifestBlocks: Record<string, any> = {};
+
+  for (const action of actionRegistry) {
+    const defKey = toBase64(action.key);
+
+    definitions[defKey] = {
+      title: action.key,
+      type: "object",
+      required: ["__resolveType"],
+      properties: {
+        __resolveType: {
+          type: "string",
+          enum: [action.key],
+          default: action.key,
+        },
+        props: action.propsSchema,
+      },
+    };
+
+    manifestBlocks[action.key] = {
+      $ref: `#/definitions/${defKey}`,
+      namespace: action.namespace,
+    };
+  }
+
+  return { definitions, manifestBlocks };
+}
+
 // ---------------------------------------------------------------------------
 // Matcher definitions — dynamic registry
 // ---------------------------------------------------------------------------
@@ -774,6 +832,7 @@ export function composeMeta(siteMeta: MetaResponse): MetaResponse {
   const fullSectionAnyOf = [...siteAnyOf, ...fwSections.extraAnyOf];
   const page = buildPageSchema(fullSectionAnyOf);
   const loaders = buildLoaderDefinitions();
+  const actions = buildActionDefinitions();
   const matchers = buildMatcherDefinitions();
 
   const sectionRefDef = { title: "Section", anyOf: fullSectionAnyOf };
@@ -786,6 +845,7 @@ export function composeMeta(siteMeta: MetaResponse): MetaResponse {
     ...fwSections.definitions,
     ...page.definitions,
     ...loaders.definitions,
+    ...actions.definitions,
     ...matchers.definitions,
     [SECTION_REF_DEF_KEY]: sectionRefDef,
     [RESOLVABLE_LITERAL_KEY]: resolvableDef,
@@ -813,6 +873,10 @@ export function composeMeta(siteMeta: MetaResponse): MetaResponse {
           ...(siteMeta.manifest?.blocks?.loaders || {}),
           ...loaders.manifestBlocks,
         },
+        actions: {
+          ...(siteMeta.manifest?.blocks?.actions || {}),
+          ...actions.manifestBlocks,
+        },
         matchers: {
           ...(siteMeta.manifest?.blocks?.matchers || {}),
           ...matchers.manifestBlocks,

package/src/admin/setup.ts

@@ -17,8 +17,11 @@ export {
 } from "./invoke";
 export { setMetaData } from "./meta";
 export {
+  type ActionConfig,
   type LoaderConfig,
   type MatcherConfig,
+  registerActionSchema,
+  registerActionSchemas,
   registerLoaderSchema,
   registerLoaderSchemas,
   registerMatcherSchema,

package/src/cms/loader.ts

@@ -1,5 +1,5 @@
 import * as asyncHooks from "node:async_hooks";
-import { djb2Hex } from "../sdk/djb2";
+import { djb2Hex } from "../sdk/djb2.ts";
 
 export type Resolvable = {
   __resolveType?: string;
@@ -127,9 +127,25 @@ export function withBlocksOverride<T>(override: Record<string, unknown>, fn: ()
   return blocksOverrideStorage.run(override, fn);
 }
 
+// Higher key wins. Compared lexicographically:
+//   [literalSegments, paramSegments, hasNoSplat]
+// So `/foo/bar` > `/foo/:x` > `/foo/*` > `/*`, and `/my-account/*` > `/*`.
+function pathSpecificityKey(path: string): [number, number, number] {
+  const parts = path.split("/").filter(Boolean);
+  let literals = 0;
+  let params = 0;
+  let hasSplat = false;
+  for (const part of parts) {
+    if (part === "*") hasSplat = true;
+    else if (part.startsWith(":") || part.startsWith("$")) params++;
+    else literals++;
+  }
+  return [literals, params, hasSplat ? 0 : 1];
+}
+
 export function getAllPages(): Array<{ key: string; page: DecoPage }> {
   const blocks = loadBlocks();
-  const pages: Array<{ key: string; page: DecoPage; specificity: number }> = [];
+  const pages: Array<{ key: string; page: DecoPage; key2: [number, number, number] }> = [];
 
   for (const [key, block] of Object.entries(blocks)) {
     if (!key.startsWith("pages-")) continue;
@@ -137,16 +153,16 @@ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
     if (!page.sections) continue;
     if (!page.path) continue;
 
-    let specificity = 0;
-    if (page.path === "/*") specificity = 0;
-    else if (page.path.includes(":") || page.path.includes("$")) specificity = 1;
-    else specificity = 2;
-
-    pages.push({ key, page, specificity });
+    pages.push({ key, page, key2: pathSpecificityKey(page.path) });
   }
 
   return pages
-    .sort((a, b) => b.specificity - a.specificity)
+    .sort((a, b) => {
+      for (let i = 0; i < a.key2.length; i++) {
+        if (a.key2[i] !== b.key2[i]) return b.key2[i] - a.key2[i];
+      }
+      return 0;
+    })
     .map(({ key, page }) => ({ key, page }));
 }
 
@@ -156,16 +172,26 @@ function matchPath(pattern: string, urlPath: string): Record<string, string> | n
   const patternParts = pattern.split("/").filter(Boolean);
   const urlParts = urlPath.split("/").filter(Boolean);
 
-  if (patternParts.length !== urlParts.length) return null;
+  // Trailing `*` means "match this prefix and any remaining segments".
+  const hasSplat = patternParts[patternParts.length - 1] === "*";
+  const fixedLen = hasSplat ? patternParts.length - 1 : patternParts.length;
+
+  if (hasSplat) {
+    if (urlParts.length < fixedLen) return null;
+  } else if (urlParts.length !== fixedLen) {
+    return null;
+  }
 
   const params: Record<string, string> = {};
-  for (let i = 0; i < patternParts.length; i++) {
+  for (let i = 0; i < fixedLen; i++) {
     const pp = patternParts[i];
     const up = urlParts[i];
     if (pp.startsWith(":")) params[pp.slice(1)] = up;
     else if (pp !== up) return null;
   }
 
+  if (hasSplat) params._splat = urlParts.slice(fixedLen).join("/");
+
   return params;
 }
 

package/src/cms/resolve.ts

@@ -3,6 +3,7 @@ import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } fro
 import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { djb2Hex } from "../sdk/djb2";
+import { registerLoaderSchemas, registerActionSchemas, type LoaderConfig, type ActionConfig } from "../admin/schema";
 
 // globalThis-backed: share state across Vite server function split modules
 const G = globalThis as any;
@@ -307,6 +308,37 @@ export function registerCommerceLoader(key: string, loader: CommerceLoader) {
 
 export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>) {
   Object.assign(commerceLoaders, loaders);
+
+  // Auto-register loader + action schemas for the admin manifest.
+  // Separate actions (keys containing "/actions/") from loaders.
+  const loaderConfigs: LoaderConfig[] = [];
+  const actionConfigs: ActionConfig[] = [];
+
+  for (const key of Object.keys(loaders)) {
+    const namespace = key.startsWith("vtex/") ? "vtex" : "site";
+    const schema = { type: "object" as const, additionalProperties: true };
+
+    if (key.includes("/actions/")) {
+      actionConfigs.push({ key, title: key, namespace, propsSchema: schema });
+    } else {
+      loaderConfigs.push({ key, title: key, namespace, propsSchema: schema, tags: inferLoaderTags(key) });
+    }
+  }
+
+  registerLoaderSchemas(loaderConfigs);
+  registerActionSchemas(actionConfigs);
+}
+
+function inferLoaderTags(key: string): string[] {
+  if (
+    key.includes("productList") ||
+    key.includes("ProductList") ||
+    key.includes("ProductShelf") ||
+    key.includes("SearchResult")
+  ) {
+    return ["product-list"];
+  }
+  return [];
 }
 
 /** Delete a single commerce loader by key. No-op if key is absent. */

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();
+  };
+}