@stelstone/server 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelstone/server",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Runtime-agnostic CMS server built on the Web Fetch API, with pluggable adapters for content, media, auth, and build.",
   "license": "MIT",
   "repository": {

package/src/adapters/basic-auth.mjs

@@ -1,4 +1,5 @@
 import crypto from "crypto";
+import { issueMediaToken as mintMediaToken } from "./media-token.mjs";
 
 /**
  * HTTP Basic auth + HMAC-SHA256 JWT for media tokens.
@@ -24,6 +25,8 @@ export function createBasicAuth({
   users,
   jwtSecret,
   jwtTtl,
+  mediaTokenTtl,
+  mediaKeyVersion,
   realm = "Admin",
 }) {
   // Normalise: prefer `users` array, fall back to single user/pass pair.
@@ -51,23 +54,17 @@ export function createBasicAuth({
   }
 
   function issueMediaToken(tenantId) {
-    if (!jwtSecret) throw new Error("JWT_SECRET not set");
-    const header = Buffer.from(
-      JSON.stringify({ alg: "HS256", typ: "JWT" }),
-    ).toString("base64url");
-    const payload = Buffer.from(
-      JSON.stringify({
-        sub: user,
-        tenant_id: tenantId,
-        iat: Math.floor(Date.now() / 1000),
-        exp: Math.floor(Date.now() / 1000) + jwtTtl,
-      }),
-    ).toString("base64url");
-    const sig = crypto
-      .createHmac("sha256", jwtSecret)
-      .update(`${header}.${payload}`)
-      .digest("base64url");
-    return `${header}.${payload}.${sig}`;
+    // Derived per tenant, and short-lived — see adapters/media-token.mjs.
+    // It used to be signed with the root secret and live as long as an admin
+    // session (8h in some configs), which is both wider and longer than an
+    // upload needs.
+    return mintMediaToken({
+      root: jwtSecret,
+      tenantId,
+      sub: user,
+      ttl: mediaTokenTtl,
+      keyVersion: mediaKeyVersion,
+    });
   }
 
   /**

package/src/adapters/github-content.mjs

@@ -408,13 +408,15 @@ export function createGitHubContent({ token, owner, repo, branch, draftBranch, p
       ? { deferredPublish: true, perEntryPublish: true }
       : { deferredPublish: false, perEntryPublish: false },
 
-    async pendingChanges() {
+    /** @param {string} [target] branch to compare against; defaults to the deploy branch */
+    async pendingChanges(target) {
       if (!draftMode) return { hasChanges: false, changedFiles: 0, files: [] };
       await ensureDraftBranch();
+      const against = target || branch;
       // One compare call: which files differ between published and draft?
       // (GitHub caps the file list at 300 — orders of magnitude above any
       // real collection here; still, say so rather than rely on it silently.)
-      const cmp = await apiGet(`/compare/${branch}...${draftBranch}`);
+      const cmp = await apiGet(`/compare/${against}...${draftBranch}`);
       const files = (cmp?.files ?? [])
         .filter((f) => f.filename.startsWith(`${pagesDir}/`))
         // Index manifests live on the draft branch only — the site build
@@ -437,16 +439,22 @@ export function createGitHubContent({ token, owner, repo, branch, draftBranch, p
      * references them by SHA — nothing is re-uploaded. A `removed` status
      * becomes a tree entry with `sha: null`, which is how git-data deletes.
      *
+     * `target` names the branch to land on, so one panel can push the same
+     * drafts to a preview site first and to the live site after. The caller
+     * resolves it from the configured list — an arbitrary branch name must
+     * never reach here from a request.
+     *
      * @param {string} [message]
-     * @param {{ entries?: {collection: string, file: string}[] }} [opts]
+     * @param {{ entries?: {collection: string, file: string}[], target?: string }} [opts]
      */
-    async publish(message, { entries } = {}) {
+    async publish(message, { entries, target } = {}) {
+      const toBranch = target || branch;
       if (!draftMode) {
         // Writes are committed instantly; trigger is external (Netlify webhook on push)
         return { ok: true, message: "All changes are already committed to GitHub" };
       }
       await ensureDraftBranch();
-      const pending = await this.pendingChanges();
+      const pending = await this.pendingChanges(toBranch);
       if (!pending.hasChanges) return { ok: false, message: "No changes to publish" };
 
       const scoped = Array.isArray(entries) && entries.length > 0;
@@ -472,7 +480,7 @@ export function createGitHubContent({ token, owner, repo, branch, draftBranch, p
       let lastErr;
       for (let attempt = 0; attempt < 2; attempt++) {
         try {
-          const refData = await apiGet(`/git/ref/heads/${branch}`);
+          const refData = await apiGet(`/git/ref/heads/${toBranch}`);
           const baseCommitSha = refData.object.sha;
           const baseCommit = await apiGet(`/git/commits/${baseCommitSha}`);
           const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
@@ -483,11 +491,11 @@ export function createGitHubContent({ token, owner, repo, branch, draftBranch, p
             tree: newTree.sha,
             parents: [baseCommitSha],
           });
-          await apiPatch(`/git/refs/heads/${branch}`, { sha: newCommit.sha });
+          await apiPatch(`/git/refs/heads/${toBranch}`, { sha: newCommit.sha });
           const shortSha = newCommit.sha.slice(0, 7);
           return {
             ok: true,
-            message: `Published ${targets.length} file(s) to ${branch} (${shortSha})`,
+            message: `Published ${targets.length} file(s) to ${toBranch} (${shortSha})`,
             sha: newCommit.sha,
             shortSha,
             branch,

package/src/adapters/github-oauth.mjs

@@ -1,4 +1,5 @@
 import crypto from "crypto";
+import { issueMediaToken as mintMediaToken } from "./media-token.mjs";
 
 /**
  * GitHub OAuth adapter — drop-in replacement for createBasicAuth.
@@ -37,6 +38,8 @@ export function createGitHubOAuth({
   roles = {},
   jwtSecret,
   jwtTtl = 8 * 60 * 60,
+  mediaTokenTtl,
+  mediaKeyVersion,
   defaultRole = "editor",
   realm = "Admin",
 }) {
@@ -143,7 +146,14 @@ export function createGitHubOAuth({
     /** @param {string} capability */
     supports: (capability) => ["mediaToken", "session", "oauth"].includes(capability),
     issueMediaToken(tenantId) {
-      return issueToken({ sub: "media", tenant_id: tenantId, type: "media" });
+      // Not issueToken(): that signs a session with the root secret and the
+      // session TTL. A media token is derived per tenant and short-lived.
+      return mintMediaToken({
+        root: jwtSecret,
+        tenantId,
+        ttl: mediaTokenTtl,
+        keyVersion: mediaKeyVersion,
+      });
     },
     verify,
     issueSessionToken,

package/src/adapters/media-token.mjs

@@ -0,0 +1,77 @@
+/**
+ * The token the admin sends to the media CDN when it uploads.
+ *
+ * It is signed with a key DERIVED from the CDN root secret, not with the root
+ * itself:
+ *
+ *   key = HMAC-SHA256(root, "jwt:v1:<tenant_id>:<keyVersion>")
+ *
+ * The CDN derives the same key from its own copy of the root and compares. Two
+ * things follow, and both are the point:
+ *
+ *   - The tenant id is bound into the key. A token minted for tenant A cannot
+ *     be replayed as tenant B: changing the claim selects a key the holder
+ *     cannot produce.
+ *   - Rotating one tenant is a counter bump on that tenant's row, with a grace
+ *     window in which the previous version still verifies. Nothing else has to
+ *     be redeployed.
+ *
+ * Signing with the raw root — which is what this used to do — worked only
+ * because the CDN still accepts it (LEGACY_JWT). That path treats the root as
+ * a master key for every tenant at once, so it is being retired.
+ *
+ * `keyVersion` has to match what the CDN holds for the tenant. It defaults to
+ * 1, which is where a tenant starts; after a `tenants.mjs rotate-keys`, raise
+ * it here inside the grace window.
+ */
+import crypto from "node:crypto";
+
+/** Must match KEY_PURPOSE_JWT in the CDN's lambda/auth.mjs. */
+const KEY_PURPOSE_JWT = "jwt";
+
+/** Ten minutes. An upload takes seconds; the token has no reason to outlive it. */
+export const DEFAULT_MEDIA_TOKEN_TTL = 600;
+
+/**
+ * @param {string} root       the CDN root secret
+ * @param {string} tenantId
+ * @param {number} keyVersion
+ */
+export function deriveMediaKey(root, tenantId, keyVersion) {
+  return crypto
+    .createHmac("sha256", root)
+    .update(`${KEY_PURPOSE_JWT}:v1:${tenantId}:${keyVersion}`)
+    .digest();
+}
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.root        the CDN root secret (JWT_SECRET)
+ * @param {string} opts.tenantId
+ * @param {string} [opts.sub]       who is uploading, for the CDN's logs
+ * @param {number} [opts.ttl]       seconds; kept short on purpose
+ * @param {number} [opts.keyVersion]
+ * @returns {string} a compact JWS
+ */
+export function issueMediaToken({ root, tenantId, sub = "media", ttl, keyVersion = 1 }) {
+  if (!root) throw new Error("JWT_SECRET not set");
+  if (!tenantId) throw new Error("media.tenantId not set — a media token names one tenant");
+
+  const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
+  const now = Math.floor(Date.now() / 1000);
+
+  // `kid` is not what the CDN selects on — it tries the tenant's active
+  // versions — but it makes a rejected token readable in a log.
+  const header = b64({ alg: "HS256", typ: "JWT", kid: `${tenantId}.v${keyVersion}` });
+  const payload = b64({
+    sub,
+    tenant_id: tenantId,
+    type: "media",
+    iat: now,
+    exp: now + (ttl ?? DEFAULT_MEDIA_TOKEN_TTL),
+  });
+
+  const key = deriveMediaKey(root, tenantId, keyVersion);
+  const sig = crypto.createHmac("sha256", key).update(`${header}.${payload}`).digest("base64url");
+  return `${header}.${payload}.${sig}`;
+}

package/src/core/adapter-options.mjs

@@ -93,6 +93,18 @@ export function githubTemplatesOptions(config, secrets) {
  * @param {SecretLookup} secrets
  * @returns {{ provider: "basic"|"github-oauth"|"cloudflare-access", options: Object }}
  */
+/**
+ * How the admin's media tokens are signed. These live under `media` rather
+ * than `auth` because they describe the CDN tenant, not the login: the key is
+ * derived from the tenant id and the version the CDN holds for it.
+ */
+function mediaTokenOptions(config) {
+  return {
+    mediaTokenTtl: config.media?.tokenTtl,
+    mediaKeyVersion: config.media?.keyVersion ?? 1,
+  };
+}
+
 export function authOptions(config, secrets) {
   const auth = config.auth ?? {};
   const provider = auth.provider ?? "basic";
@@ -108,6 +120,7 @@ export function authOptions(config, secrets) {
         defaultRole: auth.defaultRole,
         jwtSecret: secrets(auth.jwtSecretEnv),
         jwtTtl: auth.jwtTtl,
+        ...mediaTokenOptions(config),
       },
     };
   }
@@ -135,6 +148,7 @@ export function authOptions(config, secrets) {
       })),
       jwtSecret: secrets(auth.jwtSecretEnv),
       jwtTtl: auth.jwtTtl,
+      ...mediaTokenOptions(config),
     },
   };
 }

package/src/core/config-schema.mjs

@@ -86,6 +86,39 @@ function checkContent(config, report, { runtime }) {
   }
 }
 
+/**
+ * `content.publishTargets` gives one panel more than one place to land the
+ * drafts — a preview site first, the live site after. Each id is what a
+ * request may ask for; the branch is never taken from the request.
+ */
+function checkPublishTargets(config, report) {
+  const targets = config.content?.publishTargets;
+  if (targets === undefined) return;
+  if (!Array.isArray(targets) || targets.length === 0) {
+    report.error("content.publishTargets", "must be a non-empty array");
+    return;
+  }
+  if (!config.content?.draftBranch) {
+    report.error(
+      "content.publishTargets",
+      "needs content.draftBranch — without a draft branch saving already publishes, so there is nothing to send anywhere",
+    );
+  }
+  const seen = new Set();
+  targets.forEach((t, i) => {
+    const at = `content.publishTargets[${i}]`;
+    if (!t || typeof t !== "object") return report.error(at, "must be an object");
+    if (!t.id) report.error(`${at}.id`, "is required — this is what the panel sends");
+    if (!t.branch) report.error(`${at}.branch`, "is required — the branch this target lands on");
+    if (!t.label) report.warn(`${at}.label`, "is missing — the button will show the id");
+    if (t.id && seen.has(t.id)) report.error(`${at}.id`, `duplicate target id "${t.id}"`);
+    if (t.id) seen.add(t.id);
+    if (t.branch && t.branch === config.content?.draftBranch) {
+      report.error(`${at}.branch`, "is the draft branch — publishing onto it would be a no-op");
+    }
+  });
+}
+
 function checkAuth(config, report, { getSecret }) {
   const auth = config.auth;
   if (!isPlainObject(auth)) {
@@ -379,6 +412,21 @@ function checkMisc(config, report) {
   if (config.media !== undefined) {
     if (!isPlainObject(config.media)) report.error("media", "must be an object");
     else if (!config.media.cdnBase) report.error("media.cdnBase", "is required when media is configured");
+    else {
+      const { tokenTtl, keyVersion } = config.media;
+      if (tokenTtl !== undefined && (!Number.isInteger(tokenTtl) || tokenTtl < 1)) {
+        report.error("media.tokenTtl", "must be a positive integer (seconds)");
+      }
+      // An upload takes seconds. A long-lived media token is a credential
+      // sitting in a browser for no reason, and the CDN may refuse it outright
+      // when MAX_TOKEN_TTL is set below this.
+      if (Number.isInteger(tokenTtl) && tokenTtl > 3600) {
+        report.warn("media.tokenTtl", `${tokenTtl}s is long for an upload — the CDN may cap it`);
+      }
+      if (keyVersion !== undefined && (!Number.isInteger(keyVersion) || keyVersion < 1)) {
+        report.error("media.keyVersion", "must be a positive integer — the CDN's key version for this tenant");
+      }
+    }
   }
 
   if (config.previewUrl !== undefined && typeof config.previewUrl !== "function") {
@@ -420,6 +468,7 @@ export function validateConfig(config, { runtime = "node", getSecret } = {}) {
   checkCollections(config, report);
   checkForms(config, report, { getSecret: lookup });
   checkBuild(config, report, { getSecret: lookup });
+  checkPublishTargets(config, report);
   checkMisc(config, report);
 
   return { errors: report.errors, warnings: report.warnings };

package/src/default-public-config.mjs

@@ -22,6 +22,11 @@ export function defaultPublicConfig(config, overrides = {}) {
     blocks:            config.blocks,
     content: {
       provider: config.content?.provider || "fs",
+      // Ids and labels only — the branch each maps to stays server-side.
+      publishTargets: (config.content?.publishTargets ?? []).map((t) => ({
+        id: t.id,
+        label: t.label || t.id,
+      })),
       // Whether saving and publishing are separate steps. False only on the
       // github backend without a draft branch — the admin hides Publish there,
       // because saving already published.

package/src/routes.mjs

@@ -580,9 +580,11 @@ export const apiRoutes = [
     method: "POST",
     path: "/api/publish",
     auth: "admin",
-    handler: async ({ adapters }) => {
+    handler: async ({ adapters, config, body }) => {
+      const target = resolveTarget(config, body?.target);
+      if (target.error) return { status: 400, json: { ok: false, message: target.error } };
       try {
-        return ok(await adapters.content.publish());
+        return ok(await adapters.content.publish(null, { target: target.branch }));
       } catch (err) {
         return { status: 500, json: { ok: false, message: err.message } };
       }
@@ -596,7 +598,9 @@ export const apiRoutes = [
     method: "POST",
     path: "/api/collections/:collection/:file/publish",
     auth: "admin",
-    handler: async ({ adapters, params }) => {
+    handler: async ({ adapters, params, config, body }) => {
+      const target = resolveTarget(config, body?.target);
+      if (target.error) return { status: 400, json: { ok: false, message: target.error } };
       if (!adapters.content.capabilities?.perEntryPublish) {
         return {
           status: 501,
@@ -607,6 +611,7 @@ export const apiRoutes = [
         return ok(
           await adapters.content.publish(null, {
             entries: [{ collection: params.collection, file: params.file }],
+            target: target.branch,
           }),
         );
       } catch (err) {
@@ -619,10 +624,12 @@ export const apiRoutes = [
     method: "GET",
     path: "/api/publish/status",
     auth: "any",
-    handler: async ({ adapters }) => {
+    handler: async ({ adapters, config, query }) => {
+      const target = resolveTarget(config, query?.target);
+      if (target.error) return { status: 400, json: { error: target.error } };
       try {
         return ok({
-          ...(await adapters.content.pendingChanges()),
+          ...(await adapters.content.pendingChanges(target.branch)),
           perEntryPublish: !!adapters.content.capabilities?.perEntryPublish,
         });
       } catch (err) {
@@ -652,6 +659,27 @@ export const apiRoutes = [
   },
 ];
 
+/**
+ * Turns a target id from a request into a branch name.
+ *
+ * The id is matched against `content.publishTargets`; a branch name is never
+ * taken from the request itself, or an admin could push the drafts onto any
+ * ref in the repo. No id, or no targets configured, means the deploy branch —
+ * which is what every existing config does.
+ */
+function resolveTarget(config, id) {
+  const targets = config?.content?.publishTargets;
+  if (!id) return { branch: undefined };
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return { error: `Unknown publish target "${id}" — content.publishTargets is not configured` };
+  }
+  const hit = targets.find((t) => t.id === id);
+  if (!hit) {
+    return { error: `Unknown publish target "${id}" — expected one of: ${targets.map((t) => t.id).join(", ")}` };
+  }
+  return { branch: hit.branch };
+}
+
 /**
  * Media endpoints need the auth adapter to mint a CDN token. Ask the port
  * whether it can, instead of calling and handling the exception as a 500.

package/src/version.mjs

@@ -5,4 +5,4 @@
  * require() and no import.meta.url, so reading the manifest at runtime yields
  * "unknown" there.
  */
-export const SERVER_VERSION = "0.28.0";
+export const SERVER_VERSION = "0.30.0";