alpha-gate 0.1.0

package/src/auth/access-jwt.ts

@@ -0,0 +1,210 @@
+// §4 / decision 0006 — Cloudflare Access JWT verification, the security boundary for every admin
+// mutation. Fail CLOSED on any error. alg pinned to RS256 (algorithm-confusion defense); iss/aud
+// checked; ±60s clock skew; the JWKS fetch is an injectable seam so tests use a throwaway keypair.
+// A human one-time-PIN JWT carries `email`; a service-token JWT carries `common_name` (no email).
+
+export interface Jwk {
+  kid?: string;
+  kty?: string;
+  alg?: string;
+  [key: string]: unknown;
+}
+
+export type AccessIdentity =
+  | { kind: "user"; email: string }
+  | { kind: "service"; commonName: string };
+
+export type AccessResult = AccessIdentity | { kind: "reject"; reason: string };
+
+const SKEW_SECONDS = 60;
+const ACCESS_HEADER = "Cf-Access-Jwt-Assertion";
+
+const reject = (reason: string): AccessResult => ({ kind: "reject", reason });
+
+export interface VerifyOptions {
+  jwks: readonly Jwk[];
+  now: number; // unix seconds
+  aud: string;
+  issuer: string;
+}
+
+/** The pure-ish verifier: crypto + claims against a supplied JWKS. No network. */
+export async function verifyAccessJwt(token: string, opts: VerifyOptions): Promise<AccessResult> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return reject("malformed token");
+  const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string];
+
+  let header: Record<string, unknown>;
+  let payload: Record<string, unknown>;
+  let signature: Uint8Array;
+  try {
+    header = JSON.parse(decodeText(encodedHeader)) as Record<string, unknown>;
+    payload = JSON.parse(decodeText(encodedPayload)) as Record<string, unknown>;
+    signature = decodeBytes(encodedSignature);
+  } catch {
+    return reject("unparseable token");
+  }
+
+  if (header.alg !== "RS256") return reject("alg not RS256");
+  const kid = typeof header.kid === "string" ? header.kid : null;
+  const jwk = opts.jwks.find((k) => k.kid === kid) ?? (kid === null ? opts.jwks[0] : undefined);
+  if (jwk === undefined) return reject("unknown kid");
+
+  let valid: boolean;
+  try {
+    const key = await crypto.subtle.importKey(
+      "jwk",
+      jwk as JsonWebKey,
+      { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+      false,
+      ["verify"],
+    );
+    valid = await crypto.subtle.verify(
+      "RSASSA-PKCS1-v1_5",
+      key,
+      signature,
+      new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`),
+    );
+  } catch {
+    return reject("verification error");
+  }
+  if (!valid) return reject("bad signature");
+
+  if (payload.iss !== opts.issuer) return reject("issuer mismatch");
+  const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+  if (!audiences.includes(opts.aud)) return reject("audience mismatch");
+
+  // exp is REQUIRED and must be numeric: a missing/garbled exp must fail closed (decision 0006), not
+  // be treated as never-expiring. nbf/iat are optional but enforced (with skew) when present.
+  if (typeof payload.exp !== "number") return reject("missing or invalid exp");
+  if (opts.now > payload.exp + SKEW_SECONDS) return reject("expired");
+  if (typeof payload.nbf === "number" && opts.now < payload.nbf - SKEW_SECONDS) {
+    return reject("not yet valid");
+  }
+  if (typeof payload.iat === "number" && opts.now < payload.iat - SKEW_SECONDS) {
+    return reject("issued in the future");
+  }
+
+  if (typeof payload.email === "string" && payload.email.length > 0) {
+    return { kind: "user", email: payload.email };
+  }
+  if (typeof payload.common_name === "string" && payload.common_name.length > 0) {
+    return { kind: "service", commonName: payload.common_name };
+  }
+  return reject("no principal claim");
+}
+
+export interface AccessVerifier {
+  verify(headers: Headers): Promise<AccessResult>;
+}
+
+/** A JWKS fetcher: returns the team keys, optionally told which `kid` is wanted (cache refetch hint). */
+export type JwksFetcher = (
+  teamDomain: string,
+  sel?: { kid?: string | null },
+) => Promise<readonly Jwk[]>;
+
+export interface AccessConfig {
+  teamDomain: string | undefined;
+  aud: string | undefined;
+  fetchJwks: JwksFetcher;
+  now: () => number;
+}
+
+/**
+ * The Deps seam. Reads the Access assertion header, fetches the team JWKS (behind fetchJwks — in
+ * production a Worker-global cache, see createCachedJwksFetcher), and verifies — failing closed on
+ * missing config, a missing header, or a JWKS fetch failure. The token's `kid` is passed to the
+ * fetcher so the cache can force a refetch when an unknown key id appears (Cloudflare key rotation).
+ */
+export function createAccessVerifier(config: AccessConfig): AccessVerifier {
+  return {
+    async verify(headers: Headers): Promise<AccessResult> {
+      if (config.teamDomain === undefined || config.aud === undefined) {
+        return reject("Access not configured");
+      }
+      const token = headers.get(ACCESS_HEADER);
+      if (token === null || token.length === 0) return reject("missing Access assertion");
+
+      let jwks: readonly Jwk[];
+      try {
+        jwks = await config.fetchJwks(config.teamDomain, { kid: extractKid(token) });
+      } catch {
+        return reject("JWKS fetch failed");
+      }
+
+      return verifyAccessJwt(token, {
+        jwks,
+        now: config.now(),
+        aud: config.aud,
+        issuer: `https://${config.teamDomain}`,
+      });
+    },
+  };
+}
+
+/** Reads the unverified `kid` from a JWT header (drives the cache refetch); null if absent/garbled. */
+export function extractKid(token: string): string | null {
+  const dot = token.indexOf(".");
+  if (dot <= 0) return null;
+  try {
+    const header = JSON.parse(decodeText(token.slice(0, dot))) as Record<string, unknown>;
+    return typeof header.kid === "string" ? header.kid : null;
+  } catch {
+    return null;
+  }
+}
+
+async function defaultFetchJwks(teamDomain: string): Promise<readonly Jwk[]> {
+  const res = await fetch(`https://${teamDomain}/cdn-cgi/access/certs`);
+  if (!res.ok) throw new Error(`JWKS fetch returned ${res.status}`);
+  const body = (await res.json()) as { keys?: Jwk[] };
+  return body.keys ?? [];
+}
+
+export interface CachedJwksOptions {
+  /** The clock seam (unix seconds) — kept injectable so the TTL is deterministic in tests. */
+  now: () => number;
+  /** The underlying network fetch; defaults to defaultFetchJwks. */
+  fetchJwks?: (teamDomain: string) => Promise<readonly Jwk[]>;
+  /** Cache lifetime; decision 0006 calls for ~10–15 min. Default 600s. */
+  ttlSeconds?: number;
+}
+
+/**
+ * decision 0006 — a JWKS fetcher with a cache keyed by team domain and a short TTL, plus a forced
+ * refetch when the requested `kid` is absent from the cached set (so a Cloudflare key rotation is
+ * picked up at once instead of failing for up to the TTL). Create ONCE at module scope so the cache
+ * lives in Worker-global scope and survives across requests in the same isolate.
+ */
+export function createCachedJwksFetcher(options: CachedJwksOptions): JwksFetcher {
+  const fetchJwks = options.fetchJwks ?? defaultFetchJwks;
+  const ttlSeconds = options.ttlSeconds ?? 600;
+  const cache = new Map<string, { keys: readonly Jwk[]; fetchedAt: number }>();
+
+  return async (teamDomain, sel) => {
+    const entry = cache.get(teamDomain);
+    const fresh = entry !== undefined && options.now() - entry.fetchedAt < ttlSeconds;
+    const wantedKid = sel?.kid ?? null;
+    const hasKid =
+      entry !== undefined && (wantedKid === null || entry.keys.some((k) => k.kid === wantedKid));
+    if (entry !== undefined && fresh && hasKid) return entry.keys;
+
+    const keys = await fetchJwks(teamDomain);
+    cache.set(teamDomain, { keys, fetchedAt: options.now() });
+    return keys;
+  };
+}
+
+function decodeBytes(base64url: string): Uint8Array {
+  const base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function decodeText(base64url: string): string {
+  return new TextDecoder().decode(decodeBytes(base64url));
+}

package/src/auth/token-gate.ts

@@ -0,0 +1,27 @@
+import { isWellFormedToken, normalizeToken } from "../core/tokens";
+import type { Client } from "../core/types";
+import { findByToken } from "../db/clients";
+import type { Deps } from "../deps";
+
+// The public-side token gate used by every /get, /appcast, /download request. Validates shape, then
+// looks the client up by the normalized token. Returns the client for active AND revoked rows (the
+// resolver and routes decide what each gets); an unknown/malformed token is indistinguishable from a
+// revoked one to the outside, so token existence is never confirmed (§6/§16).
+
+export type GateResult =
+  | { kind: "active"; client: Client }
+  | { kind: "revoked"; client: Client }
+  | { kind: "unknown" };
+
+export async function gateToken(
+  deps: Deps,
+  rawToken: string | null | undefined,
+): Promise<GateResult> {
+  if (rawToken === null || rawToken === undefined || !isWellFormedToken(rawToken)) {
+    return { kind: "unknown" };
+  }
+
+  const client = await findByToken(deps.db, normalizeToken(rawToken));
+  if (client === null) return { kind: "unknown" };
+  return client.status === "revoked" ? { kind: "revoked", client } : { kind: "active", client };
+}

package/src/core/appcast.ts

@@ -0,0 +1,107 @@
+import type { Build } from "./types";
+
+// §8/§14/§15 — per-user appcast generation. Pure string building over already-resolved data (the
+// route passes the build + enclosure URL). The out-of-scope Sparkle client depends on this output
+// being exactly right, so every interpolated value is XML-escaped and the shape is golden-tested.
+
+const SPARKLE_NS = "http://www.andymatuschak.org/xml-namespaces/sparkle";
+const ENCLOSURE_TYPE = "application/octet-stream";
+
+/**
+ * Sentinel version for the §15 informational item — fixed, far above any real build_number, and
+ * below INT32 max. Safe permanently because the item carries no enclosure, so Sparkle can never
+ * "install" it regardless of the number (decision 0008). Real build_numbers must stay below this.
+ */
+export const INFORMATIONAL_SENTINEL_VERSION = 999_000_000;
+
+// Shown in Sparkle's dialog in place of the raw sentinel number: sparkle:shortVersionString is the
+// human-readable version string (the sentinel stays the machine-comparable sparkle:version).
+const INFORMATIONAL_DISPLAY_VERSION = "Access renewal";
+
+export interface InformationalNotice {
+  /** The /access page the notice links to. */
+  accessUrl: string;
+  /** Dialog title (already {app_name}-filled by the caller). */
+  title: string;
+  /** Plain-text body, shown as the dialog's release notes (already {app_name}-filled). */
+  message: string;
+}
+
+export function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** The `<item>` Sparkle installs: machine version, enclosure with the fixed EdDSA signature (§8/§14). */
+export function renderUpdateItem(build: Build, enclosureUrl: string): string {
+  const children = [
+    `<title>${xmlEscape(build.shortVersion)}</title>`,
+    `<sparkle:version>${build.buildNumber}</sparkle:version>`,
+    `<sparkle:shortVersionString>${xmlEscape(build.shortVersion)}</sparkle:shortVersionString>`,
+  ];
+
+  if (build.minOs !== null) {
+    children.push(
+      `<sparkle:minimumSystemVersion>${xmlEscape(build.minOs)}</sparkle:minimumSystemVersion>`,
+    );
+  }
+  if (build.critical) {
+    children.push("<sparkle:criticalUpdate></sparkle:criticalUpdate>");
+  }
+  children.push(
+    `<enclosure url="${xmlEscape(enclosureUrl)}" length="${build.length}" type="${ENCLOSURE_TYPE}" sparkle:edSignature="${xmlEscape(build.edSignature)}" />`,
+  );
+
+  return wrapItem(children);
+}
+
+/**
+ * The §15 informational notice for revoked/unknown tokens (decision 0011): a title, a message, the
+ * sentinel `sparkle:version` with a friendly `shortVersionString` (so Sparkle shows "Access renewal",
+ * not "999000000"), an explicit empty `<sparkle:informationalUpdate>` (Sparkle 2's documented marker;
+ * 1.x falls back to "no enclosure → informational"), a `<link>`, and NO enclosure (never installable).
+ */
+export function renderInformationalItem(notice: InformationalNotice): string {
+  return wrapItem([
+    `<title>${xmlEscape(notice.title)}</title>`,
+    `<description>${descriptionCdata(notice.message)}</description>`,
+    `<sparkle:version>${INFORMATIONAL_SENTINEL_VERSION}</sparkle:version>`,
+    `<sparkle:shortVersionString>${xmlEscape(INFORMATIONAL_DISPLAY_VERSION)}</sparkle:shortVersionString>`,
+    "<sparkle:informationalUpdate></sparkle:informationalUpdate>",
+    `<link>${xmlEscape(notice.accessUrl)}</link>`,
+  ]);
+}
+
+// The admin message becomes the dialog's HTML release notes. xmlEscape first so it renders as literal
+// text (no markup/script reaches Sparkle's WebView) — escaping `>` also guarantees the content can't
+// contain `]]>`, so it can't break out of the CDATA. Newlines become <br> for a readable paragraph.
+function descriptionCdata(message: string): string {
+  return `<![CDATA[<p>${xmlEscape(message).replace(/\n/g, "<br>")}</p>]]>`;
+}
+
+export interface AppcastOptions {
+  title: string;
+  items: readonly string[];
+}
+
+/** Wraps zero or more item fragments in the rss/channel document with the sparkle namespace. */
+export function renderAppcast({ title, items }: AppcastOptions): string {
+  const lines = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    `<rss version="2.0" xmlns:sparkle="${SPARKLE_NS}">`,
+    "  <channel>",
+    `    <title>${xmlEscape(title)}</title>`,
+    ...items,
+    "  </channel>",
+    "</rss>",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function wrapItem(children: readonly string[]): string {
+  return ["    <item>", ...children.map((child) => `      ${child}`), "    </item>"].join("\n");
+}

package/src/core/audit-chain.ts

@@ -0,0 +1,145 @@
+// §16 — tamper-evident admin audit hash chain (decision 0005). Pure over plain data (crypto.subtle
+// is used but only over passed-in values). The canonical form is versioned and length-prefixed so it
+// is deterministic and reproducible offline in any language — the basis for the anchor + verification.
+
+const CANON_VERSION = "v1";
+
+/** The audited content of one mutation (everything except the autoincrement id and the hash). */
+export interface AuditFields {
+  actorEmail: string;
+  action: string;
+  target: string | null;
+  detail: string | null;
+  ip: string | null;
+  rayId: string | null;
+  createdAt: string;
+}
+
+/** An entry ready to hash: the fields plus the link to the previous row. */
+export interface AuditEntry extends AuditFields {
+  prevHash: string | null;
+}
+
+/** A stored, hashed row. */
+export interface AuditRow extends AuditEntry {
+  hash: string;
+}
+
+export type VerifyResult = { ok: true } | { ok: false; brokenIndex: number };
+
+// Fixed field order. `prevHash` is part of the canonical input (chain linkage); `id` and `hash` are
+// excluded. Changing the order or set is a breaking change — bump CANON_VERSION if it ever happens.
+const FIELD_ORDER = [
+  "actorEmail",
+  "action",
+  "target",
+  "detail",
+  "ip",
+  "rayId",
+  "createdAt",
+  "prevHash",
+] as const satisfies readonly (keyof AuditEntry)[];
+
+const encoder = new TextEncoder();
+
+/**
+ * Deterministic canonical form: version tag, then each field as `name:<utf8-byte-length>:<value>`
+ * (or `name:null`). Length-prefixing means no value — even one containing newlines or colons — can
+ * forge a field boundary.
+ */
+export function canonicalize(entry: AuditEntry): string {
+  const parts: string[] = [CANON_VERSION];
+  for (const field of FIELD_ORDER) {
+    const value = entry[field];
+    if (value === null) {
+      parts.push(`${field}:null`);
+    } else {
+      parts.push(`${field}:${encoder.encode(value).length}:${value}`);
+    }
+  }
+  return parts.join("\n");
+}
+
+export async function computeHash(entry: AuditEntry): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(canonicalize(entry)));
+  return toHex(digest);
+}
+
+/** Builds the next row: links it to `prevHash` and computes its hash. */
+export async function linkRow(prevHash: string | null, fields: AuditFields): Promise<AuditRow> {
+  const entry: AuditEntry = { ...fields, prevHash };
+  const hash = await computeHash(entry);
+  return { ...entry, hash };
+}
+
+/**
+ * Recomputes each row's hash from its fields and checks both the recomputed hash and the prev_hash
+ * link. Returns the index of the first row that fails (catching edits and mid-chain deletions).
+ */
+export async function verifyChain(rows: readonly AuditRow[]): Promise<VerifyResult> {
+  let prev: string | null = null;
+  for (const [index, row] of rows.entries()) {
+    if (row.prevHash !== prev) return { ok: false, brokenIndex: index };
+    if ((await computeHash(row)) !== row.hash) return { ok: false, brokenIndex: index };
+    prev = row.hash;
+  }
+  return { ok: true };
+}
+
+/** The status the daily anchor records — and the admin Audit page displays live. */
+export interface ChainAssessment {
+  /** The chain verifies AND has not shrunk or diverged from the last anchored head. */
+  intact: boolean;
+  count: number;
+  /** The anchored head this was checked against, or null before the first anchor. */
+  anchored: { hash: string; count: number } | null;
+}
+
+/**
+ * One shared judgment of chain integrity for the anchor cron AND the Audit page (they must never
+ * disagree). `priorRaw` is the stored `audit_anchor_head` meta value (JSON), or null before the
+ * first anchor. A malformed prior is treated as suspicious, exactly like a mismatch.
+ */
+export async function assessChain(
+  rows: readonly AuditRow[],
+  priorRaw: string | null,
+): Promise<ChainAssessment> {
+  let intact = (await verifyChain(rows)).ok;
+  const head = buildHead(rows);
+
+  let prior: { hash: string; count: number } | null = null;
+  if (priorRaw !== null) {
+    try {
+      const parsed = JSON.parse(priorRaw) as { hash?: unknown; count?: unknown };
+      if (typeof parsed.hash === "string" && typeof parsed.count === "number") {
+        prior = { hash: parsed.hash, count: parsed.count };
+      } else {
+        intact = false; // corrupted anchor record — treat as suspicious
+      }
+    } catch {
+      intact = false;
+    }
+  }
+  if (prior !== null) {
+    if (head.count < prior.count) {
+      intact = false; // truncation — newest rows removed
+    } else if (prior.count > 0 && rows[prior.count - 1]?.hash !== prior.hash) {
+      intact = false; // divergence / rebuild
+    }
+  }
+  return { intact, count: head.count, anchored: prior };
+}
+
+/** The chain head for anchoring (§16): the latest hash and the row count. */
+export function buildHead(rows: readonly AuditRow[]): { hash: string; count: number } {
+  const last = rows.at(-1);
+  return { hash: last?.hash ?? "", count: rows.length };
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  let hex = "";
+  for (const byte of new Uint8Array(buffer)) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}

package/src/core/invite-template.ts

@@ -0,0 +1,127 @@
+// §13/§6 — invite text and the branded /get page model. Pure: placeholder fill and default merge.
+// The DEFAULT_INVITE_TEMPLATE here is the runtime fallback when the admin has set nothing in `meta`;
+// templates/invite-email.txt mirrors it as the human-editable canonical (kept in sync by hand).
+
+export interface InviteTemplate {
+  subject: string;
+  body: string;
+}
+
+export interface InviteVars {
+  appName: string;
+  getUrl: string;
+  token: string;
+}
+
+export const DEFAULT_INVITE_TEMPLATE: InviteTemplate = {
+  subject: "You're invited to test {app_name}",
+  body: `Hi,
+
+You've been added to the {app_name} alpha. To get started:
+
+  1. Open your private download page:  {get_url}
+  2. Download and install the app.
+  3. Launch it, then click "Activate" on the page (or paste the key shown there).
+
+That page is yours — revisit it any time to reinstall. It stops working if access is revoked.`,
+};
+
+/**
+ * The §15 reactivation notice shown by Sparkle for a revoked/unknown token (an informational update,
+ * never an install). Editable per-instance via meta.notice_title / meta.notice_message; the message
+ * supports {app_name}. Defaults are clear and action-oriented.
+ */
+export interface AccessNotice {
+  title: string;
+  message: string;
+}
+
+export const DEFAULT_ACCESS_NOTICE: AccessNotice = {
+  title: "Reactivate your access",
+  message:
+    "Your access to {app_name} has expired or been revoked, so updates are paused. " +
+    "Open your access page to get a new activation link.",
+};
+
+/** Replaces just {app_name} — used by text that has no get_url/token (e.g. the §15 access notice). */
+export function fillAppName(text: string, appName: string): string {
+  return text.replace(/\{app_name\}/g, appName);
+}
+
+/** Replaces {app_name}/{get_url}/{token} in one pass (a value can't reintroduce a placeholder). */
+export function fillTemplate(text: string, vars: InviteVars): string {
+  const replacements: Record<string, string> = {
+    "{app_name}": vars.appName,
+    "{get_url}": vars.getUrl,
+    "{token}": vars.token,
+  };
+  return text.replace(
+    /\{app_name\}|\{get_url\}|\{token\}/g,
+    (match) => replacements[match] ?? match,
+  );
+}
+
+export function renderInvite(template: InviteTemplate, vars: InviteVars): InviteTemplate {
+  return {
+    subject: fillTemplate(template.subject, vars),
+    body: fillTemplate(template.body, vars),
+  };
+}
+
+/** The resolved /get page branding (§6). */
+export interface Branding {
+  appName: string;
+  blurb: string | null;
+  accent: string;
+  iconUrl: string | null;
+  headerUrl: string | null;
+}
+
+/** Clean, never-blocking defaults (decision 0003 sibling): neutral name, system blue, no imagery. */
+export const DEFAULT_BRANDING: Branding = {
+  appName: "Your App",
+  blurb: null,
+  accent: "#0A84FF",
+  iconUrl: null,
+  headerUrl: null,
+};
+
+/**
+ * The accent colour is interpolated RAW into a `<style>` on the public pages (no escaping is possible
+ * inside CSS), so it must be a hex colour and nothing else — otherwise a stored value could break out
+ * of the style block. `isValidAccent` gates writes; `safeAccent` coerces any stored value at read time
+ * so the sink is always safe even for data written before this guard existed.
+ */
+export function isValidAccent(value: string): boolean {
+  return /^#[0-9a-fA-F]{3,8}$/.test(value.trim());
+}
+
+export function safeAccent(value: string | null | undefined): string {
+  return value != null && isValidAccent(value) ? value.trim() : DEFAULT_BRANDING.accent;
+}
+
+/**
+ * The macOS app's custom URL scheme for the §7 activation deep link (`<scheme>://activate?token=`).
+ * Per-instance config (it must match the app's Info.plist CFBundleURLSchemes); "myapp" is the default.
+ */
+export const DEFAULT_ACTIVATE_SCHEME = "myapp";
+
+// A valid RFC 3986 scheme: ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ). Restricting to this also keeps
+// the value safe to interpolate into the Activate href (no quotes/spaces/colons to break out of it).
+const SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*$/;
+
+/** The configured activate scheme if it is a well-formed URL scheme, else the safe default. */
+export function resolveActivateScheme(raw: string | null | undefined): string {
+  return typeof raw === "string" && SCHEME_RE.test(raw) ? raw : DEFAULT_ACTIVATE_SCHEME;
+}
+
+/** Merges admin overrides (from `meta` / R2 asset URL) over the defaults; ignores undefined. */
+export function resolveBranding(overrides: Partial<Branding>): Branding {
+  return {
+    appName: overrides.appName ?? DEFAULT_BRANDING.appName,
+    blurb: overrides.blurb ?? DEFAULT_BRANDING.blurb,
+    accent: overrides.accent ?? DEFAULT_BRANDING.accent,
+    iconUrl: overrides.iconUrl ?? DEFAULT_BRANDING.iconUrl,
+    headerUrl: overrides.headerUrl ?? DEFAULT_BRANDING.headerUrl,
+  };
+}