@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/src/built-script-syntax.mjs

@@ -0,0 +1,480 @@
+// Built-output script syntax gate (#480).
+//
+// A campaign-owned script that does not parse throws a SyntaxError on every
+// load of every page that references it, and nothing it defines runs. The
+// shape that shipped: a template-family checkout script copied and
+// hand-edited, left with one closing `});` too many. Page Kit built it, every
+// other doctor gate read the HTML and passed, and doctor reported the build
+// ready.
+//
+// This gate parses every campaign-owned `.js` file a built page loads by a
+// LOCAL `<script src>`, with acorn at the latest ecmaVersion: `sourceType:
+// 'script'` for classic scripts and `'module'` for `type="module"`, which is
+// how the browser reads each. A parse failure is an error naming the file, the
+// line and the column. Remote scripts (CDN URLs, protocol-relative, data:)
+// are not campaign-owned and are not read. A referenced local file that does
+// not exist on disk is a warning (#502): the browser gets a 404 for it and
+// nothing it would define runs, but whether the page needs it is not known
+// here, so it does not block.
+//
+// Not waivable: a script that cannot be parsed cannot be intended to ship.
+// Both doctor entry points drive it, like the other static built-output gates.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, isAbsolute, posix, relative, resolve, sep } from "node:path";
+
+import { parse as parseJs } from "acorn";
+import { parse as parseHtml } from "parse5";
+
+export const SCRIPT_SYNTAX = "built_output.script_syntax";
+export const SCRIPT_SYNTAX_PARSE_FAILURE = `${SCRIPT_SYNTAX}.parse_failure`;
+export const SCRIPT_SYNTAX_MISSING_SCRIPT = `${SCRIPT_SYNTAX}.missing_script`;
+
+// Classic script MIME types the browser executes. Anything else with a type
+// attribute (JSON-LD, text/template, importmap) is a data block, not script.
+const CLASSIC_SCRIPT_TYPE = /^(?:text|application)\/(?:x-)?(?:java|ecma)script$|^text\/(?:javascript1\.[0-5]|jscript|livescript)$/i;
+
+/**
+ * How a module-capable browser treats a `<script>` element, from its
+ * attributes: "classic", "module", or null when it never runs it. Follows the
+ * HTML "prepare the script element" steps: an absent or empty type (or, with
+ * no type, an absent or empty language) is classic; otherwise the type has
+ * leading and trailing ASCII whitespace stripped and is compared
+ * ASCII-case-insensitively. `nomodule` stops only classic scripts; a module
+ * script ignores it.
+ *
+ * @param {Record<string, string>} attrs
+ * @returns {"classic" | "module" | null}
+ */
+export function scriptKind(attrs) {
+  // The script block's type string, as the HTML steps build it: an empty
+  // type, or no type with an empty or absent language, is text/javascript; a
+  // type attribute is stripped of ASCII whitespace; otherwise "text/" plus the
+  // language attribute, unstripped.
+  const hasType = typeof attrs.type === "string";
+  const hasLanguage = typeof attrs.language === "string";
+  let type;
+  if (hasType ? attrs.type === "" : !hasLanguage || attrs.language === "") type = "text/javascript";
+  else if (hasType) type = attrs.type.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+  else type = `text/${attrs.language}`;
+  let kind = null;
+  if (type.toLowerCase() === "module") kind = "module";
+  else if (CLASSIC_SCRIPT_TYPE.test(type)) kind = "classic";
+  if (kind === "classic" && "nomodule" in attrs) return null;
+  return kind;
+}
+
+// Acorn messages that are fixed text. Anything else interpolates source text
+// (an identifier, a regex body, a character) and is reduced to its category,
+// so a token at the error site never reaches doctor or QA output.
+const FIXED_PARSE_MESSAGES = new Set([
+  "Unexpected token", "Unterminated string constant", "Unterminated template", "Unterminated template literal",
+  "Unterminated regular expression", "Unterminated comment", "Invalid regular expression flag",
+  "Duplicate regular expression flag", "Invalid number", "Identifier directly after number", "Assigning to rvalue",
+  "'return' outside of function", "'import' and 'export' may appear only with 'sourceType: module'",
+  "'import' and 'export' may only appear at the top level", "Cannot use 'import.meta' outside a module",
+  "Cannot use keyword 'await' outside an async function", "'super' keyword outside a method",
+  "super() call outside constructor of a subclass", "Illegal newline after throw", "Missing catch or finally clause",
+  "Multiple default clauses", "Argument name clash", "Redefinition of property", "Redefinition of __proto__ property",
+  "Bad escape sequence in untagged template literal", "Invalid use of 'super'", "'with' in strict mode",
+  "Deleting local variable in strict mode", "let is disallowed as a lexically bound name",
+  "Shorthand property assignments are valid only in destructuring patterns",
+  "Complex binding patterns require an initialization value", "Comma is not permitted after the rest element",
+  "Binding member expression", "Binding parenthesized expression", "Not enough stack space to parse input",
+  "Optional chaining cannot appear in left-hand side",
+  "Logical expressions and coalesce expressions cannot be mixed. Wrap either by parentheses",
+]);
+const PARSE_MESSAGE_CATEGORIES = [
+  [/^Invalid regular expression\b/, "Invalid regular expression"],
+  [/^Identifier .* has already been declared$/, "Identifier has already been declared"],
+  [/^Unexpected character\b/, "Unexpected character"],
+  [/^Unexpected keyword\b/, "Unexpected keyword"],
+  [/^The keyword .* is reserved$/, "Reserved keyword"],
+  [/^Label .* is already declared$/, "Duplicate label"],
+  [/^Duplicate export\b/, "Duplicate export"],
+  [/^Undefined export\b/, "Undefined export"],
+  [/^Unsyntactic (?:break|continue)$/, "Unsyntactic break or continue"],
+  [/^Escape sequence in keyword\b/, "Escape sequence in keyword"],
+  [/^Private field\b/, "Undeclared private field"],
+  [/^Expected number in radix\b/, "Invalid number"],
+  [/in strict mode$/, "Not allowed in strict mode"],
+];
+
+/**
+ * A parser error as a fixed-vocabulary category plus a 1-based position. The
+ * message never carries source text: acorn interpolates identifiers, regex
+ * bodies and characters from the script into some messages.
+ *
+ * @param {unknown} error
+ * @returns {{ line: number, column: number, message: string }}
+ */
+export function parseFailureDiagnostic(error) {
+  const line = Number.isInteger(error?.loc?.line) ? error.loc.line : 1;
+  const column = Number.isInteger(error?.loc?.column) ? error.loc.column + 1 : 1;
+  const raw = String(error?.message || "").replace(/\s*\(\d+:\d+\)$/, "");
+  let message = "Syntax error";
+  if (FIXED_PARSE_MESSAGES.has(raw)) message = raw;
+  else {
+    const category = PARSE_MESSAGE_CATEGORIES.find(([pattern]) => pattern.test(raw));
+    if (category) message = category[1];
+  }
+  return { line, column, message };
+}
+
+/**
+ * Parse one script the way the browser would read it.
+ *
+ * @param {string} source
+ * @param {{ module?: boolean }} [options]
+ * @returns {null | { line: number, column: number, message: string }}
+ *   null when the source parses; otherwise the 1-based position and a
+ *   source-free diagnostic category (see parseFailureDiagnostic).
+ */
+export function parseScriptSyntax(source, { module = false } = {}) {
+  try {
+    parseJs(String(source ?? ""), {
+      ecmaVersion: "latest",
+      sourceType: module ? "module" : "script",
+      allowHashBang: true,
+      locations: true,
+    });
+    return null;
+  } catch (error) {
+    return parseFailureDiagnostic(error);
+  }
+}
+
+export const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+
+/**
+ * A URL attribute value as the URL parser reads it: leading and trailing C0
+ * controls and space removed, nothing else (not U+00A0 or other Unicode
+ * whitespace, which String#trim would also strip).
+ *
+ * @param {string} value
+ */
+export function stripUrlSpace(value) {
+  return String(value).replace(/^[\u0000-\u0020]+|[\u0000-\u0020]+$/g, "");
+}
+
+/**
+ * Every HTML-namespace `<base href>` in a parse5 document (parsed with
+ * `sourceCodeLocationInfo`), in tree order, with the source offset at which
+ * the parser inserted it. An SVG or MathML `base` is not a base element.
+ *
+ * @param {object} root a parse5 node
+ * @returns {Array<{ href: string, offset: number }>}
+ */
+export function documentBases(root) {
+  const bases = [];
+  const walk = (node) => {
+    if (node.tagName === "base" && node.namespaceURI === HTML_NAMESPACE) {
+      const href = (node.attrs || []).find((attr) => attr.name === "href");
+      if (href) bases.push({ href: href.value, offset: node.sourceCodeLocation?.startOffset ?? -1 });
+    }
+    // Template content is a separate fragment in parse5 and never walked here.
+    for (const child of node.childNodes || []) walk(child);
+  };
+  walk(root);
+  return bases;
+}
+
+/**
+ * The `<base href>` in effect when the parser prepares a script element: the
+ * parser prepares it at its end tag, and "prepare the script element" parses
+ * `src` then, against the document base URL, which is the first base element
+ * with an href in tree order among those already in the document. Foster
+ * parenting can place a base parsed earlier after the script in tree order
+ * (it still counts) or one parsed later before it (it does not), so this
+ * compares source offsets rather than tree position. null when no base was
+ * in the document yet.
+ *
+ * @param {Array<{ href: string, offset: number }>} bases from documentBases
+ * @param {object} scriptNode a parse5 script element
+ * @returns {string | null}
+ */
+export function baseInEffect(bases, scriptNode) {
+  const location = scriptNode?.sourceCodeLocation;
+  const preparedAt = location?.endTag?.startOffset ?? location?.endOffset ?? Infinity;
+  const base = bases.find((entry) => entry.offset < preparedAt);
+  return base ? base.href : null;
+}
+
+/**
+ * `<script src>` references on a page, in document order, with whether each
+ * is a module and the `<base href>` in effect when the browser prepares it
+ * (see baseInEffect), plus the document's first `<base href>` (null when
+ * none). A `<base>` parsed after a script does not move it, whether the
+ * script is async, deferred or a module: its URL is resolved when prepared,
+ * not when fetched.
+ *
+ * Only HTML-namespace script elements are references: an SVG `<script>`
+ * never loads a `src` attribute. Data-block types are dropped. Classic
+ * `nomodule` scripts are dropped: a
+ * module-capable browser never fetches or runs them, so they cannot fail on
+ * load there. A module script ignores `nomodule` and is kept (see scriptKind).
+ * Template content and noscript are inert and not walked.
+ *
+ * @param {string} html
+ * @returns {{ base: string | null, refs: Array<{ src: string, module: boolean, base: string | null }> }}
+ */
+export function pageScriptDocument(html) {
+  const refs = [];
+  let document;
+  try {
+    document = parseHtml(String(html ?? ""), { sourceCodeLocationInfo: true });
+  } catch {
+    return { base: null, refs };
+  }
+  const bases = documentBases(document);
+  const walk = (node) => {
+    const attrs = node.tagName ? Object.fromEntries((node.attrs || []).map((attr) => [attr.name, attr.value])) : {};
+    // Only an HTML-namespace <script> loads its `src`; an SVG script reads
+    // href / xlink:href, and a MathML "script" is not a script element.
+    if (node.tagName === "script" && node.namespaceURI === HTML_NAMESPACE) {
+      const kind = scriptKind(attrs);
+      // "prepare the script element" skips only an empty src; anything else,
+      // even whitespace, is parsed as a URL and fetched.
+      if (kind && typeof attrs.src === "string" && attrs.src !== "") {
+        refs.push({ src: stripUrlSpace(attrs.src), module: kind === "module", base: baseInEffect(bases, node) });
+      }
+    }
+    if (node.tagName === "noscript") return;
+    for (const child of node.childNodes || []) walk(child);
+  };
+  walk(document);
+  return { base: bases[0]?.href ?? null, refs };
+}
+
+/**
+ * The frozen base URL of a `<base href>` (HTML "set the frozen base URL"):
+ * the href parsed against the document's fallback base URL (its own URL),
+ * falling back to that URL when the parse fails or yields a `data:` or
+ * `javascript:` URL, which the browser refuses as a base.
+ *
+ * @param {string | null} href the base element's href, or null for none
+ * @param {string} documentUrl
+ * @returns {string} the URL scripts resolve against
+ */
+export function frozenBaseUrl(href, documentUrl) {
+  if (href === null || href === undefined) return documentUrl;
+  let url;
+  try {
+    url = new URL(href, documentUrl);
+  } catch {
+    return documentUrl;
+  }
+  return url.protocol === "data:" || url.protocol === "javascript:" ? documentUrl : url.href;
+}
+
+/** The `<script src>` references of pageScriptDocument, without any base. */
+export function pageScriptReferences(html) {
+  return pageScriptDocument(html).refs.map(({ src, module }) => ({ src, module }));
+}
+
+// A synthetic origin standing in for wherever the built site is served. Page
+// URLs are their path under the site root; a script URL on any other origin
+// is not campaign-owned.
+const BUILT_ORIGIN = "http://built-site.invalid";
+
+function pageUrlFor(siteRoot, builtPath) {
+  const rel = relative(siteRoot, builtPath);
+  const segments = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel.split(sep) : [basename(builtPath)];
+  return `${BUILT_ORIGIN}/${segments.map(encodeURIComponent).join("/")}`;
+}
+
+// The browser's view of one reference: the URL it resolves to against the
+// base in effect when the script was prepared. null when that URL is not on
+// the built origin.
+function resolveScriptUrl(src, base, pageUrl) {
+  let url;
+  try {
+    url = new URL(src, frozenBaseUrl(base, pageUrl));
+  } catch {
+    return { remote: false, pathname: null };
+  }
+  if (url.origin !== BUILT_ORIGIN) return { remote: true, pathname: null };
+  return { remote: false, pathname: url.pathname };
+}
+
+// Decode a URL path the way a static server does before it maps it onto the
+// disk, then keep it inside `root`. null for a malformed escape, a NUL, or a
+// path that escapes the root.
+function fileUnder(root, pathname) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0")) return null;
+  const rootAbs = resolve(root);
+  const path = resolve(rootAbs, `.${posix.normalize(`/${decoded.replace(/\\/g, "/")}`)}`);
+  return path === rootAbs || path.startsWith(`${rootAbs}${sep}`) ? path : null;
+}
+
+function isRemote(src) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//");
+}
+
+function relFrom(root, path) {
+  const rel = relative(root, path);
+  return rel && !rel.startsWith("..") ? rel.split(sep).join("/") : path;
+}
+
+/**
+ * Resolve every built page's local script references against the filesystem.
+ * Each src resolves as the browser resolves it: against the base in effect
+ * when the script is prepared (the first `<base href>` before it in tree
+ * order, else the page URL; a `data:`, `javascript:` or unparsable base falls
+ * back to the page URL), with the page URL being its path under the site
+ * root. The resulting path is
+ * percent-decoded and mapped under the site root first (page-kit emits
+ * `/<slug>/js/...`), then the campaign directory (a root-served campaign
+ * emits `/js/...`), never outside either. A base or src on another origin is
+ * remote and not read.
+ *
+ * @param {{ site_root: string, campaign_dir: string, pages: Array<{ page_id: string, built_path: string }> }} scope
+ * @param {string} targetRepo
+ */
+export function collectBuiltScriptSyntaxInputs(scope, targetRepo) {
+  const scripts = new Map();
+  const unresolved = new Map();
+  const pages = Array.isArray(scope?.pages) ? scope.pages : [];
+  for (const page of pages) {
+    let html;
+    try {
+      html = readFileSync(page.built_path, "utf8");
+    } catch {
+      continue;
+    }
+    const { refs } = pageScriptDocument(html);
+    const pageUrl = pageUrlFor(scope.site_root, page.built_path);
+    for (const ref of refs) {
+      if (isRemote(ref.src)) continue;
+      const { remote, pathname } = resolveScriptUrl(ref.src, ref.base, pageUrl);
+      if (remote) continue;
+      let path = null;
+      if (pathname) {
+        const candidates = [fileUnder(scope.site_root, pathname), fileUnder(scope.campaign_dir, pathname)].filter(Boolean);
+        path = candidates.find((candidate) => existsSync(candidate)) || null;
+      }
+      let isFile = false;
+      try {
+        isFile = Boolean(path) && existsSync(path) && statSync(path).isFile();
+      } catch {
+        isFile = false;
+      }
+      if (!isFile) {
+        const entry = unresolved.get(ref.src) || { src: ref.src, pages: [] };
+        if (!entry.pages.includes(page.page_id)) entry.pages.push(page.page_id);
+        unresolved.set(ref.src, entry);
+        continue;
+      }
+      const key = `${resolve(path)}\u0000${ref.module ? "module" : "script"}`;
+      if (!scripts.has(key)) {
+        let content = null;
+        try {
+          content = readFileSync(path, "utf8");
+        } catch {
+          content = null;
+        }
+        if (content == null) continue;
+        scripts.set(key, { file: relFrom(targetRepo, resolve(path)), module: ref.module, content, pages: [] });
+      }
+      const entry = scripts.get(key);
+      if (!entry.pages.includes(page.page_id)) entry.pages.push(page.page_id);
+    }
+  }
+  return { pages_scanned: pages.length, scripts: [...scripts.values()], unresolved: [...unresolved.values()] };
+}
+
+function gateBase(subject) {
+  return {
+    id: SCRIPT_SYNTAX,
+    scope: SCRIPT_SYNTAX,
+    waivable: false,
+    subject: subject && typeof subject === "object" ? subject : {},
+    waiver: null,
+  };
+}
+
+/**
+ * Evaluate the syntax of the campaign-owned scripts built pages load. Pure:
+ * the caller hands in script contents.
+ *
+ * @param {{ subject?: object, pages_scanned?: number,
+ *   scripts?: Array<{ file: string, module?: boolean, content: string, pages?: string[] }>,
+ *   unresolved?: Array<{ src: string, pages: string[] }> }} input
+ */
+export function evaluateBuiltScriptSyntax({ subject, pages_scanned: pagesScanned = 0, scripts = [], unresolved = [] } = {}) {
+  const list = Array.isArray(scripts) ? scripts : [];
+  const missing = Array.isArray(unresolved) ? unresolved : [];
+  // A local script the page loads that is not in the built output: a 404 at
+  // runtime. A warning, not a blocker (#502).
+  const warned = missing.map((entry) => {
+    const pages = Array.isArray(entry.pages) ? entry.pages : [];
+    return {
+      code: SCRIPT_SYNTAX_MISSING_SCRIPT,
+      src: entry.src,
+      pages,
+      message: `${entry.src} is loaded by a local <script src>${pages.length ? ` on ${pages.join(", ")}` : ""} but is not in the built output. The browser gets a 404 for it and nothing it would define runs. Add the file to the build, or remove the reference if the page does not need it.`,
+    };
+  });
+  const missingNote = warned.length ? ` ${warned.length} referenced local script(s) are not in the built output.` : "";
+  const common = { scripts_unresolved: missing, warned, pages_scanned: pagesScanned };
+  if (list.length === 0) {
+    return {
+      ...gateBase(subject),
+      status: "not_applicable",
+      code: `${SCRIPT_SYNTAX}.not_applicable`,
+      reason: (pagesScanned
+        ? `No built page loads a campaign-owned script from disk (${pagesScanned} page(s) read).`
+        : "No built page was available to scan; script syntax is checked once pages are built.") + missingNote,
+      findings: [],
+      scripts_scanned: 0,
+      ...common,
+      required_actions: [],
+    };
+  }
+
+  const findings = [];
+  for (const script of list) {
+    const failure = parseScriptSyntax(script.content, { module: Boolean(script.module) });
+    if (!failure) continue;
+    const pages = Array.isArray(script.pages) ? script.pages : [];
+    findings.push({
+      code: SCRIPT_SYNTAX_PARSE_FAILURE,
+      file: script.file,
+      line: failure.line,
+      column: failure.column,
+      source_type: script.module ? "module" : "script",
+      pages,
+      message: `${script.file}:${failure.line}:${failure.column}: ${failure.message}. The browser throws a SyntaxError loading this ${script.module ? "module" : "script"}${pages.length ? ` on ${pages.join(", ")}` : ""}, and nothing in it runs. Fix the syntax at that position (a stray or missing bracket is the usual cause) and rebuild.`,
+    });
+  }
+
+  if (findings.length) {
+    return {
+      ...gateBase(subject),
+      status: "blocked",
+      code: SCRIPT_SYNTAX_PARSE_FAILURE,
+      reason: `${findings.length} of ${list.length} campaign-owned script(s) do not parse: ${findings.map((finding) => `${finding.file}:${finding.line}:${finding.column}`).join(", ")}.${missingNote}`,
+      findings,
+      scripts_scanned: list.length,
+      ...common,
+      required_actions: findings.map((finding) => `Fix the syntax error in ${finding.file} at line ${finding.line}, column ${finding.column}, then rebuild.`),
+    };
+  }
+
+  return {
+    ...gateBase(subject),
+    status: "pass",
+    code: `${SCRIPT_SYNTAX}.pass`,
+    reason: `All ${list.length} campaign-owned script(s) loaded by ${pagesScanned} built page(s) parse.${missingNote}`,
+    findings: [],
+    scripts_scanned: list.length,
+    ...common,
+    required_actions: [],
+  };
+}

package/src/built-site-scope.mjs

@@ -18,6 +18,18 @@ import { basename, join, relative, sep } from "node:path";
 
 const HTML_EXT = ".html";
 
+// The route tokens inferPageType reads for the funnel roles, exported so a
+// caller can tell which token produced a guess (#529: an explicit "upsell"
+// word is a stronger signal than "oto"). Tested against the lower-cased,
+// trimmed route.
+export const ROUTE_TOKENS = Object.freeze({
+  downsell: /down[\s_/-]*sell/,
+  upsell: /up[\s_/-]*sell/,
+  one_time_offer: /(^|[\s_/-])oto([\s_/-]|\d|$)|one[\s_/-]*time[\s_/-]*offer/,
+  receipt: /thank|receipt|confirm(ation)?|order[\s_/-]*complete/,
+  checkout: /checkout|\bcart\b|\border\b/,
+});
+
 // Funnel page-type inference from a built route or filename. Order matters:
 // downsell is tested before upsell, and the broad fallbacks (landing/page) run
 // last. Returns one of the page types QA understands; "page" for generic
@@ -25,10 +37,10 @@ const HTML_EXT = ".html";
 export function inferPageType(routeOrName) {
   const value = String(routeOrName || "").toLowerCase().trim();
   if (value === "" || value === "/" || value === "index") return "landing";
-  if (/down[\s_/-]*sell/.test(value)) return "downsell";
-  if (/up[\s_/-]*sell|(^|[\s_/-])oto([\s_/-]|\d|$)|one[\s_/-]*time[\s_/-]*offer/.test(value)) return "upsell";
-  if (/thank|receipt|confirm(ation)?|order[\s_/-]*complete/.test(value)) return "receipt";
-  if (/checkout|\bcart\b|\border\b/.test(value)) return "checkout";
+  if (ROUTE_TOKENS.downsell.test(value)) return "downsell";
+  if (ROUTE_TOKENS.upsell.test(value) || ROUTE_TOKENS.one_time_offer.test(value)) return "upsell";
+  if (ROUTE_TOKENS.receipt.test(value)) return "receipt";
+  if (ROUTE_TOKENS.checkout.test(value)) return "checkout";
   // The two-step bundle-selection step. Deliberately narrow, and anchored on
   // BOTH ends: the route must *be* about choosing a bundle, not merely contain
   // the words. An editorial "/our-choose-bundle-guide/" stays generic rather

package/src/campaigns-api-key.mjs

@@ -0,0 +1,99 @@
+// Where the Campaigns API key comes from, and why a candidate key was rejected.
+import {
+  isNonEmptyString,
+  optionalString,
+  firstNonEmptyString,
+  readJsonIfExists,
+  resolveFromFile,
+} from "./cli-helpers.mjs";
+
+// The Campaigns API key VALUE for this packet, for the remit's X-Campaign-Key
+// header (the receiver's tenant join). Same precedence as the doctor's
+// presence check (resolveCampaignsApiKey): packet, then the packet-local
+// CampaignSpec, then the declared env source. Campaign keys are
+// public-by-design; the value is sent as a header, never written into the
+// record. Best-effort: any read problem resolves to null (unscoped remit).
+// A campaign key is an opaque token; the receiver hashes it. The shape gate
+// below is about what is NOT a campaign key: whitespace, JSON, a URL, a
+// multi-kilobyte blob. The env source is additionally restricted to variable
+// names that name a campaign key, so a packet cannot point `api_key_source`
+// at an arbitrary secret (`env:AWS_SECRET_ACCESS_KEY`) and have its value
+// travel as a header.
+const CAMPAIGN_KEY_SHAPE = /^[A-Za-z0-9._-]{8,256}$/;
+// A variable name that names a campaign key: upper-case, starts with a letter,
+// and contains CAMPAIGN anywhere — including at the start, so the documented
+// default `CAMPAIGNS_API_KEY` qualifies (a leading `[A-Z]` that consumed the C
+// used to refuse exactly that name and `CAMPAIGN_KEY`).
+const CAMPAIGN_KEY_ENV_NAME = /^(?=[A-Z])[A-Z0-9_]*CAMPAIGN[A-Z0-9_]*$/;
+
+function campaignKeyOrNull(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  return CAMPAIGN_KEY_SHAPE.test(trimmed) ? trimmed : null;
+}
+
+// Resolve the key AND why a present value was refused. A value that is there
+// but the wrong shape is a different operator problem from no value at all —
+// a typo, a quoted key, a whole JSON blob pasted into the env var, the wrong
+// secret exported under a campaign-key name — and the caller must be able to
+// say which, naming the SOURCE (the env var, or the packet field) and never
+// the value. `rejected` is null when nothing was refused.
+export function resolveCampaignsApiKeySource(packet, packetPath, env = process.env, { spec: loadedSpec = undefined } = {}) {
+  const packetRaw = firstNonEmptyString(packet?.campaign?.campaigns_api_key, packet?.campaign?.api_key);
+  if (isNonEmptyString(packetRaw)) {
+    const packetKey = campaignKeyOrNull(packetRaw);
+    if (packetKey) return { key: packetKey, origin: packet?.campaign?.campaigns_api_key ? "packet.campaign.campaigns_api_key" : "packet.campaign.api_key", rejected: null };
+    return { key: null, origin: null, rejected: { kind: "malformed", source: packet?.campaign?.campaigns_api_key ? "packet.campaign.campaigns_api_key" : "packet.campaign.api_key" } };
+  }
+  try {
+    // A caller that already holds the packet-local CampaignSpec (doctor) hands
+    // it in; otherwise it is read from the packet's local_path.
+    const localSpecPath = packet?.spec?.local_path;
+    if (loadedSpec !== undefined || (isNonEmptyString(localSpecPath) && isNonEmptyString(packetPath))) {
+      const spec = loadedSpec !== undefined ? loadedSpec : readJsonIfExists(resolveFromFile(packetPath, localSpecPath));
+      // Name the field the value actually came from: a refused source the
+      // operator cannot find in their CampaignSpec is worse than no name.
+      const specField = [
+        ["campaign.campaigns_api_key", spec?.campaign?.campaigns_api_key],
+        ["campaigns_api_key", spec?.campaigns_api_key],
+        ["campaign.api_key", spec?.campaign?.api_key],
+      ].find(([, value]) => isNonEmptyString(value));
+      if (specField) {
+        const specKey = campaignKeyOrNull(specField[1]);
+        if (specKey) return { key: specKey, origin: `the packet-local CampaignSpec ${specField[0]}`, rejected: null };
+        return { key: null, origin: null, rejected: { kind: "malformed", source: `the packet-local CampaignSpec ${specField[0]}` } };
+      }
+    }
+  } catch {
+    // unreadable spec — fall through to env
+  }
+  const source = optionalString(packet?.campaign?.api_key_source);
+  if (source && source.startsWith("env:")) {
+    const envName = source.slice("env:".length).trim();
+    if (!CAMPAIGN_KEY_ENV_NAME.test(envName)) {
+      return { key: null, origin: null, rejected: { kind: "unsupported_env_name", source: `api_key_source "env:${envName}"` } };
+    }
+    const raw = env?.[envName];
+    if (isNonEmptyString(raw)) {
+      const envKey = campaignKeyOrNull(raw);
+      if (envKey) return { key: envKey, origin: `env:${envName}`, rejected: null };
+      return { key: null, origin: null, rejected: { kind: "malformed", source: `env:${envName}` } };
+    }
+  }
+  return { key: null, origin: null, rejected: null };
+}
+
+// Back-compat shape: the key value or null, for callers that only need the
+// header value.
+export function resolveCampaignsApiKeyValue(packet, packetPath, env = process.env) {
+  return resolveCampaignsApiKeySource(packet, packetPath, env).key;
+}
+
+// One sentence an operator can act on, naming the refused source and never
+// its value. `null` when nothing was refused.
+export function describeCampaignKeyRejection(rejected) {
+  if (!rejected) return null;
+  if (rejected.kind === "unsupported_env_name") {
+    return `${rejected.source} does not name a campaign key, so its value was not read (an api_key_source env var must match ${CAMPAIGN_KEY_ENV_NAME.source}). No credential was taken from it.`;
+  }
+  return `the Campaigns API key from ${rejected.source} is not a campaign-key shape (expected ${CAMPAIGN_KEY_SHAPE.source} — 8-256 chars of letters, digits, dot, dash, underscore, one line, no whitespace) and was refused before any request. Fix the value at that source; it is not printed here.`;
+}