@daniellins/power-claude 0.16.3

package/scripts/pod-export-ui.cjs

@@ -0,0 +1,805 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-export-ui.cjs — UI WEB DE CHECKPOINT do épico pod-export (F3, Story SF10.5).
+ *
+ * PROCESSO PRÓPRIO, SEPARADO do serviço-irmão (`pod-export-service.cjs`, que continua SEM porta —
+ * DF2-5 intacto). Servidor HTTP zero-dep (`node:http`, NÃO Next.js/Express — ADR-018 DF3-2: menor
+ * superfície de ataque + doutrina zero-dep do motor/serviço). Bind SÓ em `127.0.0.1` (NUNCA
+ * `0.0.0.0`); a exposição via nginx TLS é ação de operador (ver docs/mecanismos/pod-export-ui.md).
+ *
+ * A UI é o "mais um escritor na fila" que DF2-5 previu: REUSA por IMPORT de pod-export-service.cjs
+ * (`loadConfig`, `loadIdentities`, `listPending`/leitura de `awaiting/`, `approveRun`, `enqueue`,
+ * `verifyApproverSecret`) — NUNCA reimplementa fila/estado/enforcement. O gate real de "só Daniel
+ * aprova" vive no BACKEND (`approveRun` de SF10.4): a UI apenas coleta o segredo e o repassa; chamar
+ * o backend direto sem/segredo-errado é RECUSADO independentemente da UI.
+ *
+ * TRÊS CAMADAS DISTINTAS (DF3-3), nunca confundidas:
+ *   1. LOGIN (ACESSO)      — credencial ÚNICA de equipe (scrypt hash em env + cookie HMAC-assinado
+ *                            SameSite=Strict). Prova só que a pessoa está no time; NÃO diz quem é.
+ *   2. SELETOR (ATRIBUIÇÃO) — operador escolhido vira `started_by`. Seleção honesta, barreira FRACA
+ *                            por design; qualquer um seleciona qualquer nome (DF3-3). NÃO é auth.
+ *   3. SEGREDO (AUTORIZAÇÃO) — o 4º fator que só o aprovador detém, digitado NO MOMENTO de aprovar,
+ *                            verificado server-side por `approveRun` (scrypt+timingSafeEqual). O gate.
+ *
+ * SEGURANÇA (o /security-review ataca isto):
+ *   - Preview XSS: as 7 peças são HTML gerado por LLM (não confiável). Renderizadas em
+ *     `<iframe sandbox>` (sem allow-same-origin + allow-scripts) servidas por /preview com
+ *     `Content-Security-Policy: sandbox; script-src 'none'` — origem opaca, sem script, sem acesso
+ *     ao cookie/sessão da UI. NUNCA `srcdoc`+scripts nem same-origin.
+ *   - CSRF: cookie SameSite=Strict + verificação de Origin/Referer nas ações de estado + token CSRF
+ *     por sessão (HMAC do sid).
+ *   - Sessão: cookie HMAC-SHA256 assinado (não-forjável sem PODEXPORT_UI_SESSION_KEY), HttpOnly,
+ *     Secure (atrás de TLS), expiração. timingSafeEqual em toda verificação.
+ *   - Nenhum segredo/hash é logado ou ecoado; erros de aprovação são genéricos (sem oracle).
+ *   - Rate-limit em memória (ADR-004) em login e approve.
+ *
+ * CONFIG por ENV (instância na VPS, fora do commit):
+ *   PODEXPORT_QUEUE_DIR / PODEXPORT_RUNS_DIR / PODEXPORT_BUNDLE_DIR / PODEXPORT_IDENTITIES — de SF10.3/4.
+ *   PODEXPORT_APPROVER_SECRET_HASH — hash do segredo do aprovador (o CLARO nunca reside na UI).
+ *   PODEXPORT_UI_TEAM_HASH    (obrigatório) — hash scrypt da senha da equipe (gere com `hash-team`).
+ *   PODEXPORT_UI_SESSION_KEY  (obrigatório) — chave HMAC de assinatura do cookie de sessão (>=32 ch).
+ *   PODEXPORT_UI_PORT         (default 4600) — porta local (bind 127.0.0.1).
+ *   PODEXPORT_UI_SESSION_TTL_MS (default 8h) — validade da sessão.
+ *   PODEXPORT_UI_INSECURE=1   — desliga o flag Secure do cookie (SÓ para dev local sem TLS).
+ *
+ * Node >= 18, zero dep externa. Relógio/rede/approve/identidades INJETÁVEIS → suíte CI hermética.
+ */
+
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const svc = require('./pod-export-service.cjs');
+const motor = require('./pc-run-pod.cjs');
+
+const COOKIE_NAME = 'pex_ui';
+const DEFAULT_PORT = 4600;
+const DEFAULT_TTL_MS = 8 * 60 * 60 * 1000;
+const BODY_LIMIT = 64 * 1024;
+
+// ---------------------------------------------------------------------------
+// Config (reusa svc.loadConfig para os campos compartilhados; adiciona os da UI).
+// ---------------------------------------------------------------------------
+
+function loadUiConfig(env = process.env, overrides = {}) {
+  const base = svc.loadConfig(env, overrides);
+  return {
+    ...base,
+    host: '127.0.0.1', // FORÇADO — nunca 0.0.0.0 (DF3-2). A exposição TLS é do nginx do operador.
+    port: Number(overrides.port || env.PODEXPORT_UI_PORT || DEFAULT_PORT),
+    teamHash: overrides.teamHash || env.PODEXPORT_UI_TEAM_HASH || null,
+    sessionKey: overrides.sessionKey || env.PODEXPORT_UI_SESSION_KEY || null,
+    approverSecretHash: overrides.approverSecretHash || env.PODEXPORT_APPROVER_SECRET_HASH || null,
+    secure: (overrides.secure != null) ? overrides.secure : (env.PODEXPORT_UI_INSECURE === '1' ? false : true),
+    sessionTtlMs: Number(overrides.sessionTtlMs || env.PODEXPORT_UI_SESSION_TTL_MS || DEFAULT_TTL_MS),
+  };
+}
+
+/** Fail-loud: a UI RECUSA subir sem os segredos essenciais (nunca sobe verde-falso, ADR-015). */
+function assertUiConfig(cfg) {
+  if (!cfg.queueDir) throw new Error('[FAIL-LOUD] PODEXPORT_QUEUE_DIR ausente — a UI lê a fila (awaiting/). Defina no env.');
+  if (!cfg.teamHash || String(cfg.teamHash).trim() === '') {
+    throw new Error('[FAIL-LOUD] PODEXPORT_UI_TEAM_HASH ausente — o login compartilhado exige o hash da senha da equipe (gere com `node scripts/pod-export-ui.cjs hash-team`). Sem ele, sem acesso.');
+  }
+  if (!cfg.sessionKey || String(cfg.sessionKey).length < 32) {
+    throw new Error('[FAIL-LOUD] PODEXPORT_UI_SESSION_KEY ausente ou curta (>=32 ch) — a sessão assinada exige uma chave HMAC forte. Gere com `openssl rand -hex 32`.');
+  }
+  if (!cfg.approverSecretHash || String(cfg.approverSecretHash).trim() === '') {
+    throw new Error('[FAIL-LOUD] PODEXPORT_APPROVER_SECRET_HASH ausente — o gate de aprovação (SF10.4) exige o hash do segredo do aprovador. Sem ele, nada é aprovável.');
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Cripto de sessão/CSRF (zero-dep, node:crypto). HMAC-SHA256 + timingSafeEqual.
+// ---------------------------------------------------------------------------
+
+function b64url(buf) {
+  return Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function b64urlDecode(s) {
+  return Buffer.from(String(s).replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+function hmac(key, data) {
+  return crypto.createHmac('sha256', String(key)).update(data).digest();
+}
+function timingEq(a, b) {
+  const ba = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ba.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+/** Assina um payload de sessão como `<body>.<sig>` (HMAC). Corpo é JSON base64url. */
+function signSession(payload, key) {
+  const body = b64url(JSON.stringify(payload));
+  const sig = b64url(hmac(key, body));
+  return `${body}.${sig}`;
+}
+
+/** Verifica e decodifica um token de sessão. Retorna o payload ou null (assinatura/expiração inválida). */
+function verifySession(token, key, now = Date.now()) {
+  if (typeof token !== 'string' || token.indexOf('.') < 0) return null;
+  const idx = token.lastIndexOf('.');
+  const body = token.slice(0, idx);
+  const sig = token.slice(idx + 1);
+  const expected = b64url(hmac(key, body));
+  if (!timingEq(sig, expected)) return null; // não-forjável sem a chave.
+  let payload;
+  try { payload = JSON.parse(b64urlDecode(body).toString('utf8')); } catch { return null; }
+  if (!payload || typeof payload !== 'object') return null;
+  if (typeof payload.exp === 'number' && now > payload.exp) return null; // sessão expirada.
+  return payload;
+}
+
+/** Token CSRF derivado do sid da sessão (estável enquanto a sessão vive). */
+function csrfToken(sid, key) { return b64url(hmac(key, `csrf:${sid}`)); }
+function verifyCsrf(token, sid, key) { return typeof token === 'string' && timingEq(token, csrfToken(sid, key)); }
+
+// ---------------------------------------------------------------------------
+// Rate-limit em memória (ADR-004). Janela deslizante por chave (IP no login, sid no approve).
+// ---------------------------------------------------------------------------
+
+function createRateLimiter(max, windowMs) {
+  const hits = new Map();
+  return {
+    check(key, now = Date.now()) {
+      const arr = (hits.get(key) || []).filter((t) => now - t < windowMs);
+      if (arr.length >= max) { hits.set(key, arr); return { allowed: false, retryAfterMs: windowMs - (now - arr[0]) }; }
+      arr.push(now); hits.set(key, arr);
+      return { allowed: true };
+    },
+    reset(key) { hits.delete(key); },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTML escaping — toda interpolação de dado externo passa por aqui (anti-XSS na própria UI).
+// ---------------------------------------------------------------------------
+
+function escapeHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+// ---------------------------------------------------------------------------
+// Leitura da fila/runs (SEMPRE do disco — DF2-5, nunca um segundo motor de estado).
+// ---------------------------------------------------------------------------
+
+// SF10.9/AC5 — a regra do runId passou a viver no BACKEND (`pod-export-service.cjs`), que agora
+// também a impõe em `approveRun` (antes o valor chegava cru do form até o spawn). A UI REUSA o
+// mesmo predicado: uma única fonte, sem duas cópias que podem divergir. Export mantido (callers/tests).
+const safeRunId = svc.safeRunId;
+
+/** Lista os runs pausados em awaiting/ lendo os `<runId>.result.json` (fonte de verdade = disco). */
+function listCheckpoints(cfg) {
+  const dir = path.join(cfg.queueDir, 'awaiting');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!f.endsWith('.result.json')) continue;
+    const runId = f.slice(0, -('.result.json'.length));
+    if (!safeRunId(runId)) continue;
+    let res = {};
+    try { res = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { res = {}; }
+    let payload = {};
+    try { payload = JSON.parse(fs.readFileSync(path.join(dir, `${runId}.json`), 'utf8')); } catch { payload = {}; }
+    out.push({
+      runId,
+      startedBy: res.started_by || payload.started_by || null,
+      pod: payload.pod || null,
+      phase: res.awaiting || null,
+      at: res.at || null,
+    });
+  }
+  return out;
+}
+
+/** runDir real de um run (via motor.findStateByRunId — o mesmo do executor). null se não existe. */
+function runDirFor(cfg, runId, deps = {}) {
+  if (!safeRunId(runId)) return null;
+  const findState = deps.findStateByRunId || motor.findStateByRunId;
+  const sp = findState(cfg.runsRoot, runId);
+  return sp ? path.dirname(sp) : null;
+}
+
+/** Lista os arquivos HTML (as peças) sob o runDir, confinado, excluindo artifacts/. Rel paths. */
+function listPieceFiles(runDir) {
+  const out = [];
+  const walk = (dir, rel) => {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const abs = path.join(dir, e.name);
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (e.name === 'artifacts') continue; walk(abs, r); }
+      else if (/\.html?$/i.test(e.name)) out.push(r);
+    }
+  };
+  walk(runDir, '');
+  return out.sort();
+}
+
+/** Critério do checkpoint (best-effort): lê workflow.yaml do bundle e extrai `criteria` da fase. */
+function checkpointCriterion(cfg, phase) {
+  const fallback = 'Julgamento humano: avalie as peças geradas antes de aprovar.';
+  if (!cfg.bundleDir || !phase) return fallback;
+  const wf = path.join(cfg.bundleDir, 'workflow.yaml');
+  let text;
+  try { text = fs.readFileSync(wf, 'utf8'); } catch { return fallback; }
+  // Procura o bloco do step `phase` e um `criteria: "..."` até o próximo `- id:`.
+  const idIdx = text.indexOf(`id: ${phase}`);
+  if (idIdx < 0) return fallback;
+  const rest = text.slice(idIdx);
+  const nextStep = rest.indexOf('\n  - id:');
+  const block = nextStep > 0 ? rest.slice(0, nextStep) : rest;
+  const m = block.match(/criteria:\s*["']?([^"'\n]+)["']?/);
+  return m ? m[1].trim() : fallback;
+}
+
+/**
+ * Confina um relPath ao runDir; retorna abs ou null se traversal/fora.
+ *
+ * SF10.9/AC4 — `decodeURIComponent` é parse de entrada NÃO-CONFIÁVEL: `%zz` lança `URIError`. Sob
+ * try/catch (mesmo padrão do `new URL` do router), entrada malformada vira `null` → 400, nunca uma
+ * exceção não capturada no handler.
+ *
+ * SF10.9/AC3 — containment por REALPATH (mesmo padrão do Guard B de `command_check`,
+ * `pc-run-pod.cjs`): o guard lexical (`path.resolve`) não enxerga symlink CRIADO DENTRO do runDir
+ * apontando para fora. Quando o alvo (ou o ancestral existente mais próximo) resolve em disco, o
+ * realpath tem que permanecer sob o realpath do runDir — senão RECUSA. Aditivo: o retorno do
+ * caminho feliz continua sendo o `abs` lexical (o caller lê/serve exatamente o mesmo arquivo).
+ */
+function confineToRunDir(runDir, relPath) {
+  if (typeof relPath !== 'string' || relPath === '') return null;
+  let decoded;
+  try { decoded = decodeURIComponent(relPath); } catch { return null; } // %zz e cia → recusa, não URIError.
+  decoded = decoded.replace(/^\/+/, '');
+  if (decoded.includes('\0')) return null;
+  const root = path.resolve(runDir);
+  const abs = path.resolve(runDir, decoded);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+  // Guard realpath (defesa em profundidade). Se nem o runDir resolve em disco, não há o que servir:
+  // devolve o abs lexical (o caller ainda confere existsSync/isFile e responde 400).
+  let realRoot;
+  try { realRoot = fs.realpathSync(root); } catch { return abs; }
+  let probe = abs;
+  for (;;) {
+    let real;
+    try { real = fs.realpathSync(probe); } catch {
+      const parent = path.dirname(probe);
+      if (parent === probe || parent.length < root.length) return abs; // nada existe ainda sob o runDir.
+      probe = parent;
+      continue;
+    }
+    return (real === realRoot || real.startsWith(realRoot + path.sep)) ? abs : null;
+  }
+}
+
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.css': 'text/css; charset=utf-8',
+};
+
+// ---------------------------------------------------------------------------
+// Reject: ação de QUEUE-WRITER (DF2-5) — parkea o run em blocked/ com o motivo. NÃO reimplementa
+// approve nem toca o motor/executor. Dívida declarada (F4/F5): re-rodar a fase via `revise` do motor
+// não é wired em v1; reject = triagem de qualidade que remove o run de awaiting/ com motivo registrado.
+// ---------------------------------------------------------------------------
+
+function rejectRun(cfg, runId, { reason, rejectedBy } = {}) {
+  if (!safeRunId(runId)) return { ok: false, reason: 'runId inválido' };
+  const dirs = svc.ensureQueue(cfg.queueDir);
+  const src = path.join(dirs.awaiting, `${runId}.json`);
+  // SF10.16/AC1 (DF-SF10.16-2.1) — REIVINDICAR ANTES DE AGIR: o marcador vai para blocked/ ANTES de qualquer
+  // escrita de motivo. O `existsSync`+`renameSync` anterior era TOCTOU cross-processo: com dois
+  // cliques em `reject` (ou reject × approve), o perdedor lançava `ENOENT` DENTRO do handler async do
+  // node:http → unhandled rejection → **o processo da UI inteiro MORRIA** (não há
+  // process.on('uncaughtException') aqui). Agora o rename que sucede é a autorização; perder a
+  // disputa devolve `gone`, que o router já traduz em `flash=gone` ("já tratado por outra pessoa").
+  if (!svc.claimByRename(src, path.join(dirs.blocked, `${runId}.json`))) {
+    return { ok: false, gone: true, reason: 'run não está em awaiting/ (já tratado?)' };
+  }
+  // Daqui em diante somos o dono EXCLUSIVO do item (ninguém mais pode reivindicá-lo).
+  const srcRes = path.join(dirs.awaiting, `${runId}.result.json`);
+  try { fs.unlinkSync(srcRes); }
+  catch (e) {
+    if (!e || e.code !== 'ENOENT') {
+      // Não é catch-all: ENOENT é o caso normal (nem todo marcador tem companion). Outro errno é
+      // ANOMALIA e vai LOGADO ALTO — mas não relançado: a transição de estado que importa (o rename)
+      // já ocorreu, e derrubar a UI aqui recriaria o defeito que esta story fecha (DF-SF10.16-3: nada pode
+      // tornar a superfície de aprovação indisponível).
+      console.error(`[reject][AVISO ALTO] ${runId}: falha ao remover ${srcRes} (${e.code || e.message}) — o run JÁ está em blocked/; investigue permissões da fila.`);
+    }
+  }
+  fs.writeFileSync(path.join(dirs.blocked, `${runId}.result.json`), JSON.stringify({
+    runId, kind: 'blocked', ok: false, rejected: true,
+    rejected_by: rejectedBy || null, reason: String(reason || '').slice(0, 2000),
+    at: new Date().toISOString(),
+  }, null, 2));
+  return { ok: true, kind: 'blocked' };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers.
+// ---------------------------------------------------------------------------
+
+function parseCookies(header) {
+  const out = {};
+  if (typeof header !== 'string') return out;
+  for (const part of header.split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+function readBody(req, limit = BODY_LIMIT) {
+  return new Promise((resolve, reject) => {
+    let data = ''; let size = 0;
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > limit) { reject(new Error('payload muito grande')); req.destroy(); return; }
+      data += c;
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
+function parseForm(body) {
+  const out = {};
+  const p = new URLSearchParams(body);
+  for (const [k, v] of p) out[k] = v;
+  return out;
+}
+
+function clientIp(req) {
+  const xff = req.headers['x-forwarded-for'];
+  if (typeof xff === 'string' && xff.trim()) return xff.split(',')[0].trim();
+  return (req.socket && req.socket.remoteAddress) || 'unknown';
+}
+
+/** Origin/Referer host deve casar com o Host (defesa em profundidade além do SameSite=Strict). */
+function sameOrigin(req) {
+  const host = req.headers['x-forwarded-host'] || req.headers.host;
+  const origin = req.headers.origin;
+  if (origin) { try { return new URL(origin).host === host; } catch { return false; } }
+  const ref = req.headers.referer;
+  if (ref) { try { return new URL(ref).host === host; } catch { return false; } }
+  return false; // sem Origin/Referer numa ação de estado → recusa.
+}
+
+function baseHeaders(extra = {}) {
+  return {
+    'Content-Type': 'text/html; charset=utf-8',
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'no-referrer',
+    // A própria UI: sem script inline algum (default-src 'none'), estilos inline permitidos, imagens
+    // próprias/data, frames só de 'self' (as peças via /preview, que por sua vez são sandbox-CSP).
+    'Content-Security-Policy':
+      "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; frame-src 'self'; " +
+      "form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+    ...extra,
+  };
+}
+
+function setSessionCookie(res, token, cfg) {
+  const parts = [`${COOKIE_NAME}=${token}`, 'HttpOnly', 'SameSite=Strict', 'Path=/', `Max-Age=${Math.floor(cfg.sessionTtlMs / 1000)}`];
+  if (cfg.secure) parts.push('Secure');
+  res.setHeader('Set-Cookie', parts.join('; '));
+}
+function clearSessionCookie(res, cfg) {
+  const parts = [`${COOKIE_NAME}=`, 'HttpOnly', 'SameSite=Strict', 'Path=/', 'Max-Age=0'];
+  if (cfg.secure) parts.push('Secure');
+  res.setHeader('Set-Cookie', parts.join('; '));
+}
+
+function send(res, code, headers, body) {
+  res.writeHead(code, headers);
+  res.end(body);
+}
+function redirect(res, location, cfg, extraHeaders = {}) {
+  send(res, 303, { Location: location, 'Content-Type': 'text/plain; charset=utf-8', ...extraHeaders }, 'redirecionando...');
+}
+
+// ---------------------------------------------------------------------------
+// Views (strings HTML). Toda interpolação externa passa por escapeHtml.
+// ---------------------------------------------------------------------------
+
+const STYLE = `
+  :root{--fg:#1a1a1a;--muted:#666;--bg:#fafafa;--card:#fff;--line:#ddd;--danger:#b00020;--ok:#1b7a3d;--accent:#2a5db0}
+  *{box-sizing:border-box} body{font:15px/1.5 system-ui,sans-serif;color:var(--fg);background:var(--bg);margin:0;padding:24px}
+  .wrap{max-width:920px;margin:0 auto} h1{font-size:20px;margin:0 0 4px} .muted{color:var(--muted);font-size:13px}
+  .card{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:20px;margin:16px 0}
+  label{display:block;font-weight:600;margin:12px 0 4px} input[type=password],input[type=text],textarea{width:100%;padding:10px;border:1px solid var(--line);border-radius:6px;font:inherit}
+  button{cursor:pointer;font:inherit;padding:10px 18px;border-radius:6px;border:1px solid var(--line);background:#fff}
+  button:focus,a:focus,input:focus,[tabindex]:focus{outline:2px solid var(--accent);outline-offset:2px}
+  .primary{background:var(--accent);color:#fff;border-color:var(--accent)} .danger{color:var(--danger);border-color:var(--danger)}
+  .err{color:var(--danger);font-weight:600;margin:8px 0} .ok{color:var(--ok);font-weight:600;margin:8px 0}
+  table{width:100%;border-collapse:collapse} th,td{text-align:left;padding:8px;border-bottom:1px solid var(--line)}
+  .bar{display:flex;justify-content:space-between;align-items:center;gap:12px}
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:12px}
+  .piece{border:1px solid var(--line);border-radius:6px;overflow:hidden;background:#fff}
+  .piece iframe{width:100%;height:260px;border:0;display:block;background:#fff}
+  .piece .cap{padding:6px 8px;font-size:12px;color:var(--muted);border-top:1px solid var(--line)}
+  .crit{background:#fff8e6;border:1px solid #f0e0b0;border-radius:6px;padding:14px;font-size:14px}
+  .modal{background:#fff;border:2px solid var(--accent);border-radius:8px;padding:20px;margin:16px 0}
+  fieldset{border:1px solid var(--line);border-radius:6px;padding:8px 14px}
+`;
+
+function layout(title, inner, opts = {}) {
+  return `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>${escapeHtml(title)}</title><style>${STYLE}</style></head>` +
+    `<body><div class="wrap">${inner}</div></body></html>`;
+}
+
+function loginView(err) {
+  return layout('pod-export · checkpoint', `
+    <div class="card">
+      <h1>pod-export · checkpoint</h1>
+      ${err ? `<p class="err">${escapeHtml(err)}</p>` : ''}
+      <form method="POST" action="/login">
+        <label for="pw">Senha da equipe</label>
+        <input id="pw" name="password" type="password" autocomplete="off" autofocus>
+        <p style="margin-top:16px"><button class="primary" type="submit">Entrar</button></p>
+      </form>
+      <p class="muted">Esta senha dá acesso à ferramenta — ela NÃO identifica quem está usando.
+      Na próxima tela você escolhe seu nome.</p>
+    </div>`);
+}
+
+function operatorView(cfg, session, err) {
+  let model;
+  try { model = svc.loadIdentities({ env: process.env, file: cfg.identitiesFile }); }
+  catch { return layout('Seletor', `<div class="card"><h1>Quem está usando?</h1>
+    <p class="err">Nenhuma identidade configurada — contate o operador.</p></div>`); }
+  const csrf = csrfToken(session.sid, cfg.sessionKey);
+  const opts = model.identities.map((it, i) => `
+    <label style="font-weight:400;display:flex;gap:8px;align-items:center;margin:6px 0">
+      <input type="radio" name="operator" value="${escapeHtml(it.id)}" ${i === 0 ? 'required' : ''}>
+      ${escapeHtml(it.label || it.id)}</label>`).join('');
+  return layout('Seletor de operador', `
+    <div class="card">
+      <h1>Quem está usando a ferramenta agora?</h1>
+      ${err ? `<p class="err">${escapeHtml(err)}</p>` : ''}
+      <form method="POST" action="/operator">
+        <input type="hidden" name="_csrf" value="${escapeHtml(csrf)}">
+        <fieldset><legend class="muted">Operador</legend>${opts}</fieldset>
+        <p style="margin-top:16px"><button class="primary" type="submit">Continuar</button></p>
+      </form>
+      <p class="muted">Isto registra quem iniciou/decidiu cada ação para a equipe (rastreabilidade
+      interna) — não é uma senha e não prova identidade. Escolha seu nome com honestidade.</p>
+    </div>`);
+}
+
+function listView(cfg, session, flash) {
+  const items = listCheckpoints(cfg);
+  const op = escapeHtml(session.operator);
+  const rows = items.length ? items.map((c) => `
+    <tr>
+      <td>${escapeHtml(c.pod || '—')}</td>
+      <td>${escapeHtml(c.startedBy || '—')}</td>
+      <td>${escapeHtml(c.phase || '—')}</td>
+      <td class="muted">${escapeHtml(c.at || '')}</td>
+      <td><a href="/checkpoint?run=${encodeURIComponent(c.runId)}">Revisar →</a></td>
+    </tr>`).join('') : '';
+  return layout('Checkpoints pendentes', `
+    <div class="bar"><h1>Checkpoints pendentes</h1>
+      <span class="muted">Operando como: <strong>${op}</strong> ·
+        <form method="POST" action="/operator/change" style="display:inline">
+          <input type="hidden" name="_csrf" value="${escapeHtml(csrfToken(session.sid, cfg.sessionKey))}">
+          <button type="submit" style="padding:2px 8px">Trocar</button></form></span>
+    </div>
+    ${flash === 'approved' ? '<p class="ok">✓ Aprovado. O run continua automaticamente.</p>' : ''}
+    ${flash === 'rejected' ? '<p class="ok">✕ Rejeitado. O run foi devolvido com o motivo.</p>' : ''}
+    ${flash === 'gone' ? '<p class="err">Este checkpoint já foi tratado por outra pessoa.</p>' : ''}
+    <div class="card">
+      ${items.length ? `<table><thead><tr><th>Pod</th><th>Iniciado por</th><th>Fase</th><th>Quando</th><th></th></tr></thead>
+        <tbody>${rows}</tbody></table>`
+      : '<p class="muted">Tudo revisado. Volte quando um run novo pausar em checkpoint.</p>'}
+    </div>`);
+}
+
+function checkpointView(cfg, session, runId, err) {
+  const runDir = runDirFor(cfg, runId);
+  const inList = listCheckpoints(cfg).find((c) => c.runId === runId);
+  if (!inList) return { gone: true };
+  const pieces = runDir ? listPieceFiles(runDir) : [];
+  const criterion = checkpointCriterion(cfg, inList.phase);
+  let model;
+  try { model = svc.loadIdentities({ env: process.env, file: cfg.identitiesFile }); } catch { model = null; }
+  const isApprover = model && model.approver && model.approver.id === session.operator;
+  const csrf = csrfToken(session.sid, cfg.sessionKey);
+  const rid = escapeHtml(runId);
+
+  const previews = pieces.length ? pieces.map((rel, i) => `
+    <div class="piece">
+      <iframe sandbox referrerpolicy="no-referrer" loading="lazy"
+        src="/preview/${encodeURIComponent(runId)}/${rel.split('/').map(encodeURIComponent).join('/')}"
+        title="Peça ${i + 1}"></iframe>
+      <div class="cap">${i + 1}. ${escapeHtml(rel)}</div>
+    </div>`).join('')
+    : '<p class="muted">Não foi possível pré-visualizar as peças (nenhum HTML encontrado no run).</p>';
+
+  const approveBlock = isApprover ? `
+    <div class="modal">
+      <h2 style="margin-top:0">Confirmar aprovação</h2>
+      <p>Selecionar "${escapeHtml(session.operator)}" não autoriza sozinho — digite o segredo do
+      aprovador para confirmar.</p>
+      <form method="POST" action="/approve">
+        <input type="hidden" name="_csrf" value="${escapeHtml(csrf)}">
+        <input type="hidden" name="run" value="${rid}">
+        <label for="sec">Segredo do aprovador</label>
+        <input id="sec" name="secret" type="password" autocomplete="off">
+        <p style="margin-top:16px"><button class="primary" type="submit">✓ Aprovar</button></p>
+      </form>
+    </div>`
+    : `<p class="muted">Aprovação restrita à identidade aprovadora designada. Peça para o aprovador
+       revisar, ou troque de operador se for ele.</p>`;
+
+  const inner = `
+    <div class="bar"><h1>Checkpoint · ${escapeHtml(inList.pod || '')} · ${rid}</h1>
+      <span class="muted">Operando: <strong>${escapeHtml(session.operator)}</strong></span></div>
+    ${err ? `<p class="err">${escapeHtml(err)}</p>` : ''}
+    <div class="crit"><strong>Critério deste checkpoint:</strong><br>${escapeHtml(criterion)}</div>
+    <div class="card"><div class="grid">${previews}</div></div>
+    <div class="card">
+      <div class="bar">
+        <form method="POST" action="/reject">
+          <input type="hidden" name="_csrf" value="${escapeHtml(csrf)}">
+          <input type="hidden" name="run" value="${rid}">
+          <label for="mot">Motivo da rejeição</label>
+          <textarea id="mot" name="reason" rows="2" required></textarea>
+          <p style="margin-top:10px"><button class="danger" type="submit">✕ Rejeitar</button></p>
+        </form>
+      </div>
+      ${approveBlock}
+    </div>
+    <p><a href="/">← voltar à lista</a></p>`;
+  return { html: layout(`Checkpoint ${runId}`, inner) };
+}
+
+// ---------------------------------------------------------------------------
+// Router.
+// ---------------------------------------------------------------------------
+
+function getSession(req, cfg, now) {
+  const cookies = parseCookies(req.headers.cookie);
+  return verifySession(cookies[COOKIE_NAME], cfg.sessionKey, now);
+}
+
+function makeHandler(cfg, deps = {}) {
+  const now = deps.now || (() => Date.now());
+  const approveFn = deps.approveRun || svc.approveRun;
+  const loginLimiter = deps.loginLimiter || createRateLimiter(5, 60 * 1000);
+  const approveLimiter = deps.approveLimiter || createRateLimiter(5, 60 * 1000);
+
+  return async function handle(req, res) {
+    let url;
+    try { url = new URL(req.url, 'http://localhost'); } catch { return send(res, 400, baseHeaders(), 'bad request'); }
+    const pathname = url.pathname;
+    const method = req.method;
+
+    // Health (sem auth, mínimo).
+    if (method === 'GET' && pathname === '/health') {
+      return send(res, 200, { 'Content-Type': 'text/plain; charset=utf-8', 'X-Content-Type-Options': 'nosniff' }, 'ok');
+    }
+
+    // Preview das peças (sandbox-CSP; a peça é HTML não confiável — origem opaca, sem script).
+    if (method === 'GET' && pathname.startsWith('/preview/')) {
+      const session = getSession(req, cfg, now());
+      if (!session) return send(res, 403, { 'Content-Type': 'text/plain; charset=utf-8', 'X-Content-Type-Options': 'nosniff' }, 'sessão necessária');
+      const after = pathname.slice('/preview/'.length);
+      const slash = after.indexOf('/');
+      if (slash < 0) return send(res, 400, baseHeaders(), 'bad preview path');
+      // SF10.9/AC4 — parse de entrada não-confiável: `%zz` no segmento do runId lança `URIError`.
+      // Malformado → 400 (mesmo padrão do try/catch do `new URL` acima), nunca exceção não capturada.
+      let runId;
+      try { runId = decodeURIComponent(after.slice(0, slash)); }
+      catch { return send(res, 400, baseHeaders(), 'bad preview path'); }
+      const rel = after.slice(slash + 1);
+      const runDir = runDirFor(cfg, runId);
+      if (!runDir) return send(res, 404, { 'Content-Type': 'text/plain; charset=utf-8', 'X-Content-Type-Options': 'nosniff' }, 'run não encontrado');
+      const abs = confineToRunDir(runDir, rel);
+      if (!abs || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+        return send(res, 400, { 'Content-Type': 'text/plain; charset=utf-8', 'X-Content-Type-Options': 'nosniff' }, 'peça inválida');
+      }
+      const ext = path.extname(abs).toLowerCase();
+      const ctype = CONTENT_TYPES[ext] || 'application/octet-stream';
+      // sandbox-CSP: origem OPACA, script-src 'none' — o HTML da peça não roda JS nem lê o cookie da
+      // UI (não tem allow-same-origin nem allow-scripts). NUNCA Set-Cookie aqui.
+      const headers = {
+        'Content-Type': ctype,
+        'X-Content-Type-Options': 'nosniff',
+        'Referrer-Policy': 'no-referrer',
+        'Cross-Origin-Resource-Policy': 'same-origin',
+        'Content-Security-Policy':
+          "sandbox; default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; font-src data:",
+      };
+      return send(res, 200, headers, fs.readFileSync(abs));
+    }
+
+    const session = getSession(req, cfg, now());
+
+    // ---- Login ----
+    if (method === 'GET' && pathname === '/login') {
+      return send(res, 200, baseHeaders(), loginView(url.searchParams.get('e')));
+    }
+    if (method === 'POST' && pathname === '/login') {
+      const rl = loginLimiter.check(clientIp(req), now());
+      if (!rl.allowed) return send(res, 429, baseHeaders(), loginView('Muitas tentativas. Aguarde 1 minuto.'));
+      let form;
+      try { form = parseForm(await readBody(req)); } catch { return send(res, 413, baseHeaders(), loginView('Requisição inválida.')); }
+      if (!svc.verifyApproverSecret(form.password || '', cfg.teamHash)) {
+        return send(res, 401, baseHeaders(), loginView('Senha incorreta.'));
+      }
+      const sid = crypto.randomBytes(16).toString('hex');
+      const token = signSession({ sid, operator: null, exp: now() + cfg.sessionTtlMs }, cfg.sessionKey);
+      setSessionCookie(res, token, cfg);
+      return redirect(res, '/', cfg);
+    }
+
+    // Tudo abaixo exige sessão.
+    if (!session) return redirect(res, '/login', cfg);
+
+    // ---- Logout ----
+    if (method === 'POST' && pathname === '/logout') {
+      clearSessionCookie(res, cfg);
+      return redirect(res, '/login', cfg);
+    }
+
+    // ---- Seletor de operador ----
+    if (method === 'POST' && pathname === '/operator') {
+      const form = parseForm(await readBody(req));
+      if (!sameOrigin(req) || !verifyCsrf(form._csrf, session.sid, cfg.sessionKey)) {
+        return send(res, 403, baseHeaders(), operatorView(cfg, session, 'Sessão inválida (CSRF). Tente novamente.'));
+      }
+      let model;
+      try { model = svc.loadIdentities({ env: process.env, file: cfg.identitiesFile }); } catch { model = null; }
+      if (!model || !svc.isKnownIdentity(model, form.operator)) {
+        return send(res, 400, baseHeaders(), operatorView(cfg, session, 'Selecione um operador válido.'));
+      }
+      const token = signSession({ sid: session.sid, operator: form.operator, exp: now() + cfg.sessionTtlMs }, cfg.sessionKey);
+      setSessionCookie(res, token, cfg);
+      return redirect(res, '/', cfg);
+    }
+    if (method === 'POST' && pathname === '/operator/change') {
+      const form = parseForm(await readBody(req));
+      if (!sameOrigin(req) || !verifyCsrf(form._csrf, session.sid, cfg.sessionKey)) return send(res, 403, baseHeaders(), 'CSRF');
+      const token = signSession({ sid: session.sid, operator: null, exp: now() + cfg.sessionTtlMs }, cfg.sessionKey);
+      setSessionCookie(res, token, cfg);
+      return redirect(res, '/', cfg);
+    }
+
+    // ---- Approve ----
+    if (method === 'POST' && pathname === '/approve') {
+      const form = parseForm(await readBody(req));
+      if (!sameOrigin(req) || !verifyCsrf(form._csrf, session.sid, cfg.sessionKey)) {
+        return send(res, 403, baseHeaders(), 'CSRF: origem/token inválido.');
+      }
+      if (!session.operator) return redirect(res, '/', cfg);
+      const rl = approveLimiter.check(session.sid, now());
+      if (!rl.allowed) {
+        const v = checkpointView(cfg, session, form.run, 'Muitas tentativas. Aguarde e tente novamente.');
+        return send(res, 429, baseHeaders(), v.gone ? listView(cfg, session, 'gone') : v.html);
+      }
+      // O GATE REAL é o backend (SF10.4 approveRun): exige is_approver E o segredo verificado
+      // server-side. A UI apenas repassa asId (operador da sessão) e o segredo do form. Uma
+      // requisição forjada com operador errado / sem segredo passa por aqui e é RECUSADA pelo backend.
+      const r = await approveFn(cfg, form.run, {
+        env: process.env,
+        asId: session.operator,
+        approverSecret: form.secret,
+        approverSecretHash: cfg.approverSecretHash,
+        identitiesFile: cfg.identitiesFile,
+      });
+      if (r && r.code === 0 && !r.denied) return redirect(res, '/?flash=approved', cfg);
+      // SF10.16 — disputa PERDIDA (o checkpoint foi reivindicado por outra aprovação/rejeição entre o
+      // clique e o backend): estado que a UI já sabe renderizar. Não é erro de segredo, e dizer
+      // "confira o segredo" seria mentir ao operador. Sem oracle: a recusa por autorização continua
+      // genérica abaixo, e `gone` só é sinalizado DEPOIS de o gate de DF3-3 ter AUTORIZADO.
+      if (r && r.gone) return redirect(res, '/?flash=gone', cfg);
+      // Erro GENÉRICO (sem oracle: não distingue segredo-errado de não-aprovador).
+      const v = checkpointView(cfg, session, form.run, 'Não foi possível aprovar. Confira o segredo e tente novamente.');
+      return send(res, 403, baseHeaders(), v.gone ? listView(cfg, session, 'gone') : v.html);
+    }
+
+    // ---- Reject ----
+    if (method === 'POST' && pathname === '/reject') {
+      const form = parseForm(await readBody(req));
+      if (!sameOrigin(req) || !verifyCsrf(form._csrf, session.sid, cfg.sessionKey)) {
+        return send(res, 403, baseHeaders(), 'CSRF: origem/token inválido.');
+      }
+      if (!session.operator) return redirect(res, '/', cfg);
+      if (!form.reason || String(form.reason).trim() === '') {
+        const v = checkpointView(cfg, session, form.run, 'Informe um motivo para rejeitar.');
+        return send(res, 400, baseHeaders(), v.gone ? listView(cfg, session, 'gone') : v.html);
+      }
+      const r = rejectRun(cfg, form.run, { reason: form.reason, rejectedBy: session.operator });
+      return redirect(res, r.ok ? '/?flash=rejected' : '/?flash=gone', cfg);
+    }
+
+    // ---- GET / (lista ou seletor) ----
+    if (method === 'GET' && pathname === '/') {
+      if (!session.operator) return send(res, 200, baseHeaders(), operatorView(cfg, session));
+      const flash = url.searchParams.get('flash');
+      return send(res, 200, baseHeaders(), listView(cfg, session, flash));
+    }
+
+    // ---- GET /checkpoint ----
+    if (method === 'GET' && pathname === '/checkpoint') {
+      if (!session.operator) return redirect(res, '/', cfg);
+      const runId = url.searchParams.get('run');
+      const v = checkpointView(cfg, session, runId);
+      if (v.gone) return redirect(res, '/?flash=gone', cfg);
+      return send(res, 200, baseHeaders(), v.html);
+    }
+
+    return send(res, 404, baseHeaders(), layout('404', '<div class="card"><h1>Não encontrado</h1></div>'));
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Server.
+// ---------------------------------------------------------------------------
+
+function createServer(cfg, deps = {}) {
+  return http.createServer(makeHandler(cfg, deps));
+}
+
+function start(cfg, deps = {}) {
+  assertUiConfig(cfg);
+  const server = createServer(cfg, deps);
+  return new Promise((resolve) => {
+    server.listen(cfg.port, cfg.host, () => {
+      console.log(`[pod-export-ui] escutando em http://${cfg.host}:${cfg.port} (bind localhost — exponha via nginx TLS). queue=${cfg.queueDir}`);
+      resolve(server);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI: start | hash-team.
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const cmd = process.argv[2];
+  if (cmd === 'start') {
+    const cfg = loadUiConfig();
+    try { assertUiConfig(cfg); } catch (e) { console.error(e.message); process.exit(1); }
+    await start(cfg);
+  } else if (cmd === 'hash-team') {
+    // Gera o hash a colocar em PODEXPORT_UI_TEAM_HASH a partir de PODEXPORT_UI_TEAM_SECRET (o claro
+    // nunca é logado; reusa o scrypt do serviço).
+    const s = process.env.PODEXPORT_UI_TEAM_SECRET;
+    if (!s || String(s).trim() === '') { console.error('defina PODEXPORT_UI_TEAM_SECRET no env para gerar o hash (o claro nunca é logado).'); process.exit(2); }
+    console.log(svc.hashApproverSecret(s));
+  } else {
+    console.error('Uso: node scripts/pod-export-ui.cjs <start|hash-team>');
+    console.error('start exige PODEXPORT_QUEUE_DIR, PODEXPORT_UI_TEAM_HASH, PODEXPORT_UI_SESSION_KEY, PODEXPORT_APPROVER_SECRET_HASH no env (ver docs/mecanismos/pod-export-ui.md).');
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('[ERRO]', e.message); process.exit(1); });
+}
+
+module.exports = {
+  loadUiConfig, assertUiConfig,
+  b64url, b64urlDecode, hmac, timingEq,
+  signSession, verifySession, csrfToken, verifyCsrf,
+  createRateLimiter, escapeHtml, parseCookies, parseForm, sameOrigin, clientIp,
+  safeRunId, listCheckpoints, runDirFor, listPieceFiles, checkpointCriterion, confineToRunDir,
+  rejectRun, loginView, operatorView, listView, checkpointView, baseHeaders,
+  makeHandler, createServer, start, COOKIE_NAME,
+};