@mnstry/atelier 0.2.0-alpha.1

package/src/attestation/jcs.mjs

@@ -0,0 +1,64 @@
+// RFC 8785 (JSON Canonicalization Scheme) serializer.
+//
+// Numbers and strings delegate to JSON.stringify: RFC 8785 defines both
+// serializations as exactly ECMAScript's (ES2019+ well-formed stringify
+// escapes lone surrogates, and number formatting follows Number::toString).
+// The module's own work is recursive descent, UTF-16 code-unit key sorting
+// (plain Array.prototype.sort over strings IS code-unit order), and strict
+// rejection of every value JSON cannot faithfully round-trip.
+//
+// Rejections throw TypeError with a `JCS:` prefix naming the offending path,
+// so a non-canonicalizable document fails loudly instead of silently dropping
+// members (undefined), collapsing to {} (class instances, Map), or invoking
+// toJSON surprises (Date).
+
+function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function reject(path, detail) {
+  throw new TypeError(`JCS: ${detail} at ${path}`)
+}
+
+function serialize(value, path) {
+  if (value === null) return 'null'
+  const kind = typeof value
+  if (kind === 'boolean') return value ? 'true' : 'false'
+  if (kind === 'number') {
+    if (!Number.isFinite(value)) reject(path, `non-finite number ${String(value)} is not representable in JSON`)
+    return JSON.stringify(value)
+  }
+  if (kind === 'string') return JSON.stringify(value)
+  if (kind === 'undefined') reject(path, 'undefined is not representable in JSON')
+  if (kind === 'bigint') reject(path, 'BigInt is not representable in JSON')
+  if (kind === 'function') reject(path, 'function is not representable in JSON')
+  if (kind === 'symbol') reject(path, 'symbol is not representable in JSON')
+  if (Array.isArray(value)) {
+    // Holes must fail loudly: Array.prototype.map skips them, which would emit
+    // invalid JSON like "[,]" instead of a faithful canonicalization.
+    const items = []
+    for (let index = 0; index < value.length; index += 1) {
+      const itemPath = `${path}[${index}]`
+      if (!(index in value)) reject(itemPath, 'sparse array hole is not representable in JSON')
+      items.push(serialize(value[index], itemPath))
+    }
+    return `[${items.join(',')}]`
+  }
+  if (!isPlainObject(value)) {
+    reject(path, 'non-plain object (Date, Map, class instance, ...) cannot be canonicalized')
+  }
+  const keys = Object.keys(value).sort()
+  const members = keys.map((key) => {
+    const memberPath = `${path}.${key}`
+    if (value[key] === undefined) reject(memberPath, 'undefined property value is not representable in JSON')
+    return `${JSON.stringify(key)}:${serialize(value[key], memberPath)}`
+  })
+  return `{${members.join(',')}}`
+}
+
+// Canonicalize a JSON-compatible value into its RFC 8785 string form.
+export function canonicalize(value) {
+  return serialize(value, '$')
+}

package/src/attestation/sign.mjs

@@ -0,0 +1,305 @@
+// Attestation signing and verification reference implementation.
+//
+// The normative signing input (docs/attestation.md, "Signing procedure"):
+// the UTF-8 encoding of the RFC 8785 (JCS) canonicalization of the
+// attestation document with its `signature` member set to null.
+//
+// Key handling is JWK-only — never PEM. es256 signatures use the 64-byte
+// IEEE P1363 concatenation of r and s, not DER; the dsaEncoding flag below is
+// load-bearing for interop and is asserted by tests (64 bytes / 86 base64url
+// characters).
+//
+// Log-safety contract: every error and reason message in this module may name
+// keyId and algorithm, and must never include any JWK member value or the
+// signing input bytes.
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { canonicalize } from './jcs.mjs'
+
+// Re-exported so the package's "./attestation" export exposes the full
+// canonicalize -> payloadHashOf -> sign/verify surface from one entry point.
+export { canonicalize }
+
+const SCHEMA_PATH = fileURLToPath(new URL('../../contracts/atelier-attestation.v1.schema.json', import.meta.url))
+const SUPPORTED_ALGORITHMS = new Set(['ed25519', 'es256'])
+export const LOCAL_KEY_FILE = 'atelier-attestation-key.local.json'
+export const KEY_ENV_VAR = 'ATELIER_ATTESTATION_KEY_JSON'
+
+let cachedValidate = null
+
+function attestationValidator() {
+  if (!cachedValidate) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false })
+    addFormats(ajv)
+    cachedValidate = ajv.compile(JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8')))
+  }
+  return cachedValidate
+}
+
+function schemaErrors(doc) {
+  const validate = attestationValidator()
+  if (validate(doc)) return []
+  return (validate.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'failed schema validation'}`)
+}
+
+// Compute the canonical payload hash object for a payload document.
+export function payloadHashOf(document) {
+  const digest = crypto.createHash('sha256').update(Buffer.from(canonicalize(document), 'utf8')).digest('hex')
+  return { algorithm: 'sha-256', canonicalization: 'RFC8785-JCS', digest }
+}
+
+// The bytes a detached signature covers: the UTF-8 encoding of the RFC 8785
+// canonicalization of the document with its `signature` member set to null.
+// This is the shared normative rule — attestations and announcements both
+// sign exactly these bytes.
+export function signingInput(document) {
+  if (!document || typeof document !== 'object') {
+    throw new TypeError('signingInput requires an attestation object')
+  }
+  const unsigned = structuredClone(document)
+  unsigned.signature = null
+  return Buffer.from(canonicalize(unsigned), 'utf8')
+}
+
+function importPrivateKey(jwk) {
+  return crypto.createPrivateKey({ key: jwk, format: 'jwk' })
+}
+
+function importPublicKey(jwk) {
+  return crypto.createPublicKey({ key: jwk, format: 'jwk' })
+}
+
+function signBytes(algorithm, input, keyObject) {
+  if (algorithm === 'ed25519') return crypto.sign(null, input, keyObject)
+  if (algorithm === 'es256') return crypto.sign('sha256', input, { key: keyObject, dsaEncoding: 'ieee-p1363' })
+  throw new Error(`unsupported attestation signature algorithm: ${algorithm}`)
+}
+
+function verifyBytes(algorithm, input, keyObject, signatureBytes) {
+  if (algorithm === 'ed25519') return crypto.verify(null, input, keyObject, signatureBytes)
+  if (algorithm === 'es256') return crypto.verify('sha256', input, { key: keyObject, dsaEncoding: 'ieee-p1363' }, signatureBytes)
+  throw new Error(`unsupported attestation signature algorithm: ${algorithm}`)
+}
+
+function jwkMatchesAlgorithm(jwk, algorithm) {
+  if (!jwk || typeof jwk !== 'object') return false
+  if (algorithm === 'ed25519') return jwk.kty === 'OKP' && jwk.crv === 'Ed25519'
+  if (algorithm === 'es256') return jwk.kty === 'EC' && jwk.crv === 'P-256'
+  return false
+}
+
+// Generic detached-signature layer over any JSON document that carries a
+// `signature` member. No schema knowledge: callers layer their own document
+// validation (the attestation flow validates against its contract; the
+// announcements flow validates structurally in code). Signs the signingInput
+// bytes defined above. Never mutates the input document.
+// Attacker-controlled strings reach terminals through reason messages and
+// listing headers. A keyId carrying ANSI or newlines can erase the warning
+// line above it and print a convincing forgery in its place, so every such
+// value is capped and stripped of anything outside printable ASCII before it
+// is interpolated. Callers never see the raw value.
+export function safeLabel(value, max = 64) {
+  if (typeof value !== 'string') return '(none)'
+  const printable = Array.from(value, (ch) => (ch >= ' ' && ch <= '~' ? ch : '?')).join('')
+  if (printable.length === 0) return '(none)'
+  return printable.length > max ? `${printable.slice(0, max)}…` : printable
+}
+
+export function signDocument(doc, { privateKey, keyId, algorithm } = {}) {
+  if (!doc || typeof doc !== 'object') throw new TypeError('signDocument requires a document object')
+  if (!privateKey || typeof privateKey !== 'object') throw new TypeError('signDocument requires a private key JWK')
+  if (!keyId || typeof keyId !== 'string') throw new TypeError('signDocument requires a keyId')
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new Error(`unsupported attestation signature algorithm: ${algorithm}`)
+  }
+  if (!jwkMatchesAlgorithm(privateKey, algorithm)) {
+    throw new Error(`signing key ${keyId} privateKeyJwk does not match algorithm ${algorithm}`)
+  }
+  if (doc.signature !== null) {
+    throw new Error('document already carries a signature; refusing to re-sign. Set signature to null first if that is intended.')
+  }
+  const input = signingInput(doc)
+  const signatureBytes = signBytes(algorithm, input, importPrivateKey(privateKey))
+  const signed = structuredClone(doc)
+  signed.signature = { algorithm, keyId, value: signatureBytes.toString('base64url') }
+  return signed
+}
+
+// Generic verification for a signDocument-shaped signature. Never throws on
+// bad documents — returns { valid, reasons } with every applicable reason
+// collected. Throws only on programmer error. Reason messages may name keyId
+// and algorithm, never JWK member values or signing-input bytes.
+export function verifyDocument(doc, { publicKey } = {}) {
+  if (!doc || typeof doc !== 'object') throw new TypeError('verifyDocument requires a document object')
+  if (!publicKey || typeof publicKey !== 'object' || !publicKey.publicKeyJwk) {
+    throw new TypeError('verifyDocument requires a public key document with publicKeyJwk')
+  }
+  const reasons = []
+  const signature = doc.signature
+  if (!signature || typeof signature !== 'object') {
+    reasons.push({ code: 'signature.missing', message: 'signature is null; an unsigned document is non-authoritative and never verifies' })
+    return { valid: false, reasons }
+  }
+  if (signature.algorithm !== publicKey.algorithm || !jwkMatchesAlgorithm(publicKey.publicKeyJwk, signature.algorithm)) {
+    reasons.push({
+      code: 'signature.algorithm-mismatch',
+      message: `signature algorithm ${safeLabel(signature.algorithm, 32)} does not match public key algorithm ${safeLabel(publicKey.algorithm, 32)}`,
+    })
+  }
+  if (signature.keyId !== publicKey.keyId) {
+    reasons.push({
+      code: 'signature.key-id-mismatch',
+      message: `signature keyId ${safeLabel(signature.keyId)} does not match public key keyId ${safeLabel(publicKey.keyId)}`,
+    })
+  }
+  let cryptoValid = false
+  try {
+    const input = signingInput(doc)
+    const signatureBytes = Buffer.from(String(signature.value ?? ''), 'base64url')
+    cryptoValid = verifyBytes(signature.algorithm, input, importPublicKey(publicKey.publicKeyJwk), signatureBytes)
+  } catch {
+    cryptoValid = false
+  }
+  if (!cryptoValid) {
+    reasons.push({ code: 'signature.invalid', message: 'cryptographic verification failed over the canonical signing input' })
+  }
+  return { valid: reasons.length === 0, reasons }
+}
+
+// Generate a fresh signing key pair. Returns the private key document (shape
+// of the local key file) and the freely shareable public key document.
+export function generateKeyPair({ algorithm = 'ed25519', keyId } = {}) {
+  if (!keyId || typeof keyId !== 'string') throw new TypeError('generateKeyPair requires a keyId')
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new Error(`unsupported attestation signature algorithm: ${algorithm}`)
+  }
+  const pair = algorithm === 'ed25519'
+    ? crypto.generateKeyPairSync('ed25519')
+    : crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' })
+  return {
+    privateKeyDoc: { keyId, algorithm, privateKeyJwk: pair.privateKey.export({ format: 'jwk' }) },
+    publicKeyDoc: { keyId, algorithm, publicKeyJwk: pair.publicKey.export({ format: 'jwk' }) },
+  }
+}
+
+// Load the signing key with fail-closed precedence:
+// env JSON -> explicit key file path -> ./atelier-attestation-key.local.json.
+export function loadSigningKey({ keyPath = null, env = process.env, cwd = process.cwd() } = {}) {
+  let raw = null
+  let source = null
+  if (env[KEY_ENV_VAR]) {
+    raw = env[KEY_ENV_VAR]
+    source = `env ${KEY_ENV_VAR}`
+  } else if (keyPath) {
+    if (!fs.existsSync(keyPath)) throw new Error(`signing key file not found: ${keyPath}`)
+    raw = fs.readFileSync(keyPath, 'utf8')
+    source = keyPath
+  } else {
+    const localPath = path.join(cwd, LOCAL_KEY_FILE)
+    if (fs.existsSync(localPath)) {
+      raw = fs.readFileSync(localPath, 'utf8')
+      source = localPath
+    }
+  }
+  if (raw === null) {
+    throw new Error(
+      'no attestation signing key available. Provide one of: '
+      + `the ${KEY_ENV_VAR} environment variable (key file JSON), `
+      + '--key <file>, '
+      + `or ${LOCAL_KEY_FILE} in the current directory (gitignored).`,
+    )
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // Never echo the content: it may be (or contain) private key material.
+    throw new Error(`signing key from ${source} is not valid JSON`)
+  }
+  if (!parsed || typeof parsed !== 'object' || typeof parsed.keyId !== 'string' || !parsed.keyId) {
+    throw new Error(`signing key from ${source} is missing a keyId`)
+  }
+  if (!SUPPORTED_ALGORITHMS.has(parsed.algorithm)) {
+    throw new Error(`signing key ${parsed.keyId} has an unsupported algorithm`)
+  }
+  if (!jwkMatchesAlgorithm(parsed.privateKeyJwk, parsed.algorithm)) {
+    throw new Error(`signing key ${parsed.keyId} privateKeyJwk does not match algorithm ${parsed.algorithm}`)
+  }
+  return { keyId: parsed.keyId, algorithm: parsed.algorithm, privateKeyJwk: parsed.privateKeyJwk }
+}
+
+// Sign a schema-valid, unsigned attestation. Returns a new signed document;
+// never mutates the input. Refuses (throws) on schema-invalid input, an
+// already-signed document, or an issuer/key mismatch.
+export function signAttestation({ attestation, key } = {}) {
+  if (!attestation || typeof attestation !== 'object') throw new TypeError('signAttestation requires an attestation object')
+  if (!key || typeof key !== 'object' || !key.privateKeyJwk) throw new TypeError('signAttestation requires a signing key document')
+  if (!SUPPORTED_ALGORITHMS.has(key.algorithm)) {
+    throw new Error(`unsupported attestation signature algorithm: ${key.algorithm}`)
+  }
+  const errors = schemaErrors(attestation)
+  if (errors.length) {
+    throw new Error(`attestation is not schema-valid; refusing to sign:\n${errors.join('\n')}`)
+  }
+  if (attestation.issuer?.keyId && attestation.issuer.keyId !== key.keyId) {
+    throw new Error(`issuer.keyId ${attestation.issuer.keyId} does not match signing key ${key.keyId}; refusing to sign`)
+  }
+  return signDocument(attestation, { privateKey: key.privateKeyJwk, keyId: key.keyId, algorithm: key.algorithm })
+}
+
+// Verify an attestation signature against a public key document.
+// Never throws on bad documents — returns { valid, reasons } with every
+// applicable reason collected. Throws only on programmer error.
+export function verifyAttestation({ attestation, publicKey } = {}) {
+  if (!attestation || typeof attestation !== 'object') throw new TypeError('verifyAttestation requires an attestation object')
+  if (!publicKey || typeof publicKey !== 'object' || !publicKey.publicKeyJwk) {
+    throw new TypeError('verifyAttestation requires a public key document with publicKeyJwk')
+  }
+  const reasons = []
+  for (const message of schemaErrors(attestation)) {
+    reasons.push({ code: 'schema.invalid', message })
+  }
+  const signature = attestation.signature
+  if (signature && typeof signature === 'object' && attestation.issuer?.keyId && attestation.issuer.keyId !== signature.keyId) {
+    reasons.push({
+      code: 'issuer.key-id-mismatch',
+      message: `issuer.keyId ${attestation.issuer.keyId} does not match signature keyId ${signature.keyId}`,
+    })
+  }
+  reasons.push(...verifyDocument(attestation, { publicKey }).reasons)
+  return { valid: reasons.length === 0, reasons }
+}
+
+// Verify that an attestation is bound to a specific payload document.
+// Independent of signature validity so the two can be reported separately.
+export function verifyPayloadBinding({ attestation, payload } = {}) {
+  if (!attestation || typeof attestation !== 'object') throw new TypeError('verifyPayloadBinding requires an attestation object')
+  if (payload === undefined) throw new TypeError('verifyPayloadBinding requires a payload document')
+  const reasons = []
+  const subject = attestation.subject ?? {}
+  const payloadSchema = payload && typeof payload === 'object' ? payload.schema : undefined
+  if (typeof subject.schema === 'string' && payloadSchema !== subject.schema) {
+    reasons.push({
+      code: 'payload.schema-field-mismatch',
+      message: `payload schema field ${String(payloadSchema)} does not match subject.schema ${subject.schema}`,
+    })
+  }
+  let digest = null
+  try {
+    digest = payloadHashOf(payload).digest
+  } catch (error) {
+    reasons.push({ code: 'payload.digest-mismatch', message: `payload cannot be canonicalized: ${error.message}` })
+  }
+  if (digest !== null && digest !== subject.payloadHash?.digest) {
+    reasons.push({
+      code: 'payload.digest-mismatch',
+      message: 'recomputed payload digest does not match subject.payloadHash.digest',
+    })
+  }
+  return { valid: reasons.length === 0, reasons }
+}

package/src/boundary/content-rules.mjs

@@ -0,0 +1,262 @@
+import { spawnSync } from 'node:child_process'
+import { matchesPathPattern, normalizeRelPath } from '../project/path-match.mjs'
+
+export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904'
+export const ZERO_SHA_RE = /^0{40,}$/
+
+export const RULE_KINDS = Object.freeze(['content', 'path'])
+export const RULE_SEVERITIES = Object.freeze(['error', 'warning'])
+
+// A blanket exception is not an exception, it is switching the rule off. The
+// contract requires a rule, a repo, real paths, and a reason a reviewer can act on.
+const BLANKET_PATTERNS = new Set(['*', '**', '.', './', '**/*', '*/**'])
+const MIN_REASON_LENGTH = 8
+
+export const DEFAULT_CONTENT_RULES = Object.freeze(
+  [
+    {
+      id: 'secret-material',
+      kind: 'content',
+      severity: 'error',
+      pattern: '(-----BEGIN [A-Z ]*PRIVATE KEY-----|AKIA[0-9A-Z]{16}|ghp_[0-9A-Za-z]{36}|xox[baprs]-[0-9A-Za-z-]{10,})',
+      description: 'A credential or private key is being pushed.',
+    },
+    {
+      id: 'browser-persistence',
+      kind: 'content',
+      severity: 'error',
+      pattern: '(^|[^A-Za-z0-9_])(localStorage|sessionStorage|indexedDB|IndexedDB)([^A-Za-z0-9_]|$)|document[.]cookie|caches[.]open',
+      paths: ['*.html', '*.js', '*.mjs', '*.cjs', '*.jsx', '*.ts', '*.tsx'],
+      description: 'Artifact state must persist to Git-tracked repo files, not browser-only storage.',
+    },
+    {
+      id: 'private-financial-filename',
+      kind: 'path',
+      severity: 'error',
+      pattern: '(\\.env($|\\.)|invoice|payroll|(^|[-_/])salar(y|ies)|bank[-_]?statement|tax[-_]?return|credential|(^|[-_/])password([-_.]|$)|(^|[-_/])secret([-_.]|$)|id_rsa)',
+      description: 'Private or financial material does not belong in a source repo.',
+    },
+  ].map(Object.freeze),
+)
+
+const isObject = (value) => value && typeof value === 'object' && !Array.isArray(value)
+const trimmed = (value) => (typeof value === 'string' ? value.trim() : '')
+
+export function validateContentRules(rules, { label = 'contentRules' } = {}) {
+  const errors = []
+  if (!Array.isArray(rules)) return [`${label} must be an array`]
+  const seen = new Set()
+  for (const [index, rule] of rules.entries()) {
+    const at = `${label}[${index}]`
+    if (!isObject(rule)) {
+      errors.push(`${at} must be an object`)
+      continue
+    }
+    for (const key of Object.keys(rule)) {
+      if (!['id', 'kind', 'severity', 'pattern', 'paths', 'description'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
+    }
+    const id = trimmed(rule.id)
+    if (!id) errors.push(`${at}.id is required`)
+    else if (seen.has(id)) errors.push(`${at}.id duplicates an earlier rule: ${id}`)
+    else seen.add(id)
+    if (rule.kind != null && !RULE_KINDS.includes(rule.kind)) errors.push(`${at}.kind must be one of ${RULE_KINDS.join(', ')}`)
+    if (rule.severity != null && !RULE_SEVERITIES.includes(rule.severity)) errors.push(`${at}.severity must be one of ${RULE_SEVERITIES.join(', ')}`)
+    if (!trimmed(rule.pattern)) errors.push(`${at}.pattern is required`)
+    else {
+      try {
+        new RegExp(rule.pattern)
+      } catch (error) {
+        errors.push(`${at}.pattern is not a valid regular expression: ${error.message}`)
+      }
+    }
+    if (rule.paths != null && (!Array.isArray(rule.paths) || rule.paths.some((item) => !trimmed(item)))) {
+      errors.push(`${at}.paths must be a list of non-empty globs`)
+    }
+  }
+  return errors
+}
+
+export function validateContentRuleExceptions(exceptions, rules = DEFAULT_CONTENT_RULES, { label = 'contentRuleExceptions' } = {}) {
+  const errors = []
+  if (!Array.isArray(exceptions)) return [`${label} must be an array`]
+  const ruleIds = new Set(rules.map((rule) => trimmed(rule.id)).filter(Boolean))
+  for (const [index, exception] of exceptions.entries()) {
+    const at = `${label}[${index}]`
+    if (!isObject(exception)) {
+      errors.push(`${at} must be an object`)
+      continue
+    }
+    for (const key of Object.keys(exception)) {
+      if (!['rule', 'repo', 'paths', 'reason'].includes(key)) errors.push(`${at} must not include additional property ${key}`)
+    }
+    const rule = trimmed(exception.rule)
+    if (!rule) errors.push(`${at}.rule is required; an exception must name the rule it excepts`)
+    else if (ruleIds.size && !ruleIds.has(rule)) errors.push(`${at}.rule "${rule}" is not a declared content rule`)
+    if (!trimmed(exception.repo)) errors.push(`${at}.repo is required; exceptions are per repo, not fleet-wide`)
+    if (!Array.isArray(exception.paths) || !exception.paths.length) {
+      errors.push(`${at}.paths is required and must name the paths being excepted`)
+    } else {
+      for (const item of exception.paths) {
+        if (!trimmed(item)) errors.push(`${at}.paths must contain non-empty globs`)
+        else if (BLANKET_PATTERNS.has(normalizeRelPath(item))) {
+          errors.push(`${at}.paths must not be a blanket "${item}"; a repo-wide skip is disabling the rule, not excepting it`)
+        }
+      }
+    }
+    if (trimmed(exception.reason).length < MIN_REASON_LENGTH) {
+      errors.push(`${at}.reason is required and must explain why this usage is accepted`)
+    }
+  }
+  return errors
+}
+
+export function resolveContentRules(policy) {
+  const declared = Array.isArray(policy?.contentRules) ? policy.contentRules : null
+  return declared ?? DEFAULT_CONTENT_RULES
+}
+
+export function findException({ exceptions = [], rule, repo, path: filePath }) {
+  const rel = normalizeRelPath(filePath)
+  return (
+    exceptions.find(
+      (exception) =>
+        trimmed(exception.rule) === rule &&
+        trimmed(exception.repo) === repo &&
+        (Array.isArray(exception.paths) ? exception.paths : []).some((pattern) => matchesPathPattern(pattern, rel)),
+    ) ?? null
+  )
+}
+
+function rulePathMatches(rule, filePath) {
+  if (!Array.isArray(rule.paths) || !rule.paths.length) return true
+  return rule.paths.some((pattern) => matchesPathPattern(pattern, filePath))
+}
+
+/**
+ * Judge added lines and added file paths, not the whole tree.
+ *
+ * A whole-tree scan cannot tell "you are about to push a new violation" from
+ * "a known, accepted usage exists", so one legitimate use anywhere blocks every
+ * push of everything in that repo, forever.
+ */
+export function scanAddedContent({ files, rules = DEFAULT_CONTENT_RULES, exceptions = [], repo = null }) {
+  const findings = []
+  for (const file of files) {
+    const filePath = normalizeRelPath(file.path)
+    for (const rule of rules) {
+      const kind = rule.kind ?? 'content'
+      const severity = rule.severity ?? 'error'
+      const exception = findException({ exceptions, rule: rule.id, repo, path: filePath })
+      if (kind === 'path') {
+        if (!file.added || !new RegExp(rule.pattern, 'i').test(filePath)) continue
+        if (exception) continue
+        findings.push({ severity, code: 'content-rule-violation', rule: rule.id, repo, path: filePath, line: null, message: `${repo ?? ''}/${filePath}: ${rule.description ?? rule.id}`.replace(/^\//, '') })
+        continue
+      }
+      if (!rulePathMatches(rule, filePath)) continue
+      const re = new RegExp(rule.pattern)
+      for (const line of file.addedLines ?? []) {
+        if (!re.test(line.text)) continue
+        if (exception) continue
+        findings.push({
+          severity,
+          code: 'content-rule-violation',
+          rule: rule.id,
+          repo,
+          path: filePath,
+          line: line.number,
+          message: `${repo ?? ''}/${filePath}:${line.number}: ${rule.description ?? rule.id}`.replace(/^\//, ''),
+        })
+      }
+    }
+  }
+  return findings
+}
+
+/** Parse `git diff` output into added files and added lines with line numbers. */
+export function parseAddedContent(diff) {
+  const files = []
+  let current = null
+  let lineNumber = 0
+  for (const raw of String(diff ?? '').split('\n')) {
+    if (raw.startsWith('diff --git ')) {
+      const header = raw.match(/^diff --git a\/(.*) b\/(.*)$/)
+      current = { path: header ? normalizeRelPath(header[2]) : null, added: false, addedLines: [] }
+      files.push(current)
+      continue
+    }
+    if (!current) continue
+    if (raw.startsWith('new file mode ')) {
+      current.added = true
+      continue
+    }
+    const hunk = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (hunk) {
+      lineNumber = Number(hunk[1])
+      continue
+    }
+    if (/^\+(?!\+)/.test(raw)) {
+      current.addedLines.push({ number: lineNumber, text: raw.slice(1) })
+      lineNumber += 1
+    } else if (/^-(?!-)/.test(raw)) {
+      // removed lines do not advance the new-file line counter
+    } else if (raw.startsWith(' ')) {
+      lineNumber += 1
+    }
+  }
+  return files.filter((file) => file.path)
+}
+
+/** Ref updates arrive on the pre-push hook's stdin as `<localRef> <localSha> <remoteRef> <remoteSha>`. */
+export function parsePushRefUpdates(text) {
+  const updates = []
+  for (const raw of String(text ?? '').split('\n')) {
+    const parts = raw.trim().split(/\s+/).filter(Boolean)
+    if (parts.length < 4) continue
+    const [localRef, localSha, remoteRef, remoteSha] = parts
+    if (ZERO_SHA_RE.test(localSha)) continue // branch deletion pushes no content
+    updates.push({ localRef, localSha, remoteRef, remoteSha })
+  }
+  return updates
+}
+
+function gitOutput(repoRoot, args) {
+  const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  return result.status === 0 ? result.stdout : null
+}
+
+export function pushRangeBase(repoRoot, remoteSha) {
+  // A new branch has no remote counterpart, so everything it carries is new:
+  // diff against the empty tree rather than silently scanning nothing.
+  if (!remoteSha || ZERO_SHA_RE.test(remoteSha)) return EMPTY_TREE
+  return gitOutput(repoRoot, ['rev-parse', '--verify', '--quiet', `${remoteSha}^{commit}`]) ? remoteSha : EMPTY_TREE
+}
+
+export function diffForPushRange(repoRoot, { localSha, remoteSha }) {
+  const base = pushRangeBase(repoRoot, remoteSha)
+  return gitOutput(repoRoot, ['diff', '--unified=0', base, localSha]) ?? ''
+}
+
+export function stagedDiff(repoRoot) {
+  return gitOutput(repoRoot, ['diff', '--cached', '--unified=0']) ?? ''
+}
+
+/**
+ * Whole-tree scan for the non-blocking audit. This is the view that reports every
+ * accepted usage, so a repo can see what it has taken on without those findings
+ * stopping unrelated work from being pushed.
+ */
+export function scanTree(repoRoot, { rules = DEFAULT_CONTENT_RULES, exceptions = [], repo = null } = {}) {
+  const listed = gitOutput(repoRoot, ['ls-files', '-z']) ?? ''
+  const files = []
+  for (const rel of listed.split('\0').filter(Boolean)) {
+    const blob = gitOutput(repoRoot, ['show', `HEAD:${rel}`])
+    if (blob == null) continue
+    files.push({
+      path: rel,
+      added: true,
+      addedLines: blob.split('\n').map((text, index) => ({ number: index + 1, text })),
+    })
+  }
+  return scanAddedContent({ files, rules, exceptions, repo })
+}