@stelstone/server 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelstone/server",
-  "version": "0.27.0",
+  "version": "0.29.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/build-github-actions.mjs

@@ -0,0 +1,104 @@
+/**
+ * GitHub Actions workflow runs as the deploy status source.
+ *
+ * For sites whose CI does the deploying — a Worker, a container, an rsync to
+ * a VPS — the workflow run IS the deploy, so its state is the honest thing to
+ * show. The adapter speaks the same vocabulary as the Netlify one so the
+ * admin's pill needs no per-provider knowledge.
+ *
+ * @param {Object} opts
+ * @param {string|undefined} opts.token   repo-scoped token; `actions:read`
+ * @param {string|undefined} opts.owner
+ * @param {string|undefined} opts.repo
+ * @param {string|undefined} opts.workflow  file name ("deploy.yml") or id;
+ *                                          omit to watch every workflow
+ * @param {string|undefined} opts.defaultBranch
+ * @returns {import('./types.mjs').BuildAdapter}
+ */
+import { createGitHubApi } from "./github-api.mjs";
+
+/**
+ * A finished run's conclusion, in the admin's state vocabulary.
+ *
+ * Anything that did not succeed but also did not fail outright — skipped by a
+ * path filter, superseded, stopped by hand — reads as "cancelled": the deploy
+ * did not happen, and that is not the same as a broken build.
+ */
+const CONCLUSION_STATE = {
+  success: "ready",
+  failure: "error",
+  timed_out: "error",
+  startup_failure: "error",
+  action_required: "error",
+  cancelled: "cancelled",
+  skipped: "cancelled",
+  stale: "cancelled",
+  neutral: "cancelled",
+};
+
+/** Queued and waiting-for-approval runs have not started; both are "queued". */
+const PENDING_STATUSES = new Set(["queued", "pending", "waiting", "requested"]);
+
+function runState(run) {
+  if (run.status === "completed") return CONCLUSION_STATE[run.conclusion] || "error";
+  return PENDING_STATUSES.has(run.status) ? "enqueued" : "building";
+}
+
+export function createGitHubActionsBuild({ token, owner, repo, workflow, defaultBranch }) {
+  const configured = Boolean(token && owner && repo);
+  const api = configured ? createGitHubApi({ token, owner, repo }) : null;
+
+  return {
+    configured,
+
+    async getDeployStatus({ branch, sha } = {}) {
+      if (!configured) return { configured: false };
+
+      const query = new URLSearchParams({ per_page: "20" });
+      const targetBranch = branch || defaultBranch;
+      if (targetBranch) query.set("branch", targetBranch);
+      const path = workflow
+        ? `/actions/workflows/${encodeURIComponent(workflow)}/runs?${query}`
+        : `/actions/runs?${query}`;
+
+      const body = await api.apiGet(path);
+      // apiGet answers null on 404 — for a run listing that means the repo,
+      // the workflow name or the token is wrong, not "no runs yet". Say so
+      // instead of returning an empty list the caller would poll forever.
+      if (!body) {
+        const err = new Error(`GitHub API 404 GET ${path}`);
+        err.upstreamStatus = 404;
+        throw err;
+      }
+
+      const runs = body.workflow_runs || [];
+      let run = null;
+      if (sha) {
+        run = runs.find((r) => r.head_sha && r.head_sha.startsWith(sha));
+        // SHA not there yet — the push has not produced a run, keep waiting.
+        if (!run) return { configured: true, deploy: null };
+      }
+      if (!run) run = runs[0] || null;
+      if (!run) return { configured: true, deploy: null };
+
+      return {
+        configured: true,
+        deploy: {
+          id: run.id,
+          state: runState(run),
+          branch: run.head_branch,
+          commitRef: run.head_sha,
+          // Actions knows what it ran, not where the result is published, so
+          // the run page is the only link worth offering.
+          deployUrl: null,
+          adminUrl: run.html_url || null,
+          createdAt: run.created_at,
+          updatedAt: run.updated_at,
+          // A run carries no failure text; the run page has the logs.
+          errorMessage: null,
+          title: run.display_title || run.name || null,
+        },
+      };
+    },
+  };
+}

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/index.mjs

@@ -8,5 +8,6 @@ export { createBasicAuth } from "./basic-auth.mjs";
 export { createGitHubOAuth } from "./github-oauth.mjs";
 export { createCloudflareAccess } from "./cloudflare-access.mjs";
 export { createNetlifyBuild } from "./build-netlify.mjs";
+export { createGitHubActionsBuild } from "./build-github-actions.mjs";
 export { createMediaUrl } from "./media-url.mjs";
 export { createResendMail } from "./resend-mail.mjs";

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

@@ -16,20 +16,29 @@
 /** @typedef {(name: string) => string|undefined} SecretLookup */
 
 /**
- * Options for `createGitHubContent`.
- * @param {Object} config
+ * GITHUB_REPO ("owner/repo") overrides the config — set where the secrets
+ * already live, so a deploy-button user never edits a file. Lenient about
+ * pasted URLs: the last two path segments are the coordinates.
+ *
  * @param {SecretLookup} secrets
+ * @returns {{owner?: string, repo?: string}}
  */
-export function githubContentOptions(config, secrets) {
-  // GITHUB_REPO ("owner/repo") overrides the config — set where the secrets
-  // already live, so a deploy-button user never edits a file. Lenient about
-  // pasted URLs: the last two path segments are the coordinates.
-  const repoEnv = String(secrets("GITHUB_REPO") ?? "")
+function repoFromEnv(secrets) {
+  const parts = String(secrets("GITHUB_REPO") ?? "")
     .replace(/\.git$/, "")
     .split(/[/:]/)
     .filter(Boolean)
     .slice(-2);
-  const [envOwner, envRepo] = repoEnv.length === 2 ? repoEnv : [];
+  return parts.length === 2 ? { owner: parts[0], repo: parts[1] } : {};
+}
+
+/**
+ * Options for `createGitHubContent`.
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ */
+export function githubContentOptions(config, secrets) {
+  const { owner: envOwner, repo: envRepo } = repoFromEnv(secrets);
   return {
     token: secrets(config.content.githubTokenEnv || "GITHUB_TOKEN"),
     owner: envOwner || config.content.owner,
@@ -84,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";
@@ -99,6 +120,7 @@ export function authOptions(config, secrets) {
         defaultRole: auth.defaultRole,
         jwtSecret: secrets(auth.jwtSecretEnv),
         jwtTtl: auth.jwtTtl,
+        ...mediaTokenOptions(config),
       },
     };
   }
@@ -126,6 +148,7 @@ export function authOptions(config, secrets) {
       })),
       jwtSecret: secrets(auth.jwtSecretEnv),
       jwtTtl: auth.jwtTtl,
+      ...mediaTokenOptions(config),
     },
   };
 }
@@ -135,11 +158,54 @@ export function netlifyBuildOptions(config, secrets) {
   return {
     token: secrets(config.build?.netlifyTokenEnv || "NETLIFY_AUTH_TOKEN"),
     siteId: secrets(config.build?.netlifySiteIdEnv || "NETLIFY_SITE_ID"),
-    defaultBranch:
-      secrets("STAGING_BRANCH") || config.content?.publishBranch || config.content?.branch,
+    defaultBranch: buildDefaultBranch(config, secrets),
   };
 }
 
+/**
+ * The branch whose deploy the admin's status pill follows. `STAGING_BRANCH`
+ * wins for the same reason it does for content: it is what redirects a whole
+ * deployment onto another branch.
+ */
+function buildDefaultBranch(config, secrets) {
+  return secrets("STAGING_BRANCH") || config.content?.publishBranch || config.content?.branch;
+}
+
+/**
+ * Which build adapter to construct, and with what.
+ *
+ * Mirrors `authOptions`: the caller stays free of the naming rules and only
+ * has to map a provider name onto a factory. Netlify remains the default so
+ * existing configs keep working untouched.
+ *
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ * @returns {{provider: string, options: object}}
+ */
+export function buildOptions(config, secrets) {
+  const build = config.build ?? {};
+  const provider = build.provider ?? "netlify";
+
+  if (provider === "github-actions") {
+    // Defaults to the repo the content already comes from — for a site whose
+    // CI deploys it, that is nearly always the same repo, and the token that
+    // reads content can read its runs.
+    const { owner: envOwner, repo: envRepo } = repoFromEnv(secrets);
+    return {
+      provider,
+      options: {
+        token: secrets(build.githubTokenEnv || config.content?.githubTokenEnv || "GITHUB_TOKEN"),
+        owner: envOwner || build.owner || config.content?.owner,
+        repo: envRepo || build.repo || config.content?.repo,
+        workflow: build.workflow,
+        defaultBranch: buildDefaultBranch(config, secrets),
+      },
+    };
+  }
+
+  return { provider: "netlify", options: netlifyBuildOptions(config, secrets) };
+}
+
 /**
  * Options for `createCdnProxyMedia`.
  * @param {Object} config

package/src/core/config-schema.mjs

@@ -321,6 +321,53 @@ function checkForward(forward, at, report, getSecret) {
   }
 }
 
+/**
+ * `build` decides where the admin's deploy pill gets its status. It is
+ * optional — a site with no CI simply shows no pill — but a misspelled
+ * provider silently falls back to Netlify, which for a site that does not use
+ * Netlify means a pill that never resolves. Name it.
+ */
+function checkBuild(config, report, { getSecret }) {
+  const build = config.build;
+  if (build === undefined) return;
+  if (typeof build !== "object" || build === null) {
+    report.error("build", "must be an object");
+    return;
+  }
+
+  const provider = build.provider ?? "netlify";
+  if (!["netlify", "github-actions"].includes(provider)) {
+    report.error("build.provider", `unknown provider "${provider}" — expected netlify or github-actions`);
+    return;
+  }
+
+  if (provider === "github-actions") {
+    const owner = build.owner || config.content?.owner;
+    const repo = build.repo || config.content?.repo;
+    // GITHUB_REPO can supply both at runtime, so this is a warning: the
+    // coordinates may well arrive from the environment.
+    if (!owner || !repo) {
+      report.warn(
+        "build",
+        "owner/repo not in the config — deploy status needs them, from build.owner/build.repo, content, or GITHUB_REPO",
+      );
+    }
+    const tokenEnv = build.githubTokenEnv || config.content?.githubTokenEnv || "GITHUB_TOKEN";
+    if (!getSecret(tokenEnv)) {
+      report.warn("build.githubTokenEnv", `${tokenEnv} is not set — deploy status is unavailable`);
+    }
+    return;
+  }
+
+  for (const [key, fallback] of [
+    ["netlifyTokenEnv", "NETLIFY_AUTH_TOKEN"],
+    ["netlifySiteIdEnv", "NETLIFY_SITE_ID"],
+  ]) {
+    const name = build[key] || fallback;
+    if (!getSecret(name)) report.warn(`build.${key}`, `${name} is not set — deploy status is unavailable`);
+  }
+}
+
 function checkMisc(config, report) {
   const { locales, defaultLocale } = config;
   if (locales !== undefined && !Array.isArray(locales)) {
@@ -332,6 +379,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") {
@@ -372,6 +434,7 @@ export function validateConfig(config, { runtime = "node", getSecret } = {}) {
   checkAuth(config, report, { getSecret: lookup });
   checkCollections(config, report);
   checkForms(config, report, { getSecret: lookup });
+  checkBuild(config, report, { getSecret: lookup });
   checkMisc(config, report);
 
   return { errors: report.errors, warnings: report.warnings };
@@ -445,7 +508,10 @@ export function describeConfig(config, { adapters, getSecret, runtime = "node" }
     lines.push(`media    ${config.media.cdnBase}${config.media.tenantId ? ` (tenant: ${config.media.tenantId})` : ""}`);
   }
   if (adapters?.build) {
-    lines.push(`build    netlify — ${adapters.build.configured ? "configured" : "not configured"}`);
+    const buildProvider = config.build?.provider ?? "netlify";
+    lines.push(
+      `build    ${buildProvider} — ${adapters.build.configured ? "configured" : "not configured"}`,
+    );
   }
 
   const collections = Object.keys(config.collections || {});

package/src/server.mjs

@@ -12,7 +12,7 @@ import {
   fsContentOptions,
   githubTemplatesOptions,
   authOptions,
-  netlifyBuildOptions,
+  buildOptions,
   cdnMediaOptions,
   mailOptions,
 } from "./core/adapter-options.mjs";
@@ -25,6 +25,7 @@ import {
   createGitHubOAuth,
   createCloudflareAccess,
   createNetlifyBuild,
+  createGitHubActionsBuild,
   createFsTemplates,
   createGitHubTemplates,
   createResendMail,
@@ -79,7 +80,11 @@ export function createCmsServer({ config, rootDir, publicConfig: publicConfigFn,
   // No media config → no CDN adapter; the media routes answer 404 instead
   // of every /api request dying while the adapter bag is built.
   const cdnMedia = config.media ? createCdnProxyMedia(cdnMediaOptions(config, auth)) : undefined;
-  const build = createNetlifyBuild(netlifyBuildOptions(config, secrets));
+  const { provider: buildProvider, options: buildOpts } = buildOptions(config, secrets);
+  const build =
+    buildProvider === "github-actions"
+      ? createGitHubActionsBuild(buildOpts)
+      : createNetlifyBuild(buildOpts);
 
   const templates = useGitHub
     ? createGitHubTemplates(githubTemplatesOptions(config, secrets))

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.27.0";
+export const SERVER_VERSION = "0.29.0";