trackfw 6.9.1 → 7.0.0

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 }

package/src/thirdparty/references.js

@@ -0,0 +1,194 @@
+'use strict'
+
+// Node port of the D9 extension point from internal/integrations/render.go
+// (ThirdPartyReference, UpsertThirdPartyReference, ApplyThirdPartyReferences,
+// NormalizeThirdPartyContent, ResolveThirdPartySkillDestination) — see the
+// D9 amendment in
+// 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.
+//
+// D9 note (see docs/agents-working-context.md, ML-1A entry): this file
+// persists .trackfw/thirdparty-references.json, an artifact NOT mentioned
+// by the original ADR text (D1-D8) — it exists because a plain rendered
+// catalog agent file cannot simply have a reference block appended once:
+// the next `trackfw agents update` calls buildPlans -> render again, which
+// re-derives content straight from the catalog asset and knows nothing
+// about the appended block. Persisting the reference here and having
+// buildPlans call applyThirdPartyReferences after every render (see
+// ../integrations/index.js) makes the canonical render reproduce the
+// block, so repeated `agents update` runs settle at state "current"
+// instead of fighting the third-party attachment.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { atomicWrite } = require('./quarantine')
+const { target: catalogTarget, surfaceFor } = require('../integrations/catalog')
+
+const THIRDPARTY_REFERENCES_SCHEMA_VERSION = 1
+
+// truncateBeforeIdSegment drops the "{{id}}"-bearing path segment and
+// everything after it, returning the shared parent directory. Duplicated
+// (not imported) from npm/src/integrations/catalog.js — that module does
+// not export it, and this ML's file list does not include editing
+// catalog.js; this is the same small, pure, low-risk duplication already
+// used by the Go reference itself (see markers.go's doc comment on
+// Checksum) rather than widening catalog.js's public surface for one
+// caller.
+function truncateBeforeIdSegment(p) {
+  const segments = p.split('/')
+  const index = segments.findIndex(segment => segment.includes('{{id}}'))
+  if (index === -1) return p
+  return segments.slice(0, index).join('/')
+}
+
+function thirdPartyReferencesPath(root) {
+  return path.join(root, '.trackfw', 'thirdparty-references.json')
+}
+
+function emptyRegistry() {
+  return { schema_version: THIRDPARTY_REFERENCES_SCHEMA_VERSION, entries: {} }
+}
+
+function loadThirdPartyReferenceRegistry(root) {
+  const filename = thirdPartyReferencesPath(root)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyRegistry()
+    throw new Error(`read thirdparty reference registry: ${err.message}`)
+  }
+  let reg
+  try {
+    reg = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`decode thirdparty reference registry: ${err.message}`)
+  }
+  if (reg.schema_version !== THIRDPARTY_REFERENCES_SCHEMA_VERSION) {
+    throw new Error(`unsupported thirdparty reference registry schema ${reg.schema_version}`)
+  }
+  if (!reg.entries || Array.isArray(reg.entries)) reg.entries = {}
+  return reg
+}
+
+function writeThirdPartyReferenceRegistry(root, reg) {
+  const toWrite = { schema_version: THIRDPARTY_REFERENCES_SCHEMA_VERSION, entries: reg.entries || {} }
+  const data = `${JSON.stringify(toWrite, null, 2)}\n`
+  atomicWrite(thirdPartyReferencesPath(root), data, 0o600)
+}
+
+// upsertThirdPartyReference records (or replaces, keyed by ref.slug) a
+// reference from the rendered catalog agent artifact (targetID,
+// agentItemID) to a third-party skill, persisted under root (project root
+// — D4). Idempotent: calling it twice with the same slug replaces the
+// prior entry instead of duplicating it. Mirrors
+// internal/integrations/render.go:UpsertThirdPartyReference.
+function upsertThirdPartyReference(root, targetID, agentItemID, ref) {
+  const reg = loadThirdPartyReferenceRegistry(root)
+  const key = `${targetID}/${agentItemID}`
+  const refs = reg.entries[key] || []
+  let replaced = false
+  for (let i = 0; i < refs.length; i++) {
+    if (refs[i].slug === ref.slug) {
+      refs[i] = ref
+      replaced = true
+      break
+    }
+  }
+  if (!replaced) refs.push(ref)
+  refs.sort((a, b) => a.slug.localeCompare(b.slug))
+  reg.entries[key] = refs
+  writeThirdPartyReferenceRegistry(root, reg)
+}
+
+// THIRD_PARTY_REF_START/END are the composition markers (D5), dedicated and
+// distinct from the auxiliary-rules-file markers (a different subsystem).
+// Mirrors internal/integrations/render.go:thirdPartyRefStart/thirdPartyRefEnd.
+const THIRD_PARTY_REF_START = '<!-- trackfw:thirdparty-skills:start -->'
+const THIRD_PARTY_REF_END = '<!-- trackfw:thirdparty-skills:end -->'
+
+// applyThirdPartyReferences injects or updates the third-party reference
+// block in content for (targetID, agentItemID), based on entries persisted
+// by upsertThirdPartyReference. When root is empty or there are no entries
+// for this key, content is returned byte-for-byte unchanged — this is the
+// guarantee that every agent artifact which never received a third-party
+// attachment renders exactly as it did before D5/D9 were introduced.
+// Mirrors internal/integrations/render.go:ApplyThirdPartyReferences.
+function applyThirdPartyReferences(root, content, targetID, agentItemID) {
+  if (!root) return content
+  const reg = loadThirdPartyReferenceRegistry(root)
+  const refs = reg.entries[`${targetID}/${agentItemID}`] || []
+  if (!refs.length) return content
+
+  let block = `${THIRD_PARTY_REF_START}\n`
+  for (const ref of refs) {
+    block += `- Third-party skill "${ref.slug}": ${ref.destination} (source: ${ref.url})\n`
+  }
+  block += THIRD_PARTY_REF_END
+
+  let text = content
+  const start = text.indexOf(THIRD_PARTY_REF_START)
+  if (start === -1) {
+    if (!text.endsWith('\n')) text += '\n'
+    text += `\n${block}\n`
+    return text
+  }
+  // Search for the end marker starting at start, not from the beginning of
+  // text (hefesto-tf finding, ML-4C): searching the whole text could find
+  // an END marker that appears BEFORE start, producing end < start and
+  // silently corrupting the composed output. Anchoring the search at start
+  // makes that impossible: end is either -1 or >= start.
+  const relEnd = text.slice(start).indexOf(THIRD_PARTY_REF_END)
+  if (relEnd === -1) {
+    // Malformed (start without end): append a fresh block rather than
+    // guess at repair.
+    text += `\n${block}\n`
+    return text
+  }
+  const end = start + relEnd
+  const newText = text.slice(0, start) + block + text.slice(end + THIRD_PARTY_REF_END.length)
+  return `${newText.replace(/\n+$/, '')}\n`
+}
+
+// normalizeThirdPartyContent applies the same normalization used for
+// managed catalog skill content (trim + single trailing newline) to raw
+// third-party bytes before they are written through IntegrationManager, so
+// third-party artifacts are stored with the same on-disk convention as
+// catalog artifacts. Mirrors
+// internal/integrations/render.go:NormalizeThirdPartyContent.
+function normalizeThirdPartyContent(content) {
+  const text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+  return `${text.trim()}\n`
+}
+
+// resolveThirdPartySkillDestination computes where a third-party artifact's
+// content should live for (targetID, scope), per D5: the shared parent
+// directory of the target's own canonical project/global Skills install
+// path template, followed by "/thirdparty/<slug>.md". The directory always
+// comes from the catalog's own path template — never a hardcoded
+// ".claude" — so every target the catalog declares a Skills capability for
+// is supported without per-target special-casing. Mirrors
+// internal/integrations/render.go:ResolveThirdPartySkillDestination.
+function resolveThirdPartySkillDestination(targetID, scope, slug) {
+  let targetEntry
+  try {
+    targetEntry = catalogTarget(targetID)
+  } catch {
+    throw new Error(`unknown target "${targetID}"`)
+  }
+  const surface = surfaceFor(targetEntry, undefined, 'skills')
+  const installPath = (surface.paths.skills || []).find(entry => entry.scope === scope)
+  if (!installPath) throw new Error(`target ${targetID} surface ${surface.id} has no ${scope} skills path`)
+  const baseDir = truncateBeforeIdSegment(installPath.path)
+  return { destination: `${baseDir}/thirdparty/${slug}.md`, surfaceID: surface.id }
+}
+
+module.exports = {
+  thirdPartyReferencesPath,
+  upsertThirdPartyReference,
+  applyThirdPartyReferences,
+  normalizeThirdPartyContent,
+  resolveThirdPartySkillDestination,
+  THIRD_PARTY_REF_START,
+  THIRD_PARTY_REF_END,
+}