code-foundry 1.17.0 → 1.19.0

package/src/commands/qualified-publication.mjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+// @ts-check
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import {
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { tmpdir } from 'node:os'
+
+export const REQUIRED_NODES = ['20', '22', '24']
+export const REQUIRED_FIXTURES = [
+  'npm-direct',
+  'pnpm-direct',
+  'yarn-staging',
+  'bun-mise',
+  'nested-rust',
+  'nested-python',
+]
+/** @typedef {{ repository: string, tag: string, sourceSha: string, asset: string, directory: string }} Candidate */
+/** @typedef {(command:string, args:string[], cwd?:string) => string} Run */
+/** @param {unknown} condition @param {string} message @returns {asserts condition} */
+function ensure(condition, message) {
+  if (!condition) throw new Error(message)
+}
+/** @type {Run} */
+export function runCommand(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: 180_000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, GH_HOST: 'github.com', GH_PROMPT_DISABLED: '1' },
+  })
+  ensure(
+    !result.error && result.status === 0,
+    `${command} failed (${result.status ?? result.error?.message}); publication remains blocked`
+  )
+  return result.stdout
+}
+/** @param {Candidate} candidate */
+export function validateCandidate(candidate) {
+  ensure(
+    /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(candidate.repository) &&
+      !candidate.repository.split('/').some((part) => ['.', '..'].includes(part)),
+    'Expected an owner/repository'
+  )
+  ensure(
+    /^v\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(candidate.tag),
+    'Expected an explicit version tag'
+  )
+  ensure(/^[a-f0-9]{40}$/.test(candidate.sourceSha), 'Expected an exact source SHA')
+  ensure(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/.test(candidate.asset),
+    'Expected one exact tarball asset name'
+  )
+}
+/** @param {string} file */
+export function sha256(file) {
+  ensure(
+    lstatSync(file).isFile() && !lstatSync(file).isSymbolicLink(),
+    'Expected a regular non-symlink file'
+  )
+  const bytes = readFileSync(file)
+  ensure(bytes.length > 0, 'Empty artifact or report')
+  return createHash('sha256').update(bytes).digest('hex')
+}
+/** Pure policy check. Only reports from this workflow run are accepted by the caller.
+ * @param {unknown[]} reports @param {string} sourceSha @param {string} artifactSha256
+ */
+export function validateQualificationReports(reports, sourceSha, artifactSha256) {
+  ensure(
+    reports.length === REQUIRED_NODES.length,
+    'Every required Node qualification report is mandatory'
+  )
+  const seen = new Set()
+  for (const value of reports) {
+    const report = /** @type {Record<string, any>} */ (value)
+    ensure(
+      report?.schema_version === 1 && report.complete === true && report.actionlint === true,
+      'Incomplete or unlinted qualification report'
+    )
+    ensure(
+      report.source_sha === sourceSha && report.artifact_sha256 === artifactSha256,
+      'Qualification source or archive identity mismatch'
+    )
+    const node = /^v(\d+)\.\d+\.\d+$/.exec(report.node ?? '')?.[1]
+    ensure(
+      node && REQUIRED_NODES.includes(node) && !seen.has(node),
+      'Unexpected or duplicate Node qualification'
+    )
+    seen.add(node)
+    ensure(
+      Array.isArray(report.fixtures) && report.fixtures.length === REQUIRED_FIXTURES.length,
+      'Incomplete consumer fixture matrix'
+    )
+    for (const fixture of REQUIRED_FIXTURES)
+      ensure(
+        report.fixtures.filter(
+          (/** @type {Record<string,any>} */ entry) =>
+            entry.name === fixture && entry.status === 'passed'
+        ).length === 1,
+        `Missing successful fixture: ${fixture}`
+      )
+  }
+  return {
+    nodes: REQUIRED_NODES.filter((node) => seen.has(node)),
+    fixtures: [...REQUIRED_FIXTURES],
+  }
+}
+/** @param {Candidate} candidate */
+async function verifier(candidate) {
+  // Supplied by the separately reviewed release-integrity feature (#537).
+  const { verifyRelease } = await import('./release-integrity.mjs')
+  return verifyRelease({
+    repository: candidate.repository,
+    tag: candidate.tag,
+    expectedSha: candidate.sourceSha,
+    root: candidate.directory,
+    assets: [candidate.asset],
+  })
+}
+/** @typedef {(candidate:Candidate) => Promise<any>} Verify */
+/** @param {Candidate} candidate @param {{run?:Run, verify?:Verify}} [adapters] */
+export async function downloadVerifiedArchive(candidate, adapters = {}) {
+  validateCandidate(candidate)
+  const run = adapters.run ?? runCommand
+  const verify = adapters.verify ?? verifier
+  mkdirSync(candidate.directory, { recursive: true })
+  ensure(
+    lstatSync(candidate.directory).isDirectory() &&
+      !lstatSync(candidate.directory).isSymbolicLink(),
+    'Download directory must be a real directory'
+  )
+  ensure(readdirSync(candidate.directory).length === 0, 'Use a fresh empty download directory')
+  run('gh', [
+    'release',
+    'download',
+    candidate.tag,
+    '--repo',
+    candidate.repository,
+    '--pattern',
+    candidate.asset,
+    '--dir',
+    candidate.directory,
+  ])
+  ensure(
+    readdirSync(candidate.directory).length === 1 &&
+      readdirSync(candidate.directory)[0] === candidate.asset,
+    'Unexpected downloaded release files'
+  )
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  const digest = sha256(file)
+  const identity = await verify(candidate)
+  ensure(
+    identity.status === 'passed' &&
+      identity.immutable === true &&
+      identity.sourceSha === candidate.sourceSha,
+    'Release verification did not establish candidate identity'
+  )
+  ensure(
+    identity.assets?.length === 1 && identity.assets[0].digest === `sha256:${digest}`,
+    'Verified release asset differs from downloaded bytes'
+  )
+  ensure(sha256(file) === digest, 'Archive changed during verification')
+  return { file, digest, identity }
+}
+/** @param {Candidate} candidate @param {string[]} reportPaths @param {Run} [run] */
+export function qualifyArchive(candidate, reportPaths, run = runCommand) {
+  validateCandidate(candidate)
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  const digest = sha256(file)
+  const reports = reportPaths.map((path) => {
+    sha256(path)
+    return JSON.parse(readFileSync(path, 'utf8'))
+  })
+  const qualification = validateQualificationReports(reports, candidate.sourceSha, digest)
+  // Read one manifest without extracting archive paths into the workspace.
+  const manifest = JSON.parse(run('tar', ['-xOf', file, 'package/package.json']))
+  ensure(
+    manifest.name === 'code-foundry' && manifest.version === candidate.tag.slice(1),
+    'Archive package identity does not match this Code Foundry release'
+  )
+  return {
+    schemaVersion: 1,
+    kind: 'code-foundry-publication-eligibility',
+    repository: candidate.repository,
+    tag: candidate.tag,
+    sourceSha: candidate.sourceSha,
+    asset: candidate.asset,
+    digest: `sha256:${digest}`,
+    qualification,
+  }
+}
+/** @param {Candidate} candidate @param {string[]} reports @param {{run?:Run, verify?:Verify}} [adapters] */
+export async function publishQualifiedArchive(candidate, reports, adapters = {}) {
+  const run = adapters.run ?? runCommand
+  const before = qualifyArchive(candidate, reports, run)
+  const identity = await (adapters.verify ?? verifier)(candidate)
+  ensure(
+    identity.status === 'passed' &&
+      identity.immutable === true &&
+      identity.sourceSha === before.sourceSha &&
+      identity.assets?.length === 1 &&
+      identity.assets[0].digest === before.digest,
+    'Current release verification does not match qualified bytes'
+  )
+  const file = join(realpathSync(candidate.directory), candidate.asset)
+  ensure(`sha256:${sha256(file)}` === before.digest, 'Qualified archive changed before publication')
+  // Never publish a directory, rebuild, or invoke package lifecycle hooks here.
+  run(
+    'npm',
+    ['publish', file, '--ignore-scripts', '--provenance', '--access', 'public'],
+    candidate.directory
+  )
+  ensure(`sha256:${sha256(file)}` === before.digest, 'Archive changed during publication')
+  return { ...before, status: 'published' }
+}
+
+/** Stage only a previously-created draft: never move tags, overwrite assets, or
+ * treat an API/permissions failure as an absent release. Authentication needs
+ * immutable-settings read and release write; no setting is mutated.
+ * @param {Candidate} candidate @param {string[]} reports @param {{run?:Run, verify?:Verify}} [adapters]
+ */
+export async function stageQualifiedRelease(candidate, reports, adapters = {}) {
+  const run = adapters.run ?? runCommand
+  const qualification = qualifyArchive(candidate, reports, run)
+  const api = (/** @type {string} */ endpoint) =>
+    JSON.parse(run('gh', ['api', '--hostname', 'github.com', endpoint]))
+  const prefix = `repos/${candidate.repository}`
+  ensure(
+    api(`${prefix}/immutable-releases`).enabled === true,
+    'Release immutability is not confirmed enabled; no release write performed'
+  )
+  const checkTag = () => {
+    let object = api(`${prefix}/git/ref/tags/${encodeURIComponent(candidate.tag)}`).object
+    for (let depth = 0; object?.type === 'tag' && depth < 8; depth++) {
+      ensure(/^[a-f0-9]{40}$/.test(object.sha ?? ''), 'Invalid annotated tag')
+      object = api(`${prefix}/git/tags/${object.sha}`).object
+    }
+    ensure(
+      object?.type === 'commit' && object.sha === candidate.sourceSha,
+      'Release tag does not identify the qualified commit'
+    )
+  }
+  checkTag()
+  const endpoint = `${prefix}/releases/tags/${encodeURIComponent(candidate.tag)}`
+  const release = api(endpoint)
+  ensure(
+    Number.isSafeInteger(release.id) &&
+      release.draft === true &&
+      release.tag_name === candidate.tag &&
+      Array.isArray(release.assets),
+    'An existing draft release with the exact tag is required'
+  )
+  const temporary = mkdtempSync(join(tmpdir(), 'foundry-release-receipt-'))
+  try {
+    const receipt = join(temporary, 'qualification.json')
+    writeFileSync(receipt, JSON.stringify(qualification, null, 2) + '\n')
+    const files = [join(realpathSync(candidate.directory), candidate.asset), receipt]
+    const expected = [qualification.digest, `sha256:${sha256(receipt)}`]
+    const names = [candidate.asset, 'qualification.json']
+    for (let index = 0; index < files.length; index++) {
+      const existing = release.assets.filter(
+        (/** @type {Record<string, any>} */ asset) => asset.name === names[index]
+      )
+      ensure(existing.length <= 1, 'Ambiguous existing release asset')
+      if (existing.length)
+        ensure(
+          existing[0].state === 'uploaded' && existing[0].digest === expected[index],
+          'Existing draft asset differs; refusing to overwrite it'
+        )
+      else
+        run('gh', [
+          'release',
+          'upload',
+          candidate.tag,
+          files[index],
+          '--repo',
+          candidate.repository,
+        ])
+    }
+    const uploaded = api(endpoint)
+    ensure(
+      uploaded.id === release.id && uploaded.draft === true && uploaded.tag_name === candidate.tag,
+      'Draft changed during staging'
+    )
+    for (let index = 0; index < names.length; index++) {
+      const assets =
+        uploaded.assets?.filter(
+          (/** @type {Record<string, any>} */ asset) => asset.name === names[index]
+        ) ?? []
+      ensure(
+        assets.length === 1 &&
+          assets[0].state === 'uploaded' &&
+          assets[0].digest === expected[index],
+        'Uploaded release asset digest mismatch'
+      )
+      ensure(
+        `sha256:${sha256(files[index])}` === expected[index],
+        'Local asset changed during staging'
+      )
+    }
+    checkTag()
+    run('gh', [
+      'release',
+      'edit',
+      candidate.tag,
+      '--draft=false',
+      '--verify-tag',
+      '--repo',
+      candidate.repository,
+    ])
+    const identity = await (adapters.verify ?? verifier)(candidate)
+    ensure(
+      identity.status === 'passed' &&
+        identity.immutable === true &&
+        identity.sourceSha === qualification.sourceSha &&
+        identity.assets?.length === 1 &&
+        identity.assets[0].digest === qualification.digest,
+      'Published release verification failed; npm remains blocked'
+    )
+    return { ...qualification, status: 'release-published-and-verified' }
+  } finally {
+    rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    const [command, repository, tag, sourceSha, asset, directory, ...reports] =
+      process.argv.slice(2)
+    if (!directory || !['download', 'qualify', 'stage', 'publish'].includes(command))
+      throw new Error(
+        'Usage: qualified-publication.mjs download|qualify|stage|publish REPO TAG SOURCE_SHA ASSET DIRECTORY [REPORT.json ...]'
+      )
+    const candidate = { repository, tag, sourceSha, asset, directory: resolve(directory) }
+    if (command === 'download' && reports.length)
+      throw new Error('download does not take report paths')
+    const result =
+      command === 'download'
+        ? await downloadVerifiedArchive(candidate)
+        : command === 'qualify'
+          ? qualifyArchive(candidate, reports)
+          : command === 'stage'
+            ? await stageQualifiedRelease(candidate, reports)
+            : await publishQualifiedArchive(candidate, reports)
+    console.log(JSON.stringify(result, null, 2))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

package/src/lib/fleet-eligibility.mjs

@@ -0,0 +1,245 @@
+// @ts-check
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const RELEASE_POLICY_FILE = '.code-foundry-release-policy.json'
+/** @typedef {(command:string, args:string[]) => string} Run */
+/** @param {unknown} condition @param {string} message @returns {asserts condition} */
+function ensure(condition, message) {
+  if (!condition) throw new Error(message)
+}
+/** @type {Run} */
+function runCommand(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    timeout: 120_000,
+    maxBuffer: 16 * 1024 * 1024,
+    env: { ...process.env, GH_HOST: 'github.com', GH_PROMPT_DISABLED: '1' },
+  })
+  ensure(
+    !result.error && result.status === 0,
+    `Fleet eligibility is unverified: ${command} failed (${result.status ?? result.error?.message})`
+  )
+  return result.stdout.trim()
+}
+/** @param {Buffer} bytes */
+function hash(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+/** @param {unknown} value */
+export function validateReleasePolicy(value) {
+  const policy = /** @type {Record<string, any>} */ (value)
+  ensure(policy?.schema_version === 1, 'Expected a version-1 release policy')
+  ensure(
+    typeof policy.repository === 'string' &&
+      /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(policy.repository) &&
+      !policy.repository
+        .split('/')
+        .some((/** @type {string} */ part) => ['.', '..'].includes(part)),
+    'Invalid release-policy repository'
+  )
+  ensure(
+    typeof policy.workflow === 'string' &&
+      /^\.github\/workflows\/[A-Za-z0-9_-]+\.ya?ml$/.test(policy.workflow),
+    'Expected an exact qualification workflow path'
+  )
+  ensure(
+    policy.branch === 'main' || policy.branch === 'staging',
+    'Select a protected main or staging qualification branch'
+  )
+  ensure(
+    Array.isArray(policy.required_jobs) &&
+      policy.required_jobs.length > 0 &&
+      policy.required_jobs.every(
+        (/** @type {unknown} */ job) =>
+          typeof job === 'string' && job.trim() === job && job.length > 0
+      ) &&
+      new Set(policy.required_jobs).size === policy.required_jobs.length,
+    'Expected unique nonempty required qualification job names'
+  )
+  return policy
+}
+/** @param {unknown} value @param {string} property */
+function pages(value, property) {
+  ensure(Array.isArray(value) && value.length > 0, 'Missing paginated qualification evidence')
+  /** @type {Record<string, any>[]} */
+  const items = []
+  let expected = 0
+  for (const page of value) {
+    ensure(
+      Number.isInteger(page.total_count) && page.total_count >= 0 && Array.isArray(page[property]),
+      'Malformed paginated qualification evidence'
+    )
+    expected = Math.max(expected, page.total_count)
+    items.push(...page[property])
+  }
+  ensure(items.length >= expected, 'Incomplete qualification evidence pagination')
+  return items
+}
+/** @param {string} root @param {string} source @param {string} version @param {Run} [run] */
+export function assertFleetEligibility(root, source, version, run = runCommand) {
+  const path = join(root, RELEASE_POLICY_FILE)
+  let entry
+  try {
+    entry = lstatSync(path)
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return null
+    throw error
+  }
+  ensure(
+    entry.isFile() && !entry.isSymbolicLink(),
+    'Release policy must be a regular non-symlink file'
+  )
+  const bytes = readFileSync(path)
+  const policy = validateReleasePolicy(JSON.parse(bytes.toString('utf8')))
+  ensure(
+    /^v\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(version),
+    'Qualified upgrades require an explicit version tag'
+  )
+  const git = (/** @type {string[]} */ args) => run('git', ['-C', source, ...args]).trim()
+  const sourceSha = git(['rev-parse', 'HEAD'])
+  ensure(
+    /^[a-f0-9]{40}$/.test(sourceSha),
+    'Qualified upgrades require a source Git checkout with an exact commit'
+  )
+  ensure(
+    git(['status', '--porcelain', '--untracked-files=all']) === '',
+    'Qualification cannot authorize a dirty runtime source'
+  )
+  // Execute the installed/trusted verifier, never code from the proposed source checkout.
+  const verifier = fileURLToPath(new URL('../commands/release-integrity.mjs', import.meta.url))
+  const verified = JSON.parse(
+    run(process.execPath, [
+      verifier,
+      'release',
+      '--repo',
+      policy.repository,
+      '--tag',
+      version,
+      '--expected-sha',
+      sourceSha,
+    ])
+  )
+  ensure(
+    verified.status === 'passed' &&
+      verified.check === 'release-attestation' &&
+      verified.immutable === true &&
+      verified.repository === policy.repository &&
+      verified.tag === version &&
+      verified.sourceSha === sourceSha,
+    'Release identity was not cryptographically verified'
+  )
+  const api = (/** @type {string} */ endpoint, paginate = false) =>
+    JSON.parse(
+      run('gh', [
+        'api',
+        '--hostname',
+        'github.com',
+        endpoint,
+        ...(paginate ? ['--paginate', '--slurp'] : []),
+      ])
+    )
+  const workflow = api(
+    `repos/${policy.repository}/actions/workflows/${encodeURIComponent(policy.workflow.split('/').at(-1))}`
+  )
+  ensure(
+    Number.isSafeInteger(workflow.id) &&
+      workflow.path === policy.workflow &&
+      workflow.state === 'active',
+    'Qualification workflow is missing, disabled, or has a different identity'
+  )
+  const runs = pages(
+    api(
+      `repos/${policy.repository}/actions/workflows/${workflow.id}/runs?head_sha=${sourceSha}&per_page=100`,
+      true
+    ),
+    'workflow_runs'
+  )
+    .filter(
+      (item) =>
+        ['push', 'workflow_dispatch'].includes(item.event) && item.head_branch === policy.branch
+    )
+    // oxlint-disable-next-line unicorn/no-array-sort
+    .sort((a, b) => b.run_number - a.run_number || b.run_attempt - a.run_attempt)
+  ensure(
+    runs.every(
+      (item) => Number.isSafeInteger(item.run_number) && Number.isSafeInteger(item.run_attempt)
+    ),
+    'Malformed qualification run ordering'
+  )
+  const current = runs[0]
+  ensure(
+    current &&
+      Number.isSafeInteger(current.id) &&
+      Number.isSafeInteger(current.run_attempt) &&
+      current.run_attempt > 0 &&
+      current.workflow_id === workflow.id &&
+      current.path === policy.workflow &&
+      current.head_sha === sourceSha &&
+      current.repository?.full_name === policy.repository &&
+      current.head_repository?.full_name === policy.repository,
+    'No trusted qualification run matches the exact source and workflow'
+  )
+  ensure(
+    current.status === 'completed' && current.conclusion === 'success',
+    'Latest matching qualification has not passed; older successes do not authorize rollout'
+  )
+  const jobs = pages(
+    api(
+      `repos/${policy.repository}/actions/runs/${current.id}/attempts/${current.run_attempt}/jobs?per_page=100`,
+      true
+    ),
+    'jobs'
+  )
+  for (const name of policy.required_jobs) {
+    const matches = jobs.filter((job) => job.name === name)
+    ensure(
+      matches.length === 1 &&
+        matches[0].status === 'completed' &&
+        matches[0].conclusion === 'success',
+      `Required qualification job did not pass: ${name}`
+    )
+  }
+  const latest = api(`repos/${policy.repository}/actions/runs/${current.id}`)
+  ensure(
+    latest.run_attempt === current.run_attempt &&
+      latest.head_sha === sourceSha &&
+      latest.status === 'completed' &&
+      latest.conclusion === 'success',
+    'Qualification run changed during verification'
+  )
+  ensure(
+    git(['rev-parse', 'HEAD']) === sourceSha &&
+      git(['status', '--porcelain', '--untracked-files=all']) === '',
+    'Runtime source changed during eligibility verification'
+  )
+  ensure(
+    !lstatSync(path).isSymbolicLink() && hash(readFileSync(path)) === hash(bytes),
+    'Release policy changed during verification'
+  )
+  return {
+    schema_version: 1,
+    kind: 'code-foundry-fleet-eligibility',
+    status: 'passed',
+    repository: policy.repository,
+    tag: version,
+    source_sha: sourceSha,
+    policy_sha256: hash(bytes),
+    workflow_id: workflow.id,
+    run_id: current.id,
+    run_attempt: current.run_attempt,
+    required_jobs: policy.required_jobs,
+  }
+}
+/** Every public upgrade path, including dry run, passes the same opt-in guard.
+ * @template T @param {string} root @param {string} source @param {string} version
+ * @param {() => T} operation @param {Run} [run]
+ */
+export function guardedFleetUpgrade(root, source, version, operation, run) {
+  const eligibility = assertFleetEligibility(root, source, version, run)
+  if (eligibility) console.error(JSON.stringify(eligibility))
+  return operation()
+}