trackfw 6.10.0 → 7.0.0

package/src/thirdparty/fetch.js

@@ -0,0 +1,140 @@
+'use strict'
+
+// Node port of internal/thirdparty/fetch.go — the network fetch primitive
+// used by the two-phase third-party artifact gate (skills/agents installed
+// from a URL). See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D7).
+
+const https = require('node:https')
+const { URL } = require('node:url')
+
+// MAX_CONTENT_SIZE is the network fetch cap for third-party text artifacts
+// (D7): 2 MiB — mirrors internal/thirdparty/fetch.go:maxContentSize.
+const MAX_CONTENT_SIZE = 2 * 1024 * 1024
+
+// MAX_REDIRECTS mirrors internal/thirdparty/fetch.go:maxRedirects (3). Note
+// the Go reference's own net/http.Client.CheckRedirect semantics: the check
+// runs BEFORE following a redirect and compares the count of requests
+// ALREADY COMPLETED (via.length, which includes the request that just
+// returned the redirect) against maxRedirects — so in practice only
+// (maxRedirects - 1) redirects are ever followed before the next one is
+// refused. Reproduced here byte-for-byte via requestsCompleted, not
+// "fixed" to what the doc comment alone might suggest.
+const MAX_REDIRECTS = 3
+
+const TIMEOUT_MS = 30 * 1000
+
+// ALLOWED_CONTENT_TYPES mirrors internal/thirdparty/fetch.go:allowedContentTypes.
+const ALLOWED_CONTENT_TYPES = new Set(['text/plain', 'text/markdown', 'text/x-markdown'])
+
+// contentTypeAllowed mirrors internal/thirdparty/fetch.go:contentTypeAllowed
+// — tolerates an optional "; charset=..." (or any other parameter) suffix.
+function contentTypeAllowed(contentType) {
+  const raw = String(contentType || '')
+  const semi = raw.indexOf(';')
+  const base = (semi >= 0 ? raw.slice(0, semi) : raw).trim().toLowerCase()
+  return ALLOWED_CONTENT_TYPES.has(base)
+}
+
+// api is the module.exports object itself, referenced internally via
+// `api.requestOnce(...)` so tests can substitute the single HTTP round
+// trip without a real TLS socket — mirrors the thirdPartyFetch
+// package-var substitution pattern already used at the command layer
+// (npm/src/commands/thirdparty.js). Added in ML-4C to close a coverage
+// gap hefesto-tf found: the resp.statusCode !== 200 branch below existed
+// but was never exercised by any test.
+const api = {}
+
+function requestOnce(rawURL) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(rawURL, { timeout: TIMEOUT_MS }, res => {
+      const chunks = []
+      let total = 0
+      let tooLarge = false
+      res.on('data', chunk => {
+        if (tooLarge) return
+        total += chunk.length
+        if (total > MAX_CONTENT_SIZE) {
+          tooLarge = true
+          res.destroy()
+          return
+        }
+        chunks.push(chunk)
+      })
+      res.on('end', () => {
+        resolve({ statusCode: res.statusCode, headers: res.headers, body: Buffer.concat(chunks), tooLarge })
+      })
+      res.on('error', err => reject(new Error(`failed to read response body: ${err.message}`)))
+    })
+    req.on('timeout', () => req.destroy(new Error('fetch failed: request timed out after 30s')))
+    req.on('error', err => reject(new Error(`fetch failed: ${err.message}`)))
+  })
+}
+
+// fetchOnce follows redirects with the same accounting as Go's
+// fetchClient.CheckRedirect (see MAX_REDIRECTS doc above). requestsCompleted
+// starts at 0 and is incremented after every completed HTTP request.
+async function fetchOnce(rawURL, requestsCompleted) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch (err) {
+    throw new Error(`invalid URL "${rawURL}": ${err.message}`)
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`refused: URL scheme must be https, got "${parsed.protocol.replace(/:$/, '')}"`)
+  }
+
+  const res = await api.requestOnce(rawURL)
+  requestsCompleted += 1
+
+  if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+    if (requestsCompleted >= MAX_REDIRECTS) {
+      throw new Error(`fetch failed: stopped after ${MAX_REDIRECTS} redirects`)
+    }
+    let next
+    try {
+      next = new URL(res.headers.location, rawURL).toString()
+    } catch (err) {
+      throw new Error(`invalid redirect location: ${err.message}`)
+    }
+    const nextScheme = new URL(next).protocol
+    if (nextScheme !== 'https:') {
+      throw new Error(`redirect to non-https URL refused: ${next}`)
+    }
+    return fetchOnce(next, requestsCompleted)
+  }
+
+  if (res.statusCode !== 200) {
+    throw new Error(`fetch failed: HTTP ${res.statusCode} for ${rawURL}`)
+  }
+
+  const contentType = res.headers['content-type']
+  if (!contentTypeAllowed(contentType)) {
+    throw new Error(`refused: unsupported Content-Type "${contentType || ''}" (allowed: text/plain, text/markdown, text/x-markdown)`)
+  }
+
+  if (res.tooLarge) {
+    throw new Error(`refused: content exceeds ${MAX_CONTENT_SIZE} bytes`)
+  }
+
+  return res.body
+}
+
+// fetch downloads the content at rawURL under the D7 network policy:
+// https-only (validated before the first request), a 30s timeout, at most
+// (MAX_REDIRECTS - 1) redirect hops (each revalidated for https), a 2 MiB
+// size cap, and a Content-Type allowlist. Mirrors
+// internal/thirdparty/fetch.go:Fetch.
+async function fetch(rawURL) {
+  return fetchOnce(rawURL, 0)
+}
+
+api.fetch = fetch
+api.contentTypeAllowed = contentTypeAllowed
+api.requestOnce = requestOnce
+api.MAX_CONTENT_SIZE = MAX_CONTENT_SIZE
+api.MAX_REDIRECTS = MAX_REDIRECTS
+
+module.exports = api

package/src/thirdparty/markers.js

@@ -0,0 +1,207 @@
+'use strict'
+
+// Node port of internal/thirdparty/markers.go — the D3 objective-refusal
+// marker check and the Checksum primitive. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D3, D6).
+
+const crypto = require('node:crypto')
+const { URL } = require('node:url')
+
+// LITERAL_MARKERS mirrors internal/thirdparty/markers.go:literalMarkers — an
+// objective, literal tripwire list, not a filter against a competent
+// adversary (see the ADR's "o que este critério NÃO cobre" section).
+const LITERAL_MARKERS = [
+  'git authority',
+  'mode lock',
+  'governance prerequisite',
+  'reporting boundary',
+  'scope boundary',
+  'dispatch contract',
+]
+
+// HTML_COMMENT_PATTERN matches HTML comments; step 1 of the D3 pipeline
+// NEUTRALIZES them (strips only the delimiters, keeping the inner content
+// in place to be scanned), mirroring internal/thirdparty/markers.go's
+// D3-ter(b) amendment — see neutralizeHTMLComments below.
+const HTML_COMMENT_PATTERN = /<!--([\s\S]*?)-->/g
+
+// neutralizeHTMLComments strips only the HTML comment delimiters ("<!--"
+// and "-->"), keeping whatever text was between them in place to be
+// scanned by the later steps of the pipeline. D3-ter(b): the previous
+// wholesale removal contradicted D3's own written justification for this
+// step ("an LLM reads HTML comments in the token stream") — a marker
+// hidden as `<!-- ## Git authority -->` passed clean.
+function neutralizeHTMLComments(text) {
+  return text.replace(HTML_COMMENT_PATTERN, '$1')
+}
+
+// FENCE_PREFIX_PATTERN detects a fence-opening/closing line: optional
+// leading whitespace followed by three or more backticks or tildes.
+//
+// Unlike the Go reference — which is forced into an explicit line-scanner
+// because Go's RE2-based regexp package rejects backreferences at runtime
+// (see vault/notes/go-regexp-re2-sem-backreference-fenced-block-removal-2026-08-15.md)
+// — JS RegExp does support backreferences. This port still uses the same
+// explicit line-scanner algorithm as the Go reference (removeFencedBlocks
+// below), NOT because JS requires it, but because the scanner is what
+// implements the actual CommonMark closing rule correctly (same delimiter
+// character, closer repeat count >= opener repeat count, unclosed fence
+// never re-opens a heading read). A single backreference regex here would
+// diverge from the Go reference on: an unclosed fence, a closing run
+// shorter than the opener, and an indented fence — porting the algorithm,
+// not the regex, is what keeps behavior byte-identical to Go.
+const FENCE_PREFIX_PATTERN = /^\s*(```+|~~~+)/
+
+// trimChar mirrors Go's strings.Trim(s, cutset) for a single-char cutset:
+// strips ONLY leading/trailing runs of ch, never occurrences in the middle.
+function trimChar(str, ch) {
+  let start = 0
+  let end = str.length
+  while (start < end && str[start] === ch) start++
+  while (end > start && str[end - 1] === ch) end--
+  return str.slice(start, end)
+}
+
+// removeFencedBlocks strips PROPERLY-CLOSED fenced code blocks (``` or
+// ~~~), step 2 of the D3 pipeline: lines inside a closed fence are not read
+// as headings, otherwise documentation that merely quotes the marker list
+// would be refused by its own criterion. A fence is closed by a line
+// starting with the same delimiter character, with at least as many
+// repeats as the opener — the CommonMark rule.
+//
+// D3-ter(a) amendment: an opener with NO matching closer before EOF is NOT
+// a fence for this check — the buffered lines (including the opener) are
+// replayed as ordinary text instead of being dropped. Before this
+// amendment, an unclosed fence swallowed the rest of the document as
+// "fenced" content, silently hiding any marker after it. Mirrors
+// internal/thirdparty/markers.go:removeFencedBlocks.
+function removeFencedBlocks(text) {
+  const lines = text.split('\n')
+  const out = []
+  let buffered = [] // lines consumed since the current fence opener; replayed verbatim if it never closes
+  let closer = '' // fence delimiter run that closes the current block, '' if not in a fence
+  for (const line of lines) {
+    if (closer === '') {
+      const match = FENCE_PREFIX_PATTERN.exec(line)
+      if (match) {
+        closer = match[1]
+        buffered = [line] // keep the opener in case this fence never closes
+        continue
+      }
+      out.push(line)
+      continue
+    }
+    // Inside a (possibly-never-closing) fence: buffer the line, then check
+    // if it closes the block.
+    buffered.push(line)
+    const trimmed = line.trim()
+    const delimChar = closer[0]
+    if (trimmed.startsWith(delimChar.repeat(closer.length)) && trimChar(trimmed, delimChar) === '') {
+      closer = ''
+      buffered = [] // closed properly: the buffered fenced content is discarded, as before
+    }
+  }
+  if (closer !== '') {
+    // Reached EOF still "inside" a fence that never closed (D3-ter(a)): not
+    // a fence at all — replay every buffered line, including the opener,
+    // as ordinary text to be scanned.
+    out.push(...buffered)
+  }
+  return out.join('\n')
+}
+
+// HEADING_LINE_PATTERN matches a single, already-collapsed Markdown heading
+// line (level 1-6). Applied per-line after step 5, on text that no longer
+// contains internal runs of whitespace.
+const HEADING_LINE_PATTERN = /^#{1,6}\s+(.*)$/
+
+// WHITESPACE_PATTERN collapses runs of internal whitespace, step 5.
+const WHITESPACE_PATTERN = /\s+/g
+
+// checkMarkers applies the D3 objective-refusal criterion to content and
+// returns the literal marker names (from LITERAL_MARKERS) that matched as a
+// heading. The normalization pipeline, in fixed order, mirrors
+// internal/thirdparty/markers.go:CheckMarkers exactly:
+//  1. remove HTML comments;
+//  2. remove fenced code blocks (``` and ~~~);
+//  3. NFKC normalize;
+//  4. casefold (String.prototype.toLowerCase(), matching Go's
+//     strings.ToLower — not a true Unicode casefold, deliberately, to stay
+//     byte-identical to the Go reference);
+//  5. collapse internal whitespace + strip, applied per line;
+//  6. match only lines matching ^#{1,6}\s+ against the literal marker list.
+//
+// content may be a Buffer or a string; Buffers are decoded as UTF-8,
+// mirroring Go's string(content) over raw bytes.
+function checkMarkers(content) {
+  let text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+
+  // 1. Neutralize HTML comments — strip only the delimiters, keep the
+  // inner content in place to be scanned (D3-ter(b)).
+  text = neutralizeHTMLComments(text)
+
+  // 2. Remove fenced code blocks — lines inside a fence are not headings.
+  text = removeFencedBlocks(text)
+
+  // 3. NFKC normalize.
+  text = text.normalize('NFKC')
+
+  // 4. Casefold.
+  text = text.toLowerCase()
+
+  const matched = []
+  const seen = new Set()
+  for (const line of text.split('\n')) {
+    // 5. Collapse internal whitespace + strip.
+    const collapsed = line.replace(WHITESPACE_PATTERN, ' ').trim()
+
+    // 6. Match only heading lines against the literal marker list.
+    const match = HEADING_LINE_PATTERN.exec(collapsed)
+    if (!match) continue
+    const body = match[1]
+    for (const marker of LITERAL_MARKERS) {
+      if (body === marker && !seen.has(marker)) {
+        matched.push(marker)
+        seen.add(marker)
+      }
+    }
+  }
+  return matched
+}
+
+// checksum returns the SHA-256 hex digest of the raw bytes, before any
+// normalization. Mirrors internal/thirdparty/markers.go:Checksum. raw may be
+// a Buffer or a string (encoded as UTF-8).
+function checksum(raw) {
+  const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf8')
+  return crypto.createHash('sha256').update(buf).digest('hex')
+}
+
+// redactURL returns rawURL with its query string — and userinfo, if
+// present — replaced by the literal marker "[redacted]" (D6-bis). Used
+// before persisting a third-party artifact's source URL to disk (the
+// quarantine record and the provenance entry): a pre-signed URL can carry a
+// bearer token in its query string, which would otherwise become a
+// permanent secret in the git history the moment either file is committed.
+// The full, unredacted URL is used only in memory, for the network fetch
+// itself (D7) — never for anything persisted. Mirrors
+// internal/thirdparty/markers.go:RedactURL. Deliberately constructs the
+// result manually (protocol/host/pathname/hash) rather than mutating and
+// re-serializing via the URL object's own .toString(), to stay
+// byte-identical to the Go/Python output shape rather than depend on
+// WHATWG URL serialization nuances.
+function redactURL(rawURL) {
+  let parsed
+  try {
+    parsed = new URL(rawURL)
+  } catch {
+    return rawURL
+  }
+  let result = `${parsed.protocol}//${parsed.host}${parsed.pathname}`
+  if (parsed.search !== '') result += '?[redacted]'
+  result += parsed.hash
+  return result
+}
+
+module.exports = { checkMarkers, checksum, redactURL, literalMarkers: LITERAL_MARKERS, removeFencedBlocks }

package/src/thirdparty/provenance.js

@@ -0,0 +1,114 @@
+'use strict'
+
+// Node port of internal/thirdparty/provenance.go — the D6/D8c provenance
+// record and TOCTOU-closing approval check. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D6, D8c, D8f).
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { atomicWrite } = require('./quarantine')
+const { redactURL } = require('./markers')
+
+// PROVENANCE_SCHEMA_VERSION mirrors internal/thirdparty/provenance.go:provenanceSchemaVersion.
+//
+// Bumped 1 -> 2 (ADR-2026-08-15 D2-bis, ML-3B) to add the entry field
+// installed_sha256 (SHA-256 of the NORMALIZED bytes, computed at install
+// time). checksum_sha256 (SHA-256 of the RAW bytes, the D8c approval
+// anchor) is unchanged. No migration path exists or is needed: at the time
+// of the bump no provenance file existed anywhere with schema_version 1.
+const PROVENANCE_SCHEMA_VERSION = 2
+
+function emptyProvenance() {
+  return { schema_version: PROVENANCE_SCHEMA_VERSION, entries: {} }
+}
+
+// provenancePath returns the on-disk path of the provenance file, rooted at
+// root. Mirrors internal/thirdparty/provenance.go:ProvenancePath.
+function provenancePath(root) {
+  return path.join(root, '.trackfw', 'thirdparty-provenance.json')
+}
+
+// loadProvenance reads and validates the provenance file: a missing file is
+// a legitimate "nothing installed from a third party yet" state and returns
+// an empty, schema-valid Provenance; invalid JSON or an unsupported
+// schema_version are fatal and thrown as errors — never silently degraded
+// to empty (D8f). Deliberately asymmetric with readQuarantine (see
+// quarantine.js) — do NOT "fix" this asymmetry, it is intentional. Mirrors
+// internal/thirdparty/provenance.go:LoadProvenance.
+function loadProvenance(root) {
+  const filename = provenancePath(root)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyProvenance()
+    throw new Error(`read thirdparty provenance: ${err.message}`)
+  }
+  let prov
+  try {
+    prov = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode thirdparty provenance: ${err.message}`)
+  }
+  if (prov.schema_version !== PROVENANCE_SCHEMA_VERSION) {
+    throw new Error(`unsupported thirdparty provenance schema ${prov.schema_version}`)
+  }
+  if (!prov.entries || Array.isArray(prov.entries)) prov.entries = {}
+  return prov
+}
+
+// writeProvenance persists prov atomically.
+//
+// Failure here MUST propagate to the caller and abort the installation
+// (D6) — the deliberate opposite of a best-effort/log-and-continue write.
+// Provenance is the only record of who approved a third-party artifact, so
+// losing a write silently would leave an unapproved artifact on disk
+// indistinguishable from an approved one.
+//
+// Every entry's url is passed through redactURL before serialization
+// (D6-bis) — defense-in-depth, mirroring
+// internal/thirdparty/provenance.go:WriteProvenance's doc comment: no
+// command in this codebase writes a provenance entry's url today (D10.2),
+// but this call site guarantees the query string is never persisted here
+// regardless. Idempotent: redacting an already-redacted url is a no-op.
+function writeProvenance(root, prov) {
+  const entries = prov.entries || {}
+  const redactedEntries = {}
+  for (const [dest, entry] of Object.entries(entries)) {
+    redactedEntries[dest] = { ...entry, url: redactURL(entry.url) }
+  }
+  const toWrite = { schema_version: PROVENANCE_SCHEMA_VERSION, entries: redactedEntries }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(provenancePath(root), data, 0o600)
+}
+
+// upsertProvenanceEntry loads the current provenance, sets
+// entries[dest] = entry, and writes it back. The write is fatal-on-failure
+// (see writeProvenance) — callers MUST treat a thrown error as
+// "installation aborted", never log-and-continue. Mirrors
+// internal/thirdparty/provenance.go:UpsertProvenanceEntry.
+function upsertProvenanceEntry(root, dest, entry) {
+  const prov = loadProvenance(root)
+  prov.entries[dest] = entry
+  writeProvenance(root, prov)
+}
+
+// verifyApproval is the D8c TOCTOU close: it only succeeds if dest has a
+// provenance entry whose checksum_sha256 matches checksum exactly and whose
+// approved_by is non-empty. A destination with no entry, an entry for a
+// different checksum, or an entry with an empty approved_by all fail
+// identically: not approved. Mirrors
+// internal/thirdparty/provenance.go:VerifyApproval.
+function verifyApproval(root, checksum, dest) {
+  const prov = loadProvenance(root)
+  const entry = prov.entries[dest]
+  if (!entry) throw new Error(`no provenance entry for destination "${dest}": not approved`)
+  if (entry.checksum_sha256 !== checksum) {
+    throw new Error(`provenance checksum mismatch for "${dest}": approved ${entry.checksum_sha256}, got ${checksum}`)
+  }
+  if (!entry.approved_by) throw new Error(`provenance entry for "${dest}" has no approved_by`)
+}
+
+module.exports = { provenancePath, loadProvenance, writeProvenance, upsertProvenanceEntry, verifyApproval, PROVENANCE_SCHEMA_VERSION }

package/src/thirdparty/quarantine.js

@@ -0,0 +1,113 @@
+'use strict'
+
+// Node port of internal/thirdparty/quarantine.go — the D8a/b on-disk
+// quarantine record for one fetched third-party artifact. See:
+// docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
+// (D8a, D8b, D8f).
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { checksum: sha256hex, redactURL } = require('./markers')
+
+// QUARANTINE_SCHEMA_VERSION mirrors internal/thirdparty/quarantine.go:quarantineSchemaVersion.
+const QUARANTINE_SCHEMA_VERSION = 1
+
+// atomicWrite writes data to filename via a temp file in the same
+// directory followed by fs.renameSync, so a reader never observes a
+// partially written file. Mirrors internal/thirdparty/quarantine.go's
+// atomicWrite (shared there by quarantine.go and provenance.go; replicated
+// here and in references.js, same rationale as the Go reference's own
+// per-package duplication of Checksum in markers.go's doc comment).
+function atomicWrite(filename, data, mode) {
+  const directory = path.dirname(filename)
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const tmp = path.join(directory, `.trackfw-tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`)
+  try {
+    fs.writeFileSync(tmp, data, { mode })
+    fs.chmodSync(tmp, mode)
+    fs.renameSync(tmp, filename)
+  } finally {
+    if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
+  }
+}
+
+// quarantinePath returns the on-disk path of the quarantine record for
+// checksum, rooted at root — the project or home directory the caller is
+// operating on. Mirrors internal/thirdparty/quarantine.go:QuarantinePath.
+function quarantinePath(root, checksum) {
+  return path.join(root, '.trackfw', 'thirdparty-quarantine', `${checksum}.json`)
+}
+
+// newQuarantineEntry builds a quarantine entry from freshly fetched content.
+// matchedMarkers is checkMarkers()'s return value for raw; an empty array
+// yields marker_check.result === "pass". The content is embedded whole,
+// base64-encoded, in content_base64 — never a path to another file (D8b):
+// an indirection through a second file would reopen the TOCTOU window the
+// quarantine record exists to close.
+//
+// rawURL is stored via redactURL, not verbatim (D6-bis) — see
+// internal/thirdparty/quarantine.go:NewQuarantineEntry's doc comment.
+function newQuarantineEntry(rawURL, raw, matchedMarkers, kind, requestedTargets) {
+  const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw), 'utf8')
+  return {
+    schema_version: QUARANTINE_SCHEMA_VERSION,
+    url: redactURL(rawURL),
+    checksum_sha256: sha256hex(buf),
+    fetched_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    content_base64: buf.toString('base64'),
+    marker_check: {
+      result: matchedMarkers.length > 0 ? 'fail' : 'pass',
+      matched_markers: matchedMarkers,
+    },
+    kind,
+    requested_targets: requestedTargets || [],
+  }
+}
+
+// writeQuarantine persists entry atomically at
+// quarantinePath(root, entry.checksum_sha256). Mirrors
+// internal/thirdparty/quarantine.go:WriteQuarantine.
+function writeQuarantine(root, entry) {
+  const toWrite = { ...entry, schema_version: QUARANTINE_SCHEMA_VERSION }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(quarantinePath(root, entry.checksum_sha256), data, 0o600)
+}
+
+// readQuarantine reads and validates the quarantine record for checksum,
+// fail-closed (D8f): a missing file, invalid JSON, or an unsupported
+// schema_version are all thrown as errors, never degraded to an empty
+// value. Deliberately asymmetric with loadProvenance (see provenance.js):
+// here, the caller already holds a checksum obtained from a prior fetch and
+// is asking for that specific record, so its absence is itself the failure
+// being guarded against. Do NOT "fix" this asymmetry — it is intentional,
+// verified against the Go reference by audit. Mirrors
+// internal/thirdparty/quarantine.go:ReadQuarantine.
+function readQuarantine(root, checksum) {
+  const filename = quarantinePath(root, checksum)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    throw new Error(`read quarantine entry "${checksum}": ${err.message}`)
+  }
+  let entry
+  try {
+    entry = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode quarantine entry "${checksum}": ${err.message}`)
+  }
+  if (entry.schema_version !== QUARANTINE_SCHEMA_VERSION) {
+    throw new Error(`unsupported quarantine schema ${entry.schema_version} for "${checksum}"`)
+  }
+  return entry
+}
+
+// decodeContent decodes entry.content_base64 back to the original raw
+// bytes (a Buffer). Mirrors internal/thirdparty/quarantine.go:QuarantineEntry.DecodeContent.
+function decodeContent(entry) {
+  return Buffer.from(entry.content_base64, 'base64')
+}
+
+module.exports = { quarantinePath, newQuarantineEntry, writeQuarantine, readQuarantine, decodeContent, atomicWrite, QUARANTINE_SCHEMA_VERSION }