@stelstone/server 0.26.0

package/src/adapters/cloudflare-access.mjs

@@ -0,0 +1,144 @@
+/**
+ * Cloudflare Access auth adapter.
+ *
+ * Verifies the `Cf-Access-Jwt-Assertion` header (or `CF_Authorization` cookie)
+ * signed by your Cloudflare Access team using RS256. No third-party libraries —
+ * uses Node's built-in `crypto` module.
+ *
+ * cms.config.mjs:
+ *   auth: {
+ *     provider: "cloudflare-access",
+ *     teamDomain: "https://yourteam.cloudflareaccess.com",
+ *     audience:   "your-application-audience-tag",   // from Access app settings
+ *     roles: {                                        // optional: map email → role
+ *       "fatih@example.com": "admin",
+ *     },
+ *     defaultRole: "editor",                          // role when email not in roles map
+ *   }
+ */
+
+import crypto from "crypto";
+
+const JWKS_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.teamDomain   e.g. "https://yourteam.cloudflareaccess.com"
+ * @param {string} opts.audience     Application Audience tag from Cloudflare Access
+ * @param {Object} [opts.roles]      { "email": "admin" | "editor" }
+ * @param {string} [opts.defaultRole]
+ */
+export function createCloudflareAccess({ teamDomain, audience, roles = {}, defaultRole = "editor" }) {
+  const domain = teamDomain.replace(/\/$/, "");
+  const certsUrl = `${domain}/cdn-cgi/access/certs`;
+
+  // JWKS cache
+  let jwksCache = null;
+  let jwksCachedAt = 0;
+
+  async function getJwks() {
+    if (jwksCache && Date.now() - jwksCachedAt < JWKS_TTL_MS) return jwksCache;
+    const res = await fetch(certsUrl);
+    if (!res.ok) throw new Error(`Failed to fetch Cloudflare Access JWKS: ${res.status}`);
+    jwksCache = await res.json();
+    jwksCachedAt = Date.now();
+    return jwksCache;
+  }
+
+  function base64urlDecode(str) {
+    return Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+  }
+
+  function importPublicKey(jwk) {
+    // Cloudflare Access JWKS uses x5c (certificate chain) or n/e (RSA components).
+    if (jwk.x5c?.length) {
+      const pem = `-----BEGIN CERTIFICATE-----\n${jwk.x5c[0].match(/.{1,64}/g).join("\n")}\n-----END CERTIFICATE-----`;
+      return crypto.createPublicKey(pem);
+    }
+    if (jwk.n && jwk.e) {
+      return crypto.createPublicKey({ key: jwk, format: "jwk" });
+    }
+    throw new Error("Unsupported JWK format — no x5c or n/e fields");
+  }
+
+  async function verifyToken(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) throw new Error("Invalid JWT format");
+
+    const [headerB64, payloadB64, sigB64] = parts;
+    const header = JSON.parse(base64urlDecode(headerB64).toString());
+    const payload = JSON.parse(base64urlDecode(payloadB64).toString());
+
+    // Claim validation
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now) throw new Error("JWT expired");
+    if (payload.nbf && payload.nbf > now) throw new Error("JWT not yet valid");
+    if (payload.iss !== domain) throw new Error(`JWT issuer mismatch: ${payload.iss}`);
+    if (audience && payload.aud !== audience && !payload.aud?.includes?.(audience)) {
+      throw new Error("JWT audience mismatch");
+    }
+
+    // Signature verification
+    const jwks = await getJwks();
+    const jwk = jwks.keys?.find((k) => k.kid === header.kid) ?? jwks.keys?.[0];
+    if (!jwk) throw new Error("No matching JWK found");
+
+    const pubKey = importPublicKey(jwk);
+    const verify = crypto.createVerify("RSA-SHA256");
+    verify.update(`${headerB64}.${payloadB64}`);
+    const valid = verify.verify(pubKey, base64urlDecode(sigB64));
+    if (!valid) throw new Error("JWT signature invalid");
+
+    return payload;
+  }
+
+  function extractToken(request) {
+    const header = request.headers.get("cf-access-jwt-assertion");
+    if (header) return header;
+    // Fall back to cookie
+    const cookie = request.headers.get("cookie") || "";
+    const match = cookie.match(/(?:^|;\s*)CF_Authorization=([^;]+)/);
+    return match ? match[1] : null;
+  }
+
+  function resolveUser(payload) {
+    const email = payload.email || payload.sub;
+    const role = roles[email] ?? defaultRole;
+    return { login: email, name: email, role };
+  }
+
+  /**
+   * Cloudflare Access authenticates with its own header (or cookie) rather
+   * than Authorization — which is exactly why the handler passes the whole
+   * Request to `verify` instead of just the Authorization header. Before that,
+   * this adapter had no way to see its own token and returned null
+   * unconditionally.
+   *
+   * @param {Request} request
+   * @returns {Promise<object|null>}
+   */
+  async function verify(request) {
+    const token = extractToken(request);
+    if (!token) return null;
+    try {
+      return resolveUser(await verifyToken(token));
+    } catch (err) {
+      console.warn(`[cloudflare-access] Access denied: ${err.message}`);
+      return null;
+    }
+  }
+
+  return {
+    configured: Boolean(teamDomain && audience),
+    // Cloudflare Access issues no tokens of its own — media is expected to be
+    // protected by Cloudflare's own CDN auth. Callers ask before calling
+    // rather than discovering it as a 500.
+    supports: () => false,
+    issueMediaToken: () => {
+      throw new Error(
+        "cloudflare-access cannot issue media tokens — check auth.supports('mediaToken') first",
+      );
+    },
+    verify,
+  };
+}

package/src/adapters/fs-json-content.mjs

@@ -0,0 +1,302 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { execSync } from "child_process";
+import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue, buildListEntry, relationFields, isEntryFile } from "./_shared.mjs";
+
+const HISTORY_KEEP = 50; // max revisions kept per file
+
+/**
+ * Filesystem-backed content adapter. Pages live as JSON files under
+ * `<rootDir>/<pagesDir>/<collection>/<file>.json`. Publishing means
+ * `git add && commit && push` to a configured branch.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir
+ * @param {string} opts.pagesDir
+ * @param {string} opts.publishBranch
+ * @param {string[]} opts.publishPaths
+ * @param {(timestamp: string) => string} opts.commitMessage
+ * @returns {import('./types.mjs').ContentAdapter}
+ */
+export function createFsJsonContent({
+  rootDir,
+  pagesDir,
+  publishBranch,
+  publishPaths,
+  commitMessage,
+  collections = {},
+}) {
+  const PAGES_DIR = path.join(rootDir, pagesDir);
+  const HISTORY_DIR = path.join(rootDir, ".cms-history");
+  const PATHS_ARG = publishPaths.join(" ");
+
+  function historyDir(collection, file) {
+    return path.join(HISTORY_DIR, sanitize(collection), sanitize(file));
+  }
+
+  function saveHistory(collection, file) {
+    const src = pagePath(collection, file);
+    if (!fs.existsSync(src)) return;
+    const dir = historyDir(collection, file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    fs.copyFileSync(src, path.join(dir, `${ts}.json`));
+    // Prune old revisions beyond HISTORY_KEEP
+    const entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+    while (entries.length > HISTORY_KEEP) {
+      fs.unlinkSync(path.join(dir, entries.shift()));
+    }
+  }
+
+  function git(cmd) {
+    return execSync(`git ${cmd}`, { cwd: rootDir, encoding: "utf-8" }).trim();
+  }
+
+  function pagePath(collection, file) {
+    return path.join(PAGES_DIR, sanitize(collection), sanitize(file));
+  }
+
+  return {
+    async listCollections() {
+      if (!fs.existsSync(PAGES_DIR)) return [];
+      const dirs = fs
+        .readdirSync(PAGES_DIR)
+        .filter((d) => fs.statSync(path.join(PAGES_DIR, d)).isDirectory());
+      return dirs.map((dir) => {
+        const files = fs
+          .readdirSync(path.join(PAGES_DIR, dir))
+          .filter(isEntryFile);
+        return { name: dir, count: files.length };
+      });
+    },
+
+    async listPages(collection, sortConfig = null) {
+      const dir = path.join(PAGES_DIR, sanitize(collection));
+      if (!fs.existsSync(dir)) return null;
+
+      // Build slug→displayName lookups for collections referenced by this
+      // collection's relation fields, so list columns/filters show names
+      // instead of raw slugs.
+      const lookups = {};
+      const targets = Object.values(relationFields(collections[collection]))
+        .flatMap((rel) => rel.collections);
+      for (const target of targets) {
+        if (lookups[target]) continue;
+        const targetDir = path.join(PAGES_DIR, sanitize(target));
+        if (!fs.existsSync(targetDir)) continue;
+        const table = {};
+        for (const f of fs.readdirSync(targetDir)) {
+          if (!isEntryFile(f)) continue;
+          try {
+            const d = JSON.parse(fs.readFileSync(path.join(targetDir, f), "utf-8"));
+            if (d.slug) table[d.slug] = d.meta?.title || d.meta?.name || d.slug;
+          } catch {
+            // Skip unreadable entries
+          }
+        }
+        lookups[target] = table;
+      }
+
+      const files = fs.readdirSync(dir).filter(isEntryFile);
+      const pages = [];
+      for (const file of files) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+          pages.push(buildListEntry(collections[collection], collection, file, data, lookups));
+        } catch (err) {
+          // One corrupt entry must not take down the whole collection listing.
+          console.warn(`[listPages] Skipping unreadable ${collection}/${file}: ${err.message}`);
+        }
+      }
+      return sortPages(pages, sortConfig);
+    },
+
+    async readPage(collection, file) {
+      if (!safeFileName(file)) return null;
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return null;
+      return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    },
+
+    /**
+     * Version token for optimistic concurrency — a hash of the file's bytes.
+     * Content-derived rather than time-derived so it is stable across checkouts
+     * and unaffected by clock skew.
+     */
+    async versionOf(collection, file) {
+      if (!safeFileName(file)) return null;
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return null;
+      return crypto.createHash("sha1").update(fs.readFileSync(filePath)).digest("hex");
+    },
+
+    /**
+     * @param {Object} [opts]
+     * @param {string} [opts.expectedVersion] Refuse the write when the stored
+     *        version no longer matches — the caller edited a stale copy.
+     */
+    async writePage(collection, file, data, { expectedVersion } = {}) {
+      if (expectedVersion !== undefined && expectedVersion !== null) {
+        const current = await this.versionOf(collection, file);
+        if (current && current !== expectedVersion) {
+          const err = new Error("This entry changed since you loaded it.");
+          err.status = 412;
+          throw err;
+        }
+      }
+      saveHistory(collection, file);
+      const filePath = pagePath(collection, file);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    },
+
+    async createPage(collection, data) {
+      const slug = data.slug || data.id || `new-${Date.now()}`;
+      if (!sanitize(slug) || sanitize(slug) !== String(slug)) {
+        // Reject rather than silently stripping characters — otherwise the
+        // file name and data.slug would diverge (e.g. "ürünler" → "rnler").
+        const err = new Error(
+          `Slug "${slug}" contains unsupported characters — use only a-z, 0-9, dots, dashes, underscores.`,
+        );
+        err.status = 400;
+        throw err;
+      }
+      const fileName = `${sanitize(data.lang || "en")}-${sanitize(slug)}.json`;
+      const filePath = pagePath(collection, fileName);
+      if (fs.existsSync(filePath)) {
+        const err = new Error(
+          `An entry already exists for "${data.lang || "en"}/${slug}". Change the slug or language.`,
+        );
+        err.status = 409;
+        throw err;
+      }
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+      return { file: fileName };
+    },
+
+    async deletePage(collection, file) {
+      if (!safeFileName(file)) return null;
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return false;
+      fs.unlinkSync(filePath);
+      return true;
+    },
+
+    async duplicatePage(collection, file) {
+      if (!safeFileName(file)) return null;
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return null;
+      const src = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+
+      const { data, fileName } = buildDuplicateData(src);
+      const dest = pagePath(collection, fileName);
+      const dir = path.dirname(dest);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(dest, JSON.stringify(data, null, 2), "utf-8");
+      return { file: fileName };
+    },
+
+    // What this adapter can do beyond the shared contract. Routes consult
+    // this instead of sniffing methods, and the github adapter declares the
+    // opposite (its writes commit immediately, so publish scope is moot).
+    capabilities: { deferredPublish: true, perEntryPublish: true },
+
+    async pendingChanges() {
+      const status = git(`status --porcelain ${PATHS_ARG}`);
+      const lines = status.split("\n").filter(Boolean);
+      // Porcelain line: "XY path" (rename: "XY old -> new"). Only entries under
+      // pagesDir are attributed to a collection/file; other publishPaths (e.g.
+      // navigation data) still count but stay unattributed.
+      const files = lines.map((line) => {
+        const raw = line.slice(3).split(" -> ").pop().replace(/^"|"$/g, "");
+        const rel = path.relative(pagesDir, raw);
+        const attributed = !rel.startsWith("..") && rel.includes(path.sep);
+        return attributed
+          ? { path: raw, collection: path.dirname(rel), file: path.basename(rel) }
+          : { path: raw };
+      });
+      return { hasChanges: lines.length > 0, changedFiles: lines.length, files };
+    },
+
+    /**
+     * Commit and push. With `entries`, only those records' files are staged
+     * and committed — other editors' unfinished drafts stay out of the
+     * commit. Without it, everything under publishPaths goes (the "publish
+     * all" button and the migration scripts).
+     *
+     * @param {string} [message]
+     * @param {{ entries?: {collection: string, file: string}[] }} [opts]
+     */
+    async publish(message, { entries } = {}) {
+      const scoped = Array.isArray(entries) && entries.length > 0;
+      const pathsArg = scoped
+        ? entries
+            .map(({ collection, file }) => path.relative(rootDir, pagePath(collection, file)))
+            .map((p) => JSON.stringify(p))
+            .join(" ")
+        : PATHS_ARG;
+
+      const status = git(`status --porcelain -- ${pathsArg}`);
+      if (!status) return { ok: false, message: "No changes to publish" };
+
+      // `git add` stages deletions too, so publishing a deleted record works.
+      git(`add -- ${pathsArg}`);
+      const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+      const msg = message || commitMessage(timestamp);
+      git(`commit -m ${JSON.stringify(msg)}`);
+      git(`push origin HEAD:${publishBranch}`);
+
+      const shortSha = git("rev-parse --short HEAD");
+      const sha = git("rev-parse HEAD");
+      return {
+        ok: true,
+        message: `Published to ${publishBranch} (${shortSha})`,
+        sha,
+        shortSha,
+        branch: publishBranch,
+        scope: scoped ? "entries" : "all",
+      };
+    },
+
+    async listHistory(collection, file) {
+      if (!safeFileName(file)) return null;
+      const dir = historyDir(collection, file);
+      if (!fs.existsSync(dir)) return [];
+      return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .sort()
+        .reverse()
+        .map((f) => {
+          const stat = fs.statSync(path.join(dir, f));
+          return { ts: f.replace(".json", ""), size: stat.size };
+        });
+    },
+
+    async restoreHistory(collection, file, ts) {
+      if (!safeFileName(file)) return null;
+      const src = path.join(historyDir(collection, file), sanitize(ts) + ".json");
+      if (!fs.existsSync(src)) return false;
+      const data = JSON.parse(fs.readFileSync(src, "utf-8"));
+      // writePage saves history of current version first, then overwrites
+      await this.writePage(collection, file, data);
+      return true;
+    },
+
+    async writeBatch(items, _message) {
+      if (!items.length) return { ok: true, commitCount: 0 };
+      for (const { collection, file, data } of items) {
+        await this.writePage(collection, file, data);
+      }
+      return { ok: true, commitCount: items.length };
+    },
+
+    async listScheduled() {
+      return listScheduledDue(this);
+    },
+  };
+}

package/src/adapters/fs-templates.mjs

@@ -0,0 +1,57 @@
+import fs from "fs";
+import path from "path";
+import { sanitize, safeFileName } from "./_shared.mjs";
+
+/**
+ * Filesystem-backed block-template adapter. Templates are stored as JSON files
+ * under `<rootDir>/.cms-templates/<slug>.json`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir
+ * @returns {import('./types.mjs').TemplatesAdapter}
+ */
+export function createFsTemplates({ rootDir }) {
+  const DIR = path.join(rootDir, ".cms-templates");
+
+  return {
+    async list() {
+      if (!fs.existsSync(DIR)) return [];
+      return fs
+        .readdirSync(DIR)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+          const data = JSON.parse(fs.readFileSync(path.join(DIR, f), "utf-8"));
+          return {
+            name: data.name,
+            slug: f.replace(".json", ""),
+            blockCount: (data.blocks || []).length,
+          };
+        });
+    },
+
+    async get(slug) {
+      if (!safeFileName(slug)) return null;
+      const file = path.join(DIR, sanitize(slug) + ".json");
+      if (!fs.existsSync(file)) return null;
+      return JSON.parse(fs.readFileSync(file, "utf-8"));
+    },
+
+    async put(slug, data) {
+      if (!safeFileName(slug)) return null;
+      if (!fs.existsSync(DIR)) fs.mkdirSync(DIR, { recursive: true });
+      fs.writeFileSync(
+        path.join(DIR, sanitize(slug) + ".json"),
+        JSON.stringify(data, null, 2),
+        "utf-8",
+      );
+    },
+
+    async delete(slug) {
+      if (!safeFileName(slug)) return null;
+      const file = path.join(DIR, sanitize(slug) + ".json");
+      if (!fs.existsSync(file)) return false;
+      fs.unlinkSync(file);
+      return true;
+    },
+  };
+}

package/src/adapters/github-api.mjs

@@ -0,0 +1,100 @@
+/**
+ * Shared helpers for adapters backed by the GitHub Contents API.
+ *
+ * Returns `{ apiGet, apiPut, apiDelete }` bound to one repo. Each call returns
+ * parsed JSON (or `null` on 404 for GET) and throws on other non-2xx responses.
+ *
+ * Thrown errors carry `upstreamStatus`, so callers can act on the specific
+ * failure — a 409 from a stale blob SHA is a concurrent edit, not a generic
+ * outage — instead of pattern-matching the message.
+ */
+function apiError(status, message) {
+  const err = new Error(message);
+  err.upstreamStatus = status;
+  return err;
+}
+export function createGitHubApi({ token, owner, repo }) {
+  const BASE = `https://api.github.com/repos/${owner}/${repo}`;
+
+  const headers = () => ({
+    Authorization: `Bearer ${token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "User-Agent": "stelstone",
+    "Content-Type": "application/json",
+  });
+
+  async function apiGet(path) {
+    const r = await fetch(`${BASE}${path}`, { headers: headers() });
+    if (r.status === 404) return null;
+    if (!r.ok) throw apiError(r.status, `GitHub API ${r.status} GET ${path}`);
+    return r.json();
+  }
+
+  async function apiPut(path, body) {
+    const r = await fetch(`${BASE}${path}`, {
+      method: "PUT",
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+      const err = await r.json().catch(() => ({}));
+      throw apiError(r.status, `GitHub API ${r.status} PUT ${path}: ${err.message || ""}`);
+    }
+    return r.json();
+  }
+
+  async function apiDelete(path, body) {
+    const r = await fetch(`${BASE}${path}`, {
+      method: "DELETE",
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) throw apiError(r.status, `GitHub API ${r.status} DELETE ${path}`);
+    return r.json();
+  }
+
+  async function apiPost(path, body) {
+    const r = await fetch(`${BASE}${path}`, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+      const err = await r.json().catch(() => ({}));
+      throw apiError(r.status, `GitHub API ${r.status} POST ${path}: ${err.message || ""}`);
+    }
+    return r.json();
+  }
+
+  async function apiPatch(path, body) {
+    const r = await fetch(`${BASE}${path}`, {
+      method: "PATCH",
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+      const err = await r.json().catch(() => ({}));
+      throw apiError(r.status, `GitHub API ${r.status} PATCH ${path}: ${err.message || ""}`);
+    }
+    return r.json();
+  }
+
+  async function graphql(query, variables = {}) {
+    const r = await fetch("https://api.github.com/graphql", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "User-Agent": "stelstone",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+    if (!r.ok) throw new Error(`GitHub GraphQL ${r.status}`);
+    const json = await r.json();
+    if (json.errors?.length) throw new Error(json.errors[0].message);
+    return json.data;
+  }
+
+  return { apiGet, apiPut, apiDelete, apiPost, apiPatch, graphql };
+}