code-foundry 1.18.0 → 1.20.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()
+}

package/src/lib/merge-queue.mjs

@@ -0,0 +1,271 @@
+// @ts-check
+import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const QUEUE_CALLER = '.github/workflows/validation-merge-queue.yml'
+export const QUEUE_MARKER = '# code-foundry-managed: merge-queue-v1\n'
+/** @param {unknown} value @param {string} message @returns {asserts value} */
+function ensure(value, message) {
+  if (!value) throw new Error(message)
+}
+
+/** @param {unknown} value */
+export function mergeQueueEnabled(value) {
+  if (value === undefined || value === '' || value === false || value === 'false') return false
+  if (value === true || value === 'true') return true
+  throw new Error('merge_queue must be true or false')
+}
+
+/** Same version-pin policy as normal sync: released semver pins advance while
+ * custom refs persist unless an explicit fleet runtime override is supplied.
+ * @param {string | undefined} current @param {string} sourceVersion @param {string | undefined} override
+ */
+export function queueRuntimeRef(current, sourceVersion, override) {
+  if (override !== undefined) return override
+  if (!current || current === 'auto' || /^v\d+\.\d+\.\d+$/.test(current)) return `v${sourceVersion}`
+  return current
+}
+
+/** @param {Record<string, string>} config @param {string} ref */
+export function renderMergeQueueCaller(config, ref) {
+  const repository = config.runtime_repository || '0xPlayerOne/code-foundry'
+  ensure(
+    /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) &&
+      !repository.split('/').some((part) => ['.', '..'].includes(part)),
+    'Invalid queue runtime repository'
+  )
+  ensure(
+    /^(?:[a-f0-9]{40}|v\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?)$/.test(ref),
+    'Merge queues require a released version or exact commit pin, not a moving branch'
+  )
+  const topology = config.git_workflow || 'direct'
+  ensure(['direct', 'staging-release'].includes(topology), 'Unsupported queue topology')
+  const features = (config.features || 'all').split(/[\s,]+/)
+  ensure(
+    features.some((feature) =>
+      ['all', 'validation', 'ci', 'test', 'security', 'codeql'].includes(feature)
+    ),
+    'Merge queues require the canonical PR validation caller'
+  )
+  const branches = topology === 'direct' ? ['main'] : ['main', 'staging']
+  const workflow = config.codeql === 'false' ? 'validation-no-codeql.yml' : 'validation.yml'
+  const runner = (/** @type {string} */ key, fallback = 'ubuntu-latest') => {
+    const value = config[key] || config.runner || fallback
+    ensure(/^[A-Za-z0-9_.-]+$/.test(value), `Unsupported queue runner label: ${key}`)
+    return JSON.stringify(value)
+  }
+  const threads = config.codeql_rust_threads || '1'
+  const parallel = config.codeql_rust_max_parallel || '1'
+  ensure(
+    /^(?:[1-9]|[1-5][0-9]|6[0-4])$/.test(threads),
+    'Unsupported codeql_rust_threads; use an integer from 1 to 64.'
+  )
+  ensure(
+    /^(?:[1-8])$/.test(parallel),
+    'Unsupported codeql_rust_max_parallel; use an integer from 1 to 8.'
+  )
+
+  const rawShards = config.codeql_rust_shards || '["all"]'
+  let shards
+  try {
+    shards = JSON.parse(rawShards)
+  } catch {
+    throw new Error('Invalid codeql_rust_shards; use a JSON array of relative Rust source paths.')
+  }
+  ensure(
+    Array.isArray(shards) && shards.length > 0 && shards.length <= 8,
+    'Invalid codeql_rust_shards; configure between 1 and 8 shards.'
+  )
+  const seen = new Set()
+  for (const shard of shards) {
+    ensure(
+      typeof shard === 'string' && shard.length > 0 && shard.length <= 512 && !seen.has(shard),
+      'Invalid codeql_rust_shards; shards must be unique non-empty strings.'
+    )
+    seen.add(shard)
+    if (shard === 'all') continue
+    for (const candidate of shard.split(',')) {
+      const path = candidate.trim()
+      ensure(
+        Boolean(path) &&
+          !path.startsWith('/') &&
+          !path.split('/').includes('..') &&
+          /^[A-Za-z0-9._/@+ -]+$/.test(path),
+        `Invalid Rust CodeQL shard path: ${path || '(empty)'}`
+      )
+    }
+  }
+  ensure(
+    !(seen.has('all') && shards.length !== 1),
+    'Invalid codeql_rust_shards; "all" cannot be combined with scoped shards.'
+  )
+  return `${QUEUE_MARKER}name: Merge Queue
+
+on:
+  merge_group:
+    types: [checks_requested]
+    branches: [${branches.join(', ')}]
+
+permissions:
+  actions: read
+  contents: read
+  packages: read
+  security-events: write
+
+concurrency:
+  group: code-foundry-merge-queue-\${{ github.repository }}-\${{ github.event.merge_group.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  identity:
+    name: Merge group identity
+    if: vars.CI_BILLING_PAUSED != 'true'
+    runs-on: ${runner('runner')}
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout trusted identity verifier
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          repository: ${JSON.stringify(repository)}
+          ref: ${JSON.stringify(ref)}
+          path: .github/.code-foundry
+          sparse-checkout: src/lib
+      - name: Verify the exact merge-group commit
+        env:
+          FOUNDRY_QUEUE_BRANCHES: '${JSON.stringify(branches)}'
+        run: node .github/.code-foundry/src/lib/merge-queue.mjs
+
+  validation:
+    name: Validation
+    needs: identity
+    if: vars.CI_BILLING_PAUSED != 'true'
+    uses: ${repository}/.github/workflows/${workflow}@${ref}
+    with:
+      mode: audit
+      runtime-repository: ${JSON.stringify(repository)}
+      runtime-ref: ${JSON.stringify(ref)}
+      ci-runner: ${runner('ci_runner')}
+      test-runner: ${runner('test_runner')}
+      unit-runner: ${runner('unit_runner', 'ubuntu-slim')}
+      performance-runner: ${runner('performance_runner')}
+      security-runner: ${runner('security_runner', 'ubuntu-slim')}
+      codeql-runner: ${runner('codeql_runner')}
+      rust-shards: '${JSON.stringify(shards)}'
+      rust-threads: '${threads}'
+      rust-max-parallel: ${parallel}
+`
+}
+
+/** @param {Record<string, any>} payload @param {Record<string, string | undefined>} environment @param {unknown} branches */
+export function validateMergeGroup(payload, environment, branches) {
+  ensure(
+    Array.isArray(branches) &&
+      branches.length > 0 &&
+      branches.every((branch) => ['main', 'staging'].includes(branch)) &&
+      new Set(branches).size === branches.length,
+    'Invalid allowed merge-queue branches'
+  )
+  ensure(
+    environment.GITHUB_EVENT_NAME === 'merge_group' && payload.action === 'checks_requested',
+    'Only merge_group checks_requested is accepted'
+  )
+  const group = payload.merge_group
+  ensure(
+    group &&
+      /^[a-f0-9]{40}$/.test(group.head_sha ?? '') &&
+      /^[a-f0-9]{40}$/.test(group.base_sha ?? ''),
+    'Merge-group SHA identity is incomplete'
+  )
+  ensure(
+    branches.some((branch) => group.base_ref === `refs/heads/${branch}`),
+    'Merge-group base branch is not enabled'
+  )
+  const branch = group.base_ref.slice('refs/heads/'.length)
+  ensure(
+    typeof group.head_ref === 'string' &&
+      group.head_ref.startsWith(`refs/heads/gh-readonly-queue/${branch}/`) &&
+      group.head_ref.length > `refs/heads/gh-readonly-queue/${branch}/`.length,
+    'Unexpected merge-group ref'
+  )
+  ensure(
+    environment.GITHUB_SHA === group.head_sha && environment.GITHUB_REF === group.head_ref,
+    'Workflow commit/ref differs from the merge group'
+  )
+  ensure(
+    typeof environment.GITHUB_REPOSITORY === 'string' &&
+      environment.GITHUB_REPOSITORY === payload.repository?.full_name,
+    'Merge-group repository identity mismatch'
+  )
+  return {
+    mode: 'audit',
+    head_sha: group.head_sha,
+    base_sha: group.base_sha,
+    base_ref: group.base_ref,
+  }
+}
+
+/** Refuse symlinked workflow paths and preserve unowned files, even with force.
+ * @param {string} root @param {string | null} content
+ */
+export function inspectQueueCaller(root, content) {
+  let current = resolve(root)
+  for (const part of QUEUE_CALLER.split('/')) {
+    current = join(current, part)
+    let entry
+    try {
+      entry = lstatSync(current)
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error
+    }
+    ensure(!entry?.isSymbolicLink(), 'Merge-queue workflow paths must not contain symlinks')
+  }
+  let existing = null
+  try {
+    existing = readFileSync(current, 'utf8')
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error
+  }
+  if (existing !== null && !existing.startsWith(QUEUE_MARKER)) {
+    ensure(
+      content === null,
+      'A repository-owned merge-queue caller already exists; refusing to overwrite it'
+    )
+    return { path: current, changed: false }
+  }
+  return { path: current, changed: existing !== content }
+}
+
+/** @param {string} root @param {string | null} content @param {boolean} [dryRun] */
+export function syncQueueCaller(root, content, dryRun = false) {
+  const plan = inspectQueueCaller(root, content)
+  if (!plan.changed) return []
+  if (dryRun) console.log(`Would ${content === null ? 'remove' : 'sync'} ${QUEUE_CALLER}`)
+  else if (content === null) rmSync(plan.path, { force: true })
+  else {
+    mkdirSync(dirname(plan.path), { recursive: true })
+    writeFileSync(plan.path, content)
+  }
+  return [QUEUE_CALLER]
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    ensure(process.env.GITHUB_EVENT_PATH, 'Missing GitHub event payload')
+    console.log(
+      JSON.stringify(
+        validateMergeGroup(
+          JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')),
+          process.env,
+          JSON.parse(process.env.FOUNDRY_QUEUE_BRANCHES || '[]')
+        )
+      )
+    )
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}