@hegemonart/get-design-done 1.30.5 → 1.31.0

package/scripts/lib/figma-extract/pull.cjs

@@ -0,0 +1,394 @@
+'use strict';
+// scripts/lib/figma-extract/pull.cjs — Plan 31-01 (Wave A.1)
+// Productionized from spike 001 (.planning/spikes/001-figma-offcontext-extractor/extract.mjs).
+//
+// RAW-PULL stage of the two-stage Figma extractor pipeline. Pulls the 5 Figma
+// REST endpoints the spike validated into a local cache dir, writing JSON to
+// disk ONLY. Raw response bodies are never returned to a caller that could log
+// them — they go straight to <outDir>/<name>.json. The digest/markdown stage
+// (Plan 31-02) consumes the cache; this file does ZERO digest work.
+//
+// Decisions honored:
+//   D-01  Two-stage separation: pull.cjs only pulls + caches. No digest here.
+//   D-03  geometry=paths is DROPPED — the file endpoint is /files/:key with no
+//         geometry query param. Saves ~30% raw size for data the digest throws away.
+//   D-10  FIGMA_TOKEN is read from process.env.FIGMA_TOKEN (fallback
+//         FIGMA_PERSONAL_ACCESS_TOKEN) only. It is NEVER written to disk and
+//         NEVER passed to console.log / the logger seam. (31-10 ships a static
+//         analysis test scanning this dir for token persistence/logging.)
+//   D-11  Cache invalidation is content-based via Figma's `version` field, with
+//         a 1h wall-clock TTL fallback when no version field is available.
+//
+// Hardening over the spike: retry-with-backoff on transient 429/5xx, structured
+// per-endpoint timing emitted to an injectable logger seam (NOT raw bodies),
+// file-URL-or-bare-key input via parse-url.cjs, version-based cache skip.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseFigmaFileKey } = require('./parse-url.cjs');
+
+const FIGMA_API_BASE = 'https://api.figma.com/v1';
+
+// Endpoint inventory mirroring the spike's 5 pulls. D-03: the file endpoint is
+// `/files/${k}` with NO `?geometry=paths`. Each entry: { name, path(key)→string,
+// optional?:bool }. `optional` endpoints (Path A Variables) may 403 on
+// non-Enterprise plans and are skipped gracefully rather than aborting the run.
+const DEFAULT_ENDPOINTS = [
+  { name: 'file', path: (k) => `/files/${k}` },
+  { name: 'variables', path: (k) => `/files/${k}/variables/local`, optional: true },
+  { name: 'styles', path: (k) => `/files/${k}/styles` },
+  { name: 'components', path: (k) => `/files/${k}/components` },
+  { name: 'component_sets', path: (k) => `/files/${k}/component_sets` },
+];
+
+// Retry/backoff tuning. Bounded — never an infinite loop.
+const MAX_ATTEMPTS = 4; // 1 initial + 3 retries
+const BACKOFF_BASE_MS = 250; // base × 2^attempt, capped
+const BACKOFF_CAP_MS = 4000;
+const TTL_MS = 60 * 60 * 1000; // 1h wall-clock fallback (D-11)
+
+const noopLogger = { info() {}, warn() {}, error() {} };
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function isTransient(status) {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * Fetch a Figma API path with timing + bounded retry/backoff on transient errors.
+ * Returns { json, ms, bytes } on success. Throws a structured Error after the
+ * retry budget is exhausted, or immediately on a non-transient error.
+ *
+ * The token lives only inside `headers` (caller-provided); it is NEVER logged.
+ */
+async function fetchJson(apiPath, { fetchImpl, headers, logger, sleepImpl }) {
+  const url = `${FIGMA_API_BASE}${apiPath}`;
+  const wait = sleepImpl || sleep;
+  let lastErr;
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const t0 = Date.now();
+    let res;
+    try {
+      res = await fetchImpl(url, { headers });
+    } catch (networkErr) {
+      // Treat raw network/transport failures as transient too.
+      lastErr = networkErr;
+      logger.warn({ event: 'fetch_error', path: apiPath, attempt, message: networkErr.message });
+      if (attempt < MAX_ATTEMPTS - 1) {
+        await wait(Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_CAP_MS));
+        continue;
+      }
+      const e = new Error(`Figma API network failure on ${apiPath}: ${networkErr.message}`);
+      e.path = apiPath;
+      throw e;
+    }
+
+    const ms = Date.now() - t0;
+
+    if (res.ok) {
+      const json = await res.json();
+      const bytes = Buffer.byteLength(JSON.stringify(json), 'utf8');
+      return { json, ms, bytes };
+    }
+
+    // Non-2xx. Read a short body prefix for diagnostics — NEVER the token.
+    let bodyPrefix = '';
+    try {
+      const text = await res.text();
+      bodyPrefix = String(text).slice(0, 200);
+    } catch {
+      bodyPrefix = '';
+    }
+
+    if (isTransient(res.status) && attempt < MAX_ATTEMPTS - 1) {
+      logger.warn({ event: 'transient_retry', path: apiPath, status: res.status, attempt });
+      await wait(Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_CAP_MS));
+      lastErr = new Error(`Figma API ${res.status} on ${apiPath}`);
+      continue;
+    }
+
+    // Non-transient, or transient budget exhausted → structured throw.
+    const err = new Error(`Figma API ${res.status} on ${apiPath}: ${bodyPrefix}`);
+    err.status = res.status;
+    err.path = apiPath;
+    throw err;
+  }
+
+  // Defensive: loop only exits via return/throw above, but guard anyway.
+  const err = lastErr || new Error(`Figma API request failed on ${apiPath}`);
+  err.path = apiPath;
+  throw err;
+}
+
+/**
+ * Write one endpoint's JSON to <outDir>/<name>.json and emit structured timing.
+ * Returns { name, bytes, ms }. The logger receives only { endpoint, bytes, ms } —
+ * never the body, never the token (D-10).
+ */
+function save(outDir, name, data, meta, logger) {
+  const filePath = path.join(outDir, `${name}.json`);
+  const body = JSON.stringify(data);
+  fs.writeFileSync(filePath, body);
+  const bytes = Buffer.byteLength(body, 'utf8');
+  logger.info({ event: 'endpoint_saved', endpoint: name, bytes, ms: meta.ms });
+  return { name, bytes, ms: meta.ms };
+}
+
+function readMetaIfPresent(outDir) {
+  const metaPath = path.join(outDir, '_meta.json');
+  try {
+    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Productionized Figma REST puller.
+ *
+ * @param {object} opts
+ * @param {string} opts.input        - required: bare file key OR full Figma file URL
+ * @param {string} opts.outDir       - required: raw/ cache dir to write *.json into
+ * @param {string} [opts.token]      - defaults to env FIGMA_TOKEN / FIGMA_PERSONAL_ACCESS_TOKEN
+ * @param {Function} [opts.fetchImpl]- injectable fetch (defaults to global fetch)
+ * @param {object} [opts.logger]     - { info(obj), warn(obj), error(obj) } structured sink
+ * @param {Date}   [opts.now]        - deterministic clock for TTL tests
+ * @param {boolean}[opts.forceRefresh]- bypass version/TTL cache check
+ * @param {Function}[opts.sleepImpl] - injectable sleep for fast backoff tests
+ * @returns {Promise<{fileKey,version,cached,endpoints,outDir}>}
+ *
+ * Effect: writes <outDir>/file.json, styles.json, components.json,
+ * component_sets.json (+ variables.json when Path A succeeds) and
+ * <outDir>/_meta.json { file_key, fetched_at, version, totals }.
+ * NEVER returns raw response bodies. NEVER logs/persists `token`.
+ */
+async function pull(opts) {
+  const {
+    input,
+    outDir,
+    token,
+    fetchImpl = globalThis.fetch,
+    logger = noopLogger,
+    now,
+    forceRefresh = false,
+    sleepImpl,
+  } = opts || {};
+
+  if (!input) {
+    throw new TypeError('pull: opts.input (file key or URL) is required');
+  }
+  if (!outDir) {
+    throw new TypeError('pull: opts.outDir (cache dir) is required');
+  }
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError('pull: a fetch implementation is required (global fetch or opts.fetchImpl)');
+  }
+
+  // D-10: token from env only when not explicitly injected. NEVER interpolate
+  // the resolved token into any message, log line, or file.
+  const tok = token || process.env.FIGMA_TOKEN || process.env.FIGMA_PERSONAL_ACCESS_TOKEN;
+  if (!tok) {
+    throw new Error(
+      'FIGMA_TOKEN not set. Export FIGMA_TOKEN=figd_… (get one at ' +
+        'https://www.figma.com/developers/api#access-tokens).'
+    );
+  }
+
+  const headers = { 'X-Figma-Token': tok };
+  const fileKey = parseFigmaFileKey(input);
+  const clock = now instanceof Date ? now : new Date();
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // ── Version probe (D-11) ────────────────────────────────────────────────
+  // Cheapest file call that still returns the `version` field. depth=1 avoids
+  // pulling the full (potentially hundreds-of-MB) node tree just to compare.
+  let probedVersion = null;
+  try {
+    const probe = await fetchJson(`/files/${fileKey}?depth=1`, {
+      fetchImpl,
+      headers,
+      logger,
+      sleepImpl,
+    });
+    probedVersion = probe.json && probe.json.version != null ? probe.json.version : null;
+    logger.info({ event: 'version_probe', endpoint: 'file_probe', version: probedVersion, ms: probe.ms });
+  } catch (probeErr) {
+    // Probe failure should not be fatal on its own — fall through to TTL logic
+    // and let the heavy pull surface a real error if the file is unreachable.
+    logger.warn({ event: 'version_probe_failed', message: probeErr.message });
+    probedVersion = null;
+  }
+
+  // ── Cache check (D-11) ──────────────────────────────────────────────────
+  const cachedMeta = readMetaIfPresent(outDir);
+  if (!forceRefresh && cachedMeta) {
+    const versionMatch =
+      probedVersion != null && cachedMeta.version != null && cachedMeta.version === probedVersion;
+
+    let ttlFresh = false;
+    if (probedVersion == null && cachedMeta.fetched_at) {
+      const age = clock.getTime() - new Date(cachedMeta.fetched_at).getTime();
+      ttlFresh = Number.isFinite(age) && age >= 0 && age < TTL_MS;
+    }
+
+    if (versionMatch || ttlFresh) {
+      logger.info({
+        event: 'cache_hit',
+        reason: versionMatch ? 'version_match' : 'ttl_fresh',
+        version: probedVersion != null ? probedVersion : cachedMeta.version || null,
+      });
+      return {
+        fileKey,
+        version: probedVersion != null ? probedVersion : cachedMeta.version || null,
+        cached: true,
+        endpoints: [],
+        outDir,
+      };
+    }
+  }
+
+  // ── Heavy pull ──────────────────────────────────────────────────────────
+  const endpoints = [];
+  for (const ep of DEFAULT_ENDPOINTS) {
+    const apiPath = ep.path(fileKey);
+    if (ep.optional) {
+      // Path A (Variables): may 403 on non-Enterprise plans → graceful skip.
+      try {
+        const result = await fetchJson(apiPath, { fetchImpl, headers, logger, sleepImpl });
+        endpoints.push(save(outDir, ep.name, result.json, result, logger));
+      } catch (e) {
+        const reason = e.status ? `HTTP ${e.status}` : e.message;
+        logger.warn({ event: 'endpoint_skipped', endpoint: ep.name, reason });
+        endpoints.push({ name: ep.name, bytes: 0, ms: 0, skipped: true, reason });
+      }
+    } else {
+      const result = await fetchJson(apiPath, { fetchImpl, headers, logger, sleepImpl });
+      endpoints.push(save(outDir, ep.name, result.json, result, logger));
+    }
+  }
+
+  // ── Persist _meta.json (D-11 shape, extends spike _meta with version) ─────
+  const meta = {
+    file_key: fileKey,
+    fetched_at: clock.toISOString(),
+    version: probedVersion,
+    totals: endpoints,
+  };
+  fs.writeFileSync(path.join(outDir, '_meta.json'), JSON.stringify(meta, null, 2));
+  logger.info({ event: 'pull_complete', fileKey, version: probedVersion, endpoints: endpoints.length });
+
+  return { fileKey, version: probedVersion, cached: false, endpoints, outDir };
+}
+
+module.exports = { pull, DEFAULT_ENDPOINTS, FIGMA_API_BASE };
+
+// ── CLI entry ───────────────────────────────────────────────────────────────
+// Usage: node scripts/lib/figma-extract/pull.cjs <file-url-or-key> [--out <dir>] [--force]
+//        node scripts/lib/figma-extract/pull.cjs --help
+// FIGMA_TOKEN must be set in the environment (never passed as a flag — D-10).
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+
+  const HELP = `gdd figma-extract pull — raw Figma REST puller (Plan 31-01)
+
+Usage:
+  node scripts/lib/figma-extract/pull.cjs <file-url-or-key> [options]
+
+Arguments:
+  <file-url-or-key>   A Figma file URL (https://www.figma.com/file/<key>/… or
+                      /design/<key>/…) OR a bare file key.
+
+Options:
+  --out <dir>         Raw cache output dir.
+                      Default: .figma-extract-cache/raw/<file-key>
+  --force             Bypass version/TTL cache and re-pull all endpoints.
+  -h, --help          Show this help.
+
+Environment:
+  FIGMA_TOKEN                   Personal access token (required).
+  FIGMA_PERSONAL_ACCESS_TOKEN   Fallback token env var.
+  (The token is read from the environment only — never accepted as a flag,
+   never logged, never written to disk. — D-10)
+
+Notes:
+  - Drops geometry=paths from the file endpoint (D-03).
+  - Skips a 403 Variables endpoint gracefully (Path A, D-04).
+  - Content-version cache invalidation with 1h TTL fallback (D-11).
+  - Writes JSON to disk only; raw bodies never printed (off-context, D-01).
+`;
+
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  // Minimal flag parse — first non-flag token is the input.
+  let input = null;
+  let outDir = null;
+  let forceRefresh = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force') {
+      forceRefresh = true;
+    } else if (a === '--out') {
+      outDir = argv[++i];
+    } else if (!a.startsWith('-') && input === null) {
+      input = a;
+    }
+  }
+
+  if (!input) {
+    process.stderr.write('ERROR: a Figma file URL or key is required.\n\n' + HELP);
+    process.exit(1);
+  }
+
+  // Resolve default outDir lazily so we have the parsed key in the path.
+  (async () => {
+    try {
+      const fileKey = parseFigmaFileKey(input);
+      const resolvedOut =
+        outDir || path.join('.figma-extract-cache', 'raw', fileKey);
+
+      // CLI logger → structured JSON lines on stderr (never the token/body).
+      const cliLogger = {
+        info: (o) => process.stderr.write(JSON.stringify({ level: 'info', ...o }) + '\n'),
+        warn: (o) => process.stderr.write(JSON.stringify({ level: 'warn', ...o }) + '\n'),
+        error: (o) => process.stderr.write(JSON.stringify({ level: 'error', ...o }) + '\n'),
+      };
+
+      const result = await pull({
+        input,
+        outDir: resolvedOut,
+        logger: cliLogger,
+        forceRefresh,
+      });
+
+      process.stdout.write(
+        JSON.stringify(
+          {
+            fileKey: result.fileKey,
+            version: result.version,
+            cached: result.cached,
+            outDir: result.outDir,
+            endpoints: result.endpoints.map((e) => ({
+              name: e.name,
+              bytes: e.bytes,
+              ms: e.ms,
+              skipped: e.skipped || false,
+            })),
+          },
+          null,
+          2
+        ) + '\n'
+      );
+      process.exit(0);
+    } catch (e) {
+      // Surface the message (which never contains the token) on stderr.
+      process.stderr.write('FAILED: ' + e.message + '\n');
+      process.exit(1);
+    }
+  })();
+}

package/scripts/lib/figma-extract/receiver.cjs

@@ -0,0 +1,273 @@
+'use strict';
+// scripts/lib/figma-extract/receiver.cjs — Plan 31-06 (Wave B.3)
+// Path C receiver; D-06: ephemeral + 127.0.0.1-only.
+//
+// The localhost half of Path C (D-04). The Figma plugin "GDD Sync" (31-05)
+// reads `figma.variables` from inside Figma (works on any plan — sidesteps the
+// spike's Variables-API-403 Enterprise blocker) and POSTs them here. This
+// receiver validates the payload against payload-schema.json and writes it into
+// the raw/ cache as variables.json, where digest.cjs (31-02) consumes it as
+// Path C via the `source:'gdd-plugin'` marker.
+//
+// Security properties are the WHOLE point (D-06):
+//   - Binds 127.0.0.1 ONLY (host '127.0.0.1', never 0.0.0.0) — unreachable off
+//     the loopback interface.
+//   - REFUSES any non-loopback remote with 403 (req.socket.remoteAddress gate),
+//     even though the bind already makes that essentially unreachable — defense
+//     in depth, and asserted by test via a mocked remote address.
+//   - Validates EVERY payload against the schema BEFORE touching disk (400 on
+//     invalid; nothing written).
+//   - Port is HARDCODED to 5179 — NOT read from env or a CLI flag (acceptance
+//     criterion). Changing it requires a code edit. There is intentionally no
+//     `process.env.*PORT*` read in this module.
+//   - EPHEMERAL: listens only for the duration of one extract run and exits on
+//     the FIRST valid receipt OR on a timeout — never a lingering open port.
+//
+// D-10: this module handles design variables ONLY. It NEVER touches the Figma
+// token (that's a REST-path concern, not Path C). There is no secret-handling
+// code here, and the logger seam receives lifecycle events + counts only —
+// never full payloads.
+
+const http = require('node:http');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const Ajv = require('ajv');
+
+const payloadSchema = require('./payload-schema.json');
+
+// ── constants (D-06 acceptance criterion: hardcoded, no env override) ─────────
+const RECEIVER_HOST = '127.0.0.1'; // loopback ONLY
+const RECEIVER_PORT = 5179; // HARDCODED — intentionally not read from process.env
+
+// The marker digest.cjs (31-02) keys on to route variables.json to Path C.
+const PLUGIN_PAYLOAD_MARKER = 'gdd-plugin';
+
+// Defensive body cap. Large design systems can ship sizeable variable sets
+// (the risk register notes streaming for the raw pull); 50MB is generous for a
+// variables-only JSON payload while still bounding memory from a hostile body.
+const MAX_BODY_BYTES = 50 * 1024 * 1024;
+
+// ── validator (Ajv is a hard repo dependency — package.json "ajv": "^8.18.0") ─
+// Compiled once at module load. Ajv 8 CJS: require('ajv') is the constructor.
+// NOTE: fail-fast (default, NO allErrors). The receiver validates an UNTRUSTED
+// HTTP body from the plugin; `allErrors: true` would walk the entire (possibly
+// hostile, deeply-nested) object collecting every violation — a resource-
+// exhaustion / DoS amplifier (CodeQL js/resources-exhaustion). Fail-fast stops
+// at the first violation, which is all the 400 response needs. The 50MB
+// MAX_BODY_BYTES cap bounds input size; fail-fast bounds traversal cost.
+const AjvCtor = Ajv.default || Ajv;
+const _ajv = new AjvCtor({ strict: false });
+const _validate = _ajv.compile(payloadSchema);
+
+/**
+ * Validate a parsed body against payload-schema.json.
+ * @param {*} body
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+function validatePayload(body) {
+  const valid = _validate(body) === true;
+  return { valid, errors: valid ? [] : (_validate.errors || []) };
+}
+
+/** Normalize req.socket.remoteAddress to a loopback test (IPv4, IPv6, mapped). */
+function isLoopbackRemote(remoteAddress) {
+  return (
+    remoteAddress === '127.0.0.1' ||
+    remoteAddress === '::1' ||
+    remoteAddress === '::ffff:127.0.0.1'
+  );
+}
+
+/** Read the full request body with a hard size cap. Rejects on overflow. */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('payload too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+/** No-op logger fallback. The real seam receives lifecycle events + counts only. */
+function emit(logger, event) {
+  if (typeof logger === 'function') {
+    try {
+      logger(event);
+    } catch {
+      /* a broken logger must never crash the receiver */
+    }
+  }
+}
+
+/**
+ * Build the request handler. Exported (`createHandler`) so tests can exercise
+ * the loopback gate / routing synchronously by invoking it with a fake req/res
+ * — no real remote socket needed (D-06 refusal path is asserted this way).
+ *
+ * The `onReceipt(parsed, filePath)` callback is invoked exactly once, on the
+ * first VALID localhost POST, AFTER the file is written. startReceiver wires it
+ * to close the server + resolve. Non-localhost (403), bad route (404), parse
+ * error / schema-invalid (400) NEVER call onReceipt — the server keeps waiting.
+ *
+ * @param {object} opts
+ * @param {string} opts.outDir
+ * @param {Function} [opts.logger]
+ * @param {Function} opts.onReceipt  async (parsed, filePath) => void
+ * @returns {Function} (req, res) => void
+ */
+function createHandler({ outDir, logger, onReceipt }) {
+  return function handler(req, res) {
+    // (1) Loopback gate FIRST (D-06) — defense in depth on top of the bind.
+    const remoteAddress = req.socket && req.socket.remoteAddress;
+    if (!isLoopbackRemote(remoteAddress)) {
+      emit(logger, { event: 'reject-403', reason: 'non-localhost' });
+      res.writeHead(403, { 'content-type': 'text/plain' });
+      res.end('forbidden: non-localhost');
+      return;
+    }
+
+    // (2) Route — only POST /variables is handled.
+    if (req.method !== 'POST' || req.url !== '/variables') {
+      emit(logger, { event: 'reject-404', method: req.method, url: req.url });
+      res.writeHead(404, { 'content-type': 'text/plain' });
+      res.end('not found');
+      return;
+    }
+
+    // (3) Read + parse + validate + write. Any thrown error → 500 (no crash).
+    readBody(req)
+      .then(async (raw) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          emit(logger, { event: 'reject-400', reason: 'malformed-json' });
+          res.writeHead(400, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'malformed-json' }));
+          return;
+        }
+
+        const { valid, errors } = validatePayload(parsed);
+        if (!valid) {
+          emit(logger, { event: 'reject-400', reason: 'schema', errorCount: errors.length });
+          res.writeHead(400, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'schema', details: errors }));
+          return;
+        }
+
+        // Valid. Stamp the marker if (defensively) absent, then write the file.
+        if (parsed.source !== PLUGIN_PAYLOAD_MARKER) parsed.source = PLUGIN_PAYLOAD_MARKER;
+        const filePath = path.join(outDir, 'variables.json');
+        await fs.mkdir(outDir, { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(parsed));
+
+        emit(logger, {
+          event: 'receipt',
+          path: filePath,
+          collections: Array.isArray(parsed.collections) ? parsed.collections.length : 0,
+          variables: Array.isArray(parsed.variables) ? parsed.variables.length : 0,
+        });
+
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+
+        if (typeof onReceipt === 'function') await onReceipt(parsed, filePath);
+      })
+      .catch((err) => {
+        // Body-too-large or unexpected I/O error. Do NOT leak internals; do NOT
+        // resolve the receipt. 500 keeps the server waiting for a retry.
+        emit(logger, { event: 'error', message: err && err.message });
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'internal' }));
+        }
+      });
+  };
+}
+
+/**
+ * Start the ephemeral Path C receiver.
+ *
+ * @param {object} opts
+ * @param {string} opts.outDir              REQUIRED — writes <outDir>/variables.json on valid receipt
+ * @param {number} [opts.timeoutMs=120000]  exits if no valid payload arrives in time
+ * @param {Function} [opts.logger]          structured lifecycle sink (never receives secrets/full payloads)
+ * @returns {Promise<{received:true, path:string} | {received:false, reason:'timeout'}>}
+ *
+ * Resolves with `{received:true, path}` on the FIRST valid POST /variables, or
+ * `{received:false, reason:'timeout'}` on timeout. The server is closed on BOTH
+ * exit paths (ephemeral — D-06). Non-localhost → 403; schema-invalid → 400;
+ * neither resolves the promise (the server keeps waiting until receipt/timeout).
+ */
+function startReceiver({ outDir, timeoutMs = 120000, logger } = {}) {
+  if (!outDir) {
+    return Promise.reject(new TypeError('startReceiver: opts.outDir is required'));
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+    let server = null;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      // Close the server on BOTH exit paths so the port is never left open and
+      // the event loop can drain (process can exit). close() is idempotent-safe.
+      if (server) server.close(() => resolve(result));
+      else resolve(result);
+    };
+
+    const handler = createHandler({
+      outDir,
+      logger,
+      onReceipt: (_parsed, filePath) => finish({ received: true, path: filePath }),
+    });
+
+    server = http.createServer(handler);
+
+    server.on('error', (err) => {
+      // Most likely EADDRINUSE (another receiver already bound 5179) — surface
+      // it to the caller rather than hanging. Only meaningful before listen.
+      if (!settled) {
+        settled = true;
+        if (timer) clearTimeout(timer);
+        reject(err);
+      }
+    });
+
+    server.listen(RECEIVER_PORT, RECEIVER_HOST, () => {
+      emit(logger, { event: 'listen', host: RECEIVER_HOST, port: RECEIVER_PORT });
+      // Arm the timeout only once we are actually listening.
+      timer = setTimeout(() => {
+        emit(logger, { event: 'timeout', timeoutMs });
+        finish({ received: false, reason: 'timeout' });
+      }, timeoutMs);
+      // Don't let the timeout itself keep the process alive past its purpose.
+      if (typeof timer.unref === 'function') timer.unref();
+    });
+  });
+}
+
+module.exports = {
+  startReceiver,
+  createHandler,
+  validatePayload,
+  isLoopbackRemote,
+  RECEIVER_PORT,
+  RECEIVER_HOST,
+  PLUGIN_PAYLOAD_MARKER,
+};