wize-dev-kit 0.4.1 → 0.6.0

package/src/security-overlay/_shared/partial.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// partial.js — the contract between phase skills and the report render.
+//
+// All phase skills write their findings to <securityDir>/<phase>.md using
+// this helper. The format is a YAML frontmatter (zero-dep serialization)
+// followed by `## <heading>` sections in a stable order. The report
+// (wize-sec-report) consumes these parciais and produces the final MD/HTML.
+//
+// Reruns are idempotent: writePartial overwrites the file in place; sections
+// are rendered in the order provided by the caller.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PARTIALS_SUBDIR = '.wize/security';
+
+// --- serialization helpers (zero-dep) ------------------------------------
+
+// YAML-quote a string value (only when needed). Strings that look like
+// numbers or booleans are still rendered as plain scalars — but the parse
+// side uses a STRICT type-coercion only when the string came in as a
+// non-string. That keeps version="2.9" round-tripping as a string.
+function yamlScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'string') {
+    // Quote when the string contains characters that YAML would mis-parse
+    // OR when the string is empty / has leading/trailing whitespace.
+    if (/[:#&*?|<>=!%@`\n]/.test(value) || value === '' || /^\s|\s$/.test(value)) {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+  throw new Error(`yamlScalar: unsupported type ${typeof value}`);
+}
+
+// Build a nested YAML mapping under a fixed indent. Used for `tools:` and
+// any other { name: { ... } } structure. Depth is unbounded; objects are
+// rendered as nested mappings, scalars as flat `key: value` lines.
+function renderNestedMap(obj, indent) {
+  const pad = ' '.repeat(indent);
+  const inner = ' '.repeat(indent + 2);
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(`${pad}${k}:`);
+      for (const [k2, v2] of Object.entries(v)) {
+        if (v2 && typeof v2 === 'object' && !Array.isArray(v2)) {
+          out.push(`${inner}${k2}:`);
+          const inner2 = ' '.repeat(indent + 4);
+          for (const [k3, v3] of Object.entries(v2)) {
+            out.push(`${inner2}${k3}: ${yamlScalar(v3)}`);
+          }
+        } else {
+          out.push(`${inner}${k2}: ${yamlScalar(v2)}`);
+        }
+      }
+    } else {
+      out.push(`${pad}${k}: ${yamlScalar(v)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+// Parse a flat YAML frontmatter into an object. We only accept the limited
+// shape the helper writes: flat `key: value` lines plus a `tools:` block
+// that may nest 2 levels deep (tool -> { key: value }). This is
+// intentionally not a general YAML parser.
+function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  const out = {};
+  let inTools = false;
+  let tools = null;
+  let toolKey = null;
+  for (const raw of lines) {
+    if (inTools) {
+      if (raw.trim() === '') continue;
+      // 2-space-indented top-level key under `tools:`.
+      const toolKeyMatch = raw.match(/^  ([a-zA-Z_][a-zA-Z0-9_-]*):\s*$/);
+      if (toolKeyMatch) {
+        toolKey = toolKeyMatch[1];
+        tools[toolKey] = {};
+        continue;
+      }
+      // 4-space-indented mapping under the current tool.
+      const valMatch = raw.match(/^    ([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+      if (valMatch && toolKey) {
+        tools[toolKey][valMatch[1]] = coerceScalar(valMatch[2]);
+        continue;
+      }
+      // Anything else ends the tools block.
+      if (/^\S/.test(raw)) {
+        inTools = false;
+        toolKey = null;
+        // fall through to the top-level branch on the same line
+      } else {
+        continue;
+      }
+    }
+    if (/^[a-zA-Z_][a-zA-Z0-9_-]*:(\s|$)/.test(raw)) {
+      const m = raw.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+      if (!m) continue;
+      const [, k, vRaw] = m;
+      const v = vRaw.replace(/^['"]|['"]$/g, '');
+      if (k === 'tools') {
+        inTools = true;
+        tools = {};
+        out.tools = tools;
+        toolKey = null;
+        continue;
+      }
+      out[k] = coerceScalar(v);
+    }
+  }
+  return out;
+}
+
+function coerceScalar(v) {
+  // Strings are kept as strings (so version="2.9" round-trips as a string,
+  // not a number). Booleans and null are explicit.
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (v === 'null') return null;
+  // Inline JSON array: [a, b, c]
+  if (/^\[.*\]$/.test(v)) {
+    try { return JSON.parse(v); } catch (_) { /* fall through */ }
+  }
+  return v;
+}
+
+// --- public API ----------------------------------------------------------
+
+function defaultSecurityDir() {
+  return path.join(process.cwd(), PARTIALS_SUBDIR);
+}
+
+// Refuse phase names that try to escape the securityDir.
+function assertSafePhase(phase) {
+  if (typeof phase !== 'string' || !phase) {
+    throw new Error('invalid phase: empty');
+  }
+  if (phase.includes('..') || phase.includes('/') || phase.includes('\\') || path.isAbsolute(phase)) {
+    throw new Error(`partial phase-name-traversal: refused ${JSON.stringify(phase)}`);
+  }
+}
+
+// writePartial({ securityDir?, phase, mode, scope, status, tools?, sections })
+//   - sections: object of { heading: content } (preserves order via Object.keys).
+//   - Returns the absolute path of the written file.
+function writePartial(opts) {
+  if (!opts || typeof opts !== 'object') throw new Error('writePartial: opts required');
+  const phase = opts.phase;
+  assertSafePhase(phase);
+  const sec = opts.securityDir || defaultSecurityDir();
+  fs.mkdirSync(sec, { recursive: true });
+
+  const scope = opts.scope || {};
+  const scopeSha = (scope.frontmatter && scope.frontmatter.scope_sha256) || (opts.scopeSha256 || '');
+
+  const fm = [];
+  fm.push('---');
+  fm.push(`phase: ${yamlScalar(phase)}`);
+  fm.push(`generated_at: ${new Date().toISOString()}`);
+  fm.push(`scope_sha256: ${yamlScalar(scopeSha)}`);
+  fm.push(`mode: ${yamlScalar(opts.mode || 'passive')}`);
+  fm.push(`partial_status: ${yamlScalar(opts.status || 'complete')}`);
+  if (Array.isArray(opts.dependsOn) && opts.dependsOn.length) {
+    const arr = '[' + opts.dependsOn.map(v => JSON.stringify(String(v))).join(', ') + ']';
+    fm.push(`depends_on: ${arr}`);
+  }
+  if (opts.tools && Object.keys(opts.tools).length) {
+    fm.push(renderNestedMap({ tools: opts.tools }, 0));
+  }
+  fm.push('---');
+  fm.push('');
+
+  const body = [];
+  for (const [heading, content] of Object.entries(opts.sections || {})) {
+    body.push(`## ${heading}`);
+    body.push('');
+    body.push(String(content == null ? '' : content).trimEnd());
+    body.push('');
+  }
+
+  const file = path.join(sec, `${phase}.md`);
+  fs.writeFileSync(file, fm.join('\n') + '\n' + body.join('\n'), 'utf8');
+  return file;
+}
+
+// loadPartial({ securityDir?, phase }) -> { frontmatter, body } or null.
+function loadPartial(opts) {
+  const phase = opts.phase;
+  assertSafePhase(phase);
+  const sec = opts.securityDir || defaultSecurityDir();
+  const file = path.join(sec, `${phase}.md`);
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!fmMatch) return null;
+  const frontmatter = parseFrontmatter(fmMatch[1]);
+  const body = text.slice(fmMatch[0].length);
+  return { frontmatter, body };
+}
+
+// listPartials({ securityDir? }) -> array of phase names (sorted).
+function listPartials(opts = {}) {
+  const sec = opts.securityDir || defaultSecurityDir();
+  if (!fs.existsSync(sec)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(sec)) {
+    if (name.endsWith('.md') && !name.startsWith('.')) {
+      out.push(name.replace(/\.md$/, ''));
+    }
+  }
+  return out.sort();
+}
+
+module.exports = {
+  writePartial,
+  loadPartial,
+  listPartials,
+  PARTIALS_SUBDIR
+};

package/src/security-overlay/_shared/preflight.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// preflight.js — detects the host environment (OS/arch/package manager)
+// and which tools from data/tool-allowlist.json are installed.
+//
+// Test hook: when WIZE_SEC_PREFLIGHT_OS, WIZE_SEC_PREFLIGHT_PM, and
+// WIZE_SEC_PREFLIGHT_TOOLS (JSON) env vars are set, the real probes
+// are skipped and the values are returned directly. This lets tests
+// simulate Mac/Linux/Windows-WSL without actually running `which` etc.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const ALLOWLIST_PATH = path.join(__dirname, '..', 'data', 'tool-allowlist.json');
+
+function readToolNames() {
+  try {
+    const data = JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf8'));
+    // Skip _schema and any non-array fields.
+    return Object.keys(data).filter(k => k !== '_schema' && Array.isArray(data[k]));
+  } catch (_) {
+    return [];
+  }
+}
+
+function detectOS() {
+  if (process.env.WIZE_SEC_PREFLIGHT_OS) return process.env.WIZE_SEC_PREFLIGHT_OS;
+  const platform = os.platform();
+  if (platform === 'linux') {
+    // Detect WSL by reading /proc/version for "Microsoft" or "WSL".
+    try {
+      const v = fs.readFileSync('/proc/version', 'utf8');
+      if (/microsoft|wsl/i.test(v)) return 'wsl';
+    } catch (_) { /* not linux */ }
+    return 'linux';
+  }
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'win32') return 'win32';
+  return 'linux';
+}
+
+function detectArch() {
+  if (process.env.WIZE_SEC_PREFLIGHT_ARCH) return process.env.WIZE_SEC_PREFLIGHT_ARCH;
+  return process.arch; // 'x64' | 'arm64' | 'ia32' etc.
+}
+
+function detectPackageManager(os) {
+  if (process.env.WIZE_SEC_PREFLIGHT_PM) return process.env.WIZE_SEC_PREFLIGHT_PM;
+  // Check for the most common PMs in order.
+  const candidates = {
+    linux: ['apt', 'dnf', 'pacman', 'zypper', 'apk'],
+    wsl:   ['apt', 'dnf', 'pacman'],
+    darwin: ['brew'],
+    win32: ['scoop', 'chocolatey']
+  };
+  const list = candidates[os] || [];
+  for (const pm of list) {
+    const cmds = { apt: 'apt', dnf: 'dnf', pacman: 'pacman', zypper: 'zypper', apk: 'apk', brew: 'brew', scoop: 'scoop', chocolatey: 'choco' }[pm];
+    try {
+      execFileSync(cmds, ['--version'], { stdio: 'ignore' });
+      return pm;
+    } catch (_) { /* not present */ }
+  }
+  return 'none';
+}
+
+function whichCommand(os) {
+  // 'command -v' on POSIX, 'where' on Windows.
+  if (os === 'win32') return 'where';
+  return 'command';
+}
+
+function whichArg(os) {
+  if (os === 'win32') return [];
+  return ['-v'];
+}
+
+function probeWhich(name, os) {
+  try {
+    const r = spawnSync(whichCommand(os), [...whichArg(os), name], { encoding: 'utf8', timeout: 2000 });
+    if (r.status === 0 && r.stdout) {
+      return r.stdout.split('\n')[0].trim();
+    }
+  } catch (_) { /* not present */ }
+  return null;
+}
+
+function probeVersion(binPath, os) {
+  // Try common version flags. Each is a separate probe; failure is non-fatal.
+  const flags = ['--version', '-version', '-V', 'version'];
+  for (const f of flags) {
+    try {
+      const out = execFileSync(binPath, [f], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const first = (out || '').split('\n')[0].trim();
+      if (first) return first.slice(0, 120);
+    } catch (_) { /* try next */ }
+  }
+  return null;
+}
+
+function detectTools(os) {
+  const names = readToolNames();
+  const tools = {};
+  // Initialize all tools as missing.
+  for (const n of names) tools[n] = { present: false };
+  // Test hook: parse the JSON env var. The hook marks the listed tools as
+  // present; everything else stays missing.
+  if (process.env.WIZE_SEC_PREFLIGHT_TOOLS) {
+    try {
+      const m = JSON.parse(process.env.WIZE_SEC_PREFLIGHT_TOOLS);
+      for (const [name, path] of Object.entries(m)) {
+        if (!(name in tools)) tools[name] = { present: !!path, path: path || undefined, version: null };
+        else {
+          tools[name] = { present: !!path, path: path || undefined, version: null };
+        }
+      }
+    } catch (_) { /* fall through to real detection */ }
+    return tools;
+  }
+  // Real detection.
+  for (const name of names) {
+    const p = probeWhich(name, os);
+    if (!p) {
+      tools[name] = { present: false };
+    } else {
+      tools[name] = { present: true, path: p, version: probeVersion(p, os) };
+    }
+  }
+  return tools;
+}
+
+function runPreflight(opts = {}) {
+  const os_ = detectOS();
+  const arch = detectArch();
+  const pm = detectPackageManager(os_);
+  const tools = detectTools(os_);
+  const missing = Object.entries(tools).filter(([, v]) => !v.present).map(([k]) => k);
+  return {
+    os: os_,
+    arch,
+    packageManager: pm,
+    tools,
+    missing,
+    node: process.version,
+    nodePath: process.execPath
+  };
+}
+
+function formatReport(p) {
+  const present = Object.entries(p.tools).filter(([, v]) => v.present);
+  const lines = [];
+  lines.push(`OS: ${p.os} (${p.arch})`);
+  lines.push(`Package manager: ${p.packageManager || 'none'}`);
+  lines.push(`Node: ${p.node}`);
+  lines.push('');
+  lines.push(`Tools: ${present.length} present, ${p.missing.length} missing`);
+  if (present.length) {
+    lines.push('  present:');
+    for (const [name, info] of present) {
+      const v = info.version ? ` — ${info.version}` : '';
+      lines.push(`    ✓ ${name}${v}`);
+    }
+  }
+  if (p.missing.length) {
+    lines.push('  missing:');
+    for (const name of p.missing) lines.push(`    ✗ ${name}`);
+    lines.push('');
+    lines.push('Run the install script (see .wize/security/install-pentest-tools.sh) to add the missing tools.');
+  }
+  return lines.join('\n');
+}
+
+module.exports = { runPreflight, formatReport, readToolNames };

package/src/security-overlay/_shared/scope-gate.js

@@ -0,0 +1,172 @@
+'use strict';
+
+// scope-gate.js — single point that decides whether an offensive tool may run
+// against a given target. ADR-001: this module is THE gate; skills must call
+// assertTargetInScope before any execFile.
+//
+// Refusals (returns false) are logged to .wize/security/.refusals.log with
+// ISO-8601 timestamp + target + reason. Scope validation errors (ScopeError)
+// propagate — they signal an invalid scope, not a refused action.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  parseScope,
+  validateScope,
+  ScopeError
+} = require('./scope-parser.js');
+
+const REFSUAL_LOG_FILENAME = '.refusals.log';
+
+// --- body parsing --------------------------------------------------------
+
+// Parse the body of a scope.md into a structured allowlist. We accept the
+// shape defined in ADR-002:
+//
+//   ## allowlist
+//   hosts:
+//     - localhost
+//     - 127.0.0.1
+//   urls:
+//     - https://staging.example.internal/api/
+//   paths:
+//     - /api
+//
+// Zero-dep: each list block is matched line-by-line under its `## allowlist`
+// heading until the next `##` heading or EOF. Empty / missing blocks yield
+// empty arrays (which makes EVERY target fail the allowlist — fail-closed).
+function parseAllowlist(body) {
+  const out = { hosts: [], urls: [], paths: [] };
+  const lines = String(body || '').split('\n');
+  let section = null;
+  let key = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+([a-zA-Z_][a-zA-Z0-9_-]*)/);
+    if (h) {
+      section = h[1] === 'allowlist' ? 'allowlist' : null;
+      key = null;
+      continue;
+    }
+    if (section !== 'allowlist') continue;
+    const km = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*$/);
+    if (km) {
+      const k = km[1];
+      if (k === 'hosts' || k === 'urls' || k === 'paths') key = k;
+      else key = null;
+      continue;
+    }
+    const lm = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (lm && key) {
+      out[key].push(lm[1]);
+    }
+  }
+  return out;
+}
+
+// --- matching ------------------------------------------------------------
+
+function matchHost(allowlist, host) {
+  return allowlist.hosts.some(h => h === host);
+}
+
+function matchUrl(allowlist, url) {
+  // Normalize by stripping trailing slashes so 'http://x/' and 'http://x'
+  // match the same prefix.
+  const norm = s => String(s || '').replace(/\/+$/, '');
+  const target = norm(url);
+  return allowlist.urls.some(prefix => target.startsWith(norm(prefix)));
+}
+
+function matchPath(allowlist, p) {
+  // The path must equal or start with one of the allowlisted paths.
+  return allowlist.paths.some(ap => p === ap || p.startsWith(ap.endsWith('/') ? ap : ap + '/'));
+}
+
+// --- public api ----------------------------------------------------------
+
+// loadScope(scopePath) — load + parse + validate. On error: log refusal
+// (best-effort) and rethrow. The caller (a skill) aborts on throw.
+function loadScope(scopePath) {
+  if (!fs.existsSync(scopePath)) {
+    // Cannot log refusal without a known scope directory; rely on caller.
+    throw new ScopeError('MISSING_FILE', null,
+      `scope.md ausente em ${scopePath} — crie e assine em .wize/security/scope.md antes de rodar o pipeline`);
+  }
+  const text = fs.readFileSync(scopePath, 'utf8');
+  const scope = parseScope(text);
+  validateScope(scope);
+  return scope;
+}
+
+// assertTargetInScope(scope, target, { refusalsDir }) -> boolean.
+// On refusal, writes a line to <refusalsDir>/.refusals.log and returns false.
+// Throws ScopeError if `scope` itself is invalid (HASH_MISMATCH, etc.) —
+// callers should treat that as abort-the-pipeline.
+function assertTargetInScope(scope, target, opts = {}) {
+  const refusalsDir = opts.refusalsDir || path.join(process.cwd(), '.wize', 'security');
+
+  // Validate the scope up front so any tampering is surfaced loudly. We
+  // also log the attempt before re-throwing — an invalid scope is itself
+  // a refusal event that must appear in the audit trail.
+  try {
+    validateScope(scope);
+  } catch (err) {
+    if (err && err.code) {
+      logRefusal(refusalsDir, target || {}, `${err.code}: ${String(err.message || '').slice(0, 200)}`);
+    }
+    throw err;
+  }
+
+  const allowlist = parseAllowlist(scope.body);
+
+  // Evaluate each provided dimension of the target. A dimension is "in scope"
+  // iff it matches an allowlist entry. If the caller provides multiple
+  // dimensions (e.g. {host, url}), all of them must match.
+  const checks = [];
+  if (target.host) checks.push({ ok: matchHost(allowlist, target.host), why: 'host not in allowlist' });
+  if (target.url)  checks.push({ ok: matchUrl(allowlist, target.url),   why: 'url not in allowlist' });
+  if (target.path) checks.push({ ok: matchPath(allowlist, target.path), why: 'path not in allowlist' });
+
+  if (checks.length === 0) {
+    // Defensive: refusing a target we can't classify is the safe default.
+    logRefusal(refusalsDir, target, 'no target dimension provided');
+    return false;
+  }
+
+  const allIn = checks.every(c => c.ok);
+  if (!allIn) {
+    const reason = checks.filter(c => !c.ok).map(c => c.why).join('; ');
+    logRefusal(refusalsDir, target, reason);
+    return false;
+  }
+  return true;
+}
+
+// logRefusal(refusalsDir, target, reason) — append a YAML line to
+// .wize/security/.refusals.log. Best-effort: never throws (a logging failure
+// must not mask the refusal that caused it).
+function logRefusal(refusalsDir, target, reason) {
+  try {
+    fs.mkdirSync(refusalsDir, { recursive: true });
+    const file = path.join(refusalsDir, REFSUAL_LOG_FILENAME);
+    const entry = [
+      '-',
+      `  timestamp: ${new Date().toISOString()}`,
+      ...Object.entries(target || {}).map(([k, v]) => `  ${k}: ${String(v).replace(/\n/g, ' ')}`),
+      `  reason: ${String(reason || 'unspecified').replace(/\n/g, ' ')}`
+    ].join('\n') + '\n';
+    fs.appendFileSync(file, entry, 'utf8');
+  } catch (_) {
+    // Intentionally swallow — refusing to crash the caller is more important
+    // than refusing to log. The gate decision (return false) is what matters.
+  }
+}
+
+module.exports = {
+  loadScope,
+  assertTargetInScope,
+  logRefusal,
+  parseAllowlist,
+  ScopeError
+};

package/src/security-overlay/_shared/scope-parser.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// scope-parser.js — file-first parser/validator for `.wize/security/scope.md`.
+//
+// Format (ADR-002):
+//   ---
+//   accepted_by: <string>
+//   accepted_at: <ISO-8601>
+//   scope_sha256: <hex SHA-256 of the body below>
+//   ---
+//
+//   ## allowlist
+//   ...
+//
+// This module is the single source of truth for parsing + validating the
+// scope. Skills that touch offensive tools must call loadScope() and abort
+// on any ScopeError.
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+class ScopeError extends Error {
+  constructor(code, field, message) {
+    super(message || `${code}${field ? ` (${field})` : ''}`);
+    this.name = 'ScopeError';
+    this.code = code;
+    this.field = field || null;
+  }
+}
+
+const REQUIRED_FIELDS = ['accepted_by', 'accepted_at', 'scope_sha256'];
+
+// Split a `scope.md` text into { frontmatter, body }.
+// The frontmatter is the YAML block delimited by `---` lines at the very top.
+// We do NOT use a YAML library (zero-dep); we accept a flat `key: value` shape
+// only, which is the entire scope of this overlay's frontmatter (ADR-002).
+function parseScope(mdText) {
+  if (typeof mdText !== 'string' || !mdText.startsWith('---\n') && mdText !== '---') {
+    throw new ScopeError('INVALID_FORMAT', null,
+      'scope.md must start with a YAML frontmatter block (--- on line 1)');
+  }
+  // Normalize: accept either "---\n...\n---\n\nbody" or "---\n...\n---\nbody".
+  // The trailing \n after the closing --- is part of the separator, NOT the body.
+  // This is what the user signs when they run --sign-scope (and what they
+  // expect when the hash is computed on the body they wrote).
+  const fmMatch = mdText.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!fmMatch) {
+    throw new ScopeError('INVALID_FORMAT', null,
+      'scope.md frontmatter is missing or not terminated by a second --- line');
+  }
+  const fmText = fmMatch[1];
+  const body = mdText.slice(fmMatch[0].length);
+
+  const frontmatter = {};
+  for (const line of fmText.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+    if (!m) continue;
+    frontmatter[m[1]] = m[2].replace(/^['"]|['"]$/g, ''); // strip wrapping quotes
+  }
+
+  return { frontmatter, body };
+}
+
+// Validate a parsed scope. Returns true on success; throws ScopeError otherwise.
+// opts: { now?: Date } — for future `accepted_at` warning. Currently unused but
+// reserved so we can add a warn() channel without breaking callers.
+function validateScope(scope, opts = {}) {
+  if (!scope || typeof scope !== 'object') {
+    throw new ScopeError('INVALID_FORMAT', null, 'scope is not an object');
+  }
+  const fm = scope.frontmatter || {};
+  for (const field of REQUIRED_FIELDS) {
+    if (!fm[field] || typeof fm[field] !== 'string' || fm[field].trim() === '') {
+      throw new ScopeError('MISSING_FIELDS', field,
+        `scope.md frontmatter is missing required field "${field}" — ` +
+        `crie e assine com "wize-sec-pentest --sign-scope" ou preencha manualmente`);
+    }
+  }
+
+  // Hash integrity. Compute SHA-256 of the body and compare to scope_sha256.
+  // We re-parse the body as-is (already stripped of frontmatter) — the original
+  // signing was done on the raw body bytes, so byte-equality matters.
+  const expected = computeScopeSha256(scope.body || '');
+  if (expected !== fm.scope_sha256) {
+    throw new ScopeError('HASH_MISMATCH', 'scope_sha256',
+      `scope.md body was modified after acceptance (expected ${expected.slice(0, 12)}…, ` +
+      `got ${String(fm.scope_sha256).slice(0, 12)}…) — re-assine com "wize-sec-pentest --sign-scope"`);
+  }
+
+  // Soft check: accepted_at in the future is a warning, not an error.
+  // We don't surface the warning through this function (no logger plumbed
+  // here); consumers can inspect frontmatter.accepted_at themselves.
+
+  return true;
+}
+
+function computeScopeSha256(bodyText) {
+  return crypto.createHash('sha256').update(String(bodyText || ''), 'utf8').digest('hex');
+}
+
+// Read + parse + validate a scope.md file. The single entry point used by
+// every offensive skill (AC-E02-1, AC-E02-3).
+function loadScope(scopePath) {
+  if (!fs.existsSync(scopePath)) {
+    throw new ScopeError('MISSING_FILE', null,
+      `scope.md ausente em ${scopePath} — crie e assine em .wize/security/scope.md antes de rodar o pipeline`);
+  }
+  const text = fs.readFileSync(scopePath, 'utf8');
+  const scope = parseScope(text);
+  validateScope(scope);
+  return scope;
+}
+
+module.exports = {
+  parseScope,
+  validateScope,
+  computeScopeSha256,
+  loadScope,
+  ScopeError
+};