@volter/twin-catalog 0.2.2

package/lib/publication.mjs

@@ -0,0 +1,166 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { admit, defaults, digest, loadIndex, read, requireThat, stable, submissionId, validateIndex, write } from './model.mjs';
+
+export function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  requireThat(r.status === 0, `git ${args[0]}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+export function submissions(root) {
+  return ['submissions', 'reassessments'].flatMap((kind) => {
+    const dir = join(root, kind);
+    return existsSync(dir) ? readdirSync(dir).filter((f) => /^[a-f0-9]{64}\.json$/.test(f)).sort().map((f) => {
+      const submission = read(join(dir, f));
+      requireThat(f === `${submissionId(submission)}.json`, 'submission name/identity mismatch');
+      const path = `${kind}/${f}`;
+      const commit = git(root, ['log', '--diff-filter=A', '--format=%H', '--', path]).split('\n')[0];
+      requireThat(/^[a-f0-9]{40}$/.test(commit), `${path} is not in the committed admission ledger`);
+      return { submission, path, reassessment: kind === 'reassessments', commit, at: git(root, ['show', '-s', '--format=%cI', commit]) };
+    }) : [];
+  });
+}
+export function builtIndex(root) {
+  const index = loadIndex(root);
+  // Recommendations may refer to admitted submissions not yet present in legacy vendors/.
+  const recommendations = index.recommendations, revocations = index.revocations;
+  index.recommendations = {}; index.revocations = [];
+  for (const item of submissions(root)) admit(index, item.submission, item.commit, item.at, item.reassessment);
+  index.recommendations = recommendations; index.revocations = revocations;
+  validateIndex(index);
+  return index;
+}
+export function build(root, out, evidence = {}) {
+  requireThat(!existsSync(out), 'build output must be a new directory');
+  const index = builtIndex(root);
+  const commit = git(root, ['rev-parse', 'HEAD']);
+  const version = `0.2.${git(root, ['rev-list', '--first-parent', '--count', 'HEAD'])}`;
+  const references = Object.fromEntries(Object.entries(evidence).map(([id, { envelope, ...receipt }]) => [id, receipt]));
+  const identity = digest({ evidence: references, sources: index.sources, vendors: index.vendors, recommendations: index.recommendations, revocations: index.revocations });
+  mkdirSync(out, { recursive: true });
+  write(join(out, 'sources.json'), index.sources);
+  write(join(out, 'recommendations.json'), index.recommendations);
+  write(join(out, 'revocations.json'), index.revocations);
+  for (const e of index.vendors) write(join(out, 'vendors', `${e.vendor}.json`), e);
+  const catalog = { schemaVersion: 1, sourceCommit: commit, digest: identity, versions: index.vendors.flatMap((e) => e.packages.flatMap((p) => p.versions.map((v) => ({ vendor: e.vendor, package: p.name, source: p.source, ...v, evidence: (v.submission ?? v.assessment) ? { submission: v.submission ?? v.assessment, admissionCommit: v.assessmentCommit ?? v.commit, ...(references[v.submission ?? v.assessment] ?? {}) } : null, assessed: Boolean(v.submission ?? v.assessment) })))) };
+  write(join(out, 'catalog.json'), catalog);
+  for (const [id, receipt] of Object.entries(evidence)) write(join(out, 'evidence', `${id}.json`), receipt.envelope);
+  const pkg = { ...read(join(root, 'package.json')), version, catalog: { sourceCommit: commit, digest: identity } };
+  delete pkg.devDependencies;
+  write(join(out, 'package.json'), pkg);
+  for (const path of ['bin', 'lib', 'runner', 'docs', 'README.md', 'policy.json', 'LICENSE']) if (existsSync(join(root, path))) cpSync(join(root, path), join(out, path), { recursive: true });
+  return { version, sourceCommit: commit, digest: identity, directory: out };
+}
+
+function authorizedMaintainer(pr, policy, mergerPermission) {
+  return Array.isArray(policy.reviewBypassUsers) && policy.reviewBypassUsers.includes(pr.merged_by?.login) &&
+    ['admin', 'maintain'].includes(mergerPermission);
+}
+function trustedAccountAuthor(pr, policy) {
+  return Array.isArray(policy.trustedAccounts) && policy.trustedAccounts.some((account) =>
+    Number.isSafeInteger(account?.id) && account.id > 0 && typeof account.login === 'string' &&
+    account.login.length > 0 && ['User', 'Bot'].includes(account.type) &&
+    account.id === pr.user.id && account.login === pr.user.login && account.type === pr.user.type);
+}
+export function trustedAccountAdmission(pr, policy, mergerPermission) {
+  return Boolean(trustedAccountAuthor(pr, policy) && authorizedMaintainer(pr, policy, mergerPermission));
+}
+
+export function internalAdmission(pr, source, policy, mergerPermission) {
+  const bot = pr.user.type === 'Bot' && (pr.user.login === 'github-actions[bot]' ||
+    (Array.isArray(policy.internalBotAuthors) && policy.internalBotAuthors.some((author) =>
+      Number.isSafeInteger(author?.id) && author.id > 0 && author.id === pr.user.id && author.login === pr.user.login)));
+  return Boolean(source && Array.isArray(policy.internalRepositories) && policy.internalRepositories.includes(source.repository) &&
+    authorizedMaintainer(pr, policy, mergerPermission) &&
+    pr.head.repo?.full_name === pr.base.repo?.full_name && pr.base.repo?.full_name &&
+    (bot || (pr.user.type !== 'Bot' && ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(pr.author_association))));
+}
+export function reviewSatisfied(pr, reviews, checks, internal = false) {
+  const latest = new Map();
+  for (const r of reviews) {
+    if (['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'].includes(r.state)) latest.set(r.user.login, r);
+  }
+  const decisions = [...latest.values()].filter((r) => r.commit_id === pr.head.sha);
+  return Boolean(pr.merged_at) && (internal || decisions.some((r) => r.state === 'APPROVED' && r.user.login !== pr.user.login && r.user.type !== 'Bot' && !r.user.login.endsWith('[bot]') && ['MEMBER', 'OWNER', 'COLLABORATOR'].includes(r.author_association))) && !decisions.some((r) => r.state === 'CHANGES_REQUESTED') && checks.some((c) => c.name === 'catalog/readiness' && c.head_sha === pr.head.sha && c.conclusion === 'success' && c.app?.slug === 'github-actions');
+}
+export async function verifyAdmission(root, github, policyClient = github) {
+  requireThat(git(root, ['status', '--porcelain']) === '', 'publication requires a clean committed catalog checkout');
+  const main = await github.call('git/ref/heads/main');
+  requireThat(main.object?.sha === git(root, ['rev-parse', 'HEAD']), 'publication must use current main; retry the latest source commit');
+  requireThat(/^\*\s+@/m.test(await github.content('.github/CODEOWNERS', main.object.sha)), 'catalog needs moderator CODEOWNERS over every path');
+  const owners = await github.call('codeowners/errors?ref=main');
+  requireThat(Array.isArray(owners.errors) && owners.errors.length === 0, 'catalog CODEOWNERS has invalid moderators');
+  const protection = await policyClient.call('branches/main/protection');
+  requireThat(protection.enforce_admins?.enabled && protection.required_status_checks?.strict && protection.required_status_checks.contexts.includes('catalog/readiness') && protection.required_pull_request_reviews?.dismiss_stale_reviews && protection.required_pull_request_reviews?.require_code_owner_reviews && protection.required_pull_request_reviews?.require_last_push_approval, 'publication requires active current-head readiness and CODEOWNERS branch protection');
+  const proofs = [];
+  const policy = read(join(root, 'policy.json'));
+  const sources = loadIndex(root).sources;
+  for (const item of submissions(root)) {
+    const pulls = await github.pages(`commits/${item.commit}/pulls`);
+    let accepted = false;
+    for (const p of pulls.filter((p) => p.merged_at && p.base.ref === 'main')) {
+      const pr = await github.call(`pulls/${p.number}`);
+      const files = await github.pages(`pulls/${p.number}/files`);
+      if (files.length !== 1 || files[0].status !== 'added' || files[0].filename !== item.path) continue;
+      const contents = JSON.parse(await github.content(files[0].filename, pr.head.sha));
+      if (stable(contents) !== stable(item.submission)) continue;
+      const reviews = await github.pages(`pulls/${p.number}/reviews`);
+      const checks = await github.call(`commits/${pr.head.sha}/check-runs?check_name=catalog%2Freadiness&filter=latest&per_page=100`);
+      const source = sources.find((s) => s.name === item.submission.source);
+      let permission;
+      if ((trustedAccountAuthor(pr, policy) || (Array.isArray(policy.internalRepositories) && policy.internalRepositories.includes(source?.repository))) &&
+        Array.isArray(policy.reviewBypassUsers) && policy.reviewBypassUsers.includes(pr.merged_by?.login)) {
+        permission = (await policyClient.call(`collaborators/${encodeURIComponent(pr.merged_by.login)}/permission`)).permission;
+      }
+      const trusted = trustedAccountAdmission(pr, policy, permission);
+      const internal = internalAdmission(pr, source, policy, permission);
+      if (reviewSatisfied(pr, reviews, checks.check_runs, trusted || internal)) {
+        const check = checks.check_runs.find((c) => c.name === 'catalog/readiness' && c.head_sha === pr.head.sha && c.conclusion === 'success' && c.app?.slug === 'github-actions');
+        const parts = (check.external_id ?? '').split(':');
+        requireThat([4, 6].includes(parts.length) && parts[0] === String(pr.number) && parts[1] === pr.head.sha && /^[a-f0-9]{40}$/.test(parts[2]) && /^[a-f0-9]{64}$/.test(parts[3]), 'readiness check has no bound evidence receipt');
+        let workflow;
+        if (parts.length === 6) {
+          requireThat(/^[1-9][0-9]*$/.test(parts[4]) && /^[1-9][0-9]*$/.test(parts[5]) && Number.isSafeInteger(Number(parts[4])) && Number.isSafeInteger(Number(parts[5])), 'readiness receipt has an invalid workflow run or attempt');
+          workflow = { run: Number(parts[4]), attempt: Number(parts[5]) };
+        }
+        proofs.push({ ...item, pullRequest: pr.number, head: pr.head.sha, base: parts[2], reportSha256: parts[3], ...(workflow ? { workflow } : {}), check, moderation: { mode: trusted ? 'trusted-account-merge' : internal ? 'internal-maintainer-merge' : 'human-review', mergedBy: pr.merged_by.login, ...(trusted ? { account: { id: pr.user.id, login: pr.user.login, type: pr.user.type } } : {}) } });
+        accepted = true; break;
+      }
+    }
+    requireThat(accepted, `${submissionId(item.submission)}: no reviewed current-head admission with successful readiness`);
+  }
+  return proofs;
+}
+
+// Ten minutes rounds up three times the observed delay; see docs/measurements/registry-confirmation.json.
+const confirmationWindowMs = 10 * 60_000;
+export async function publish(directory, registry, fetcher = fetch, execute = spawnSync, confirmation = {}) {
+  const pkg = read(join(directory, 'package.json'));
+  const url = `${registry.replace(/\/$/, '')}/${encodeURIComponent(pkg.name)}/${pkg.version}`;
+  const before = await fetcher(url, { redirect: 'error' });
+  if (before.ok) {
+    const existing = await before.json();
+    requireThat(stable(existing.catalog) === stable(pkg.catalog), 'published version conflicts with this source identity');
+    requireThat(existing.dist?.integrity, 'published version has no artifact integrity');
+    return { published: false, existing: true, package: pkg.name, version: pkg.version, integrity: existing.dist.integrity, ...pkg.catalog };
+  }
+  requireThat(before.status === 404, `registry lookup failed: HTTP ${before.status}`);
+  const { now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), windowMs = confirmationWindowMs, intervalMs = 15_000 } = confirmation;
+  requireThat(Number.isFinite(windowMs) && windowMs > 0 && Number.isFinite(intervalMs) && intervalMs > 0, 'invalid registry confirmation timing');
+  const result = execute('npm', ['publish', '--ignore-scripts', '--access', 'public', '--provenance', '--registry', registry], { cwd: directory, encoding: 'utf8' });
+  requireThat(result.status === 0, `index publication failed: ${result.stderr}`);
+  const deadline = now() + windowMs;
+  let response;
+  for (;;) {
+    response = await fetcher(url, { redirect: 'error' });
+    if (response.ok) break;
+    requireThat(response.status === 404, `registry confirmation failed: HTTP ${response.status}`);
+    const remaining = deadline - now();
+    requireThat(remaining > 0, 'npm accepted the upload but registry confirmation is still unavailable; upload is unverified, retry to verify');
+    await sleep(Math.min(intervalMs, remaining));
+  }
+  const published = await response.json();
+  requireThat(stable(published.catalog) === stable(pkg.catalog) && published.dist?.integrity, 'published registry identity differs');
+  return { published: true, package: pkg.name, version: pkg.version, integrity: published.dist.integrity, ...pkg.catalog };
+}

package/lib/register.mjs

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { read, requireThat, stable, validateSources, write } from './model.mjs';
+
+/** Prepare a separate registration PR's data. No GitHub or registry action. */
+export function register(sources, source, file) {
+  validateSources(sources);
+  validateSources([source]);
+  const existing = sources.find((s) => s.name === source.name);
+  requireThat(!existing || stable(existing) === stable(source), 'source name already has a different registration');
+  const next = existing ? sources : validateSources([...sources, source]);
+  if (existsSync(file)) {
+    const held = stable(read(file));
+    requireThat(held === stable(sources) || held === stable(next), 'registration output already has different content');
+  }
+  write(file, next);
+  return { file, source, alreadyRegistered: Boolean(existing),
+    next: 'Open a separate pull request changing only sources.json. No publication or PR was performed.' };
+}

package/lib/registry.mjs

@@ -0,0 +1,101 @@
+import { createHash, X509Certificate } from 'node:crypto';
+import { requireThat, packagePattern, versionPattern } from './model.mjs';
+
+export async function metadata(name, version, registry, fetcher = fetch, confirmation) {
+  requireThat(packagePattern.test(name) && versionPattern.test(version), 'registry lookup requires an exact scoped package version');
+  const base = new URL(registry);
+  requireThat(base.protocol === 'https:' && !base.username && !base.password, 'registry must be HTTPS without credentials');
+  const { now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), windowMs = 600_000, intervalMs = 15_000 } = confirmation ?? {};
+  // Publisher confirmation uses the observed registry propagation in docs/measurements/registry-confirmation.json.
+  requireThat(!confirmation || (Number.isFinite(windowMs) && windowMs > 0 && Number.isFinite(intervalMs) && intervalMs > 0), 'invalid registry confirmation timing');
+  const deadline = now() + windowMs;
+  let response;
+  for (;;) {
+    response = await fetcher(`${registry.replace(/\/$/, '')}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`, { redirect: 'error' });
+    if (response.ok || !confirmation || response.status !== 404) break;
+    const remaining = deadline - now();
+    requireThat(remaining > 0, 'published package is not yet visible; retry confirmation, never upload this version again');
+    await sleep(Math.min(intervalMs, remaining));
+  }
+  requireThat(response.ok, `registry metadata: HTTP ${response.status}`);
+  const doc = await response.json();
+  requireThat(doc.name === name && doc.version === version, 'registry returned a different package/version');
+  return doc;
+}
+/** Confirm the registry view npm install uses; visibility of /name/version alone is insufficient. */
+export async function installationMetadata(submission, registry, fetcher = fetch, confirmation = {}) {
+  const { package: name, version, integrity } = submission;
+  requireThat(packagePattern.test(name) && versionPattern.test(version), 'installation lookup requires an exact scoped package version');
+  requireThat(typeof integrity === 'string' && /^sha512-[A-Za-z0-9+/]{86}==$/.test(integrity), 'installation lookup requires artifact SHA-512 integrity');
+  const base = new URL(registry);
+  requireThat(base.protocol === 'https:' && !base.username && !base.password, 'registry must be HTTPS without credentials');
+  const { now = Date.now, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), windowMs = 600_000, intervalMs = 15_000 } = confirmation;
+  // Reuse the measured bound in docs/measurements/registry-confirmation.json; this is read-only propagation recovery.
+  requireThat(Number.isFinite(windowMs) && windowMs > 0 && Number.isFinite(intervalMs) && intervalMs > 0, 'invalid registry confirmation timing');
+  const deadline = now() + windowMs;
+  for (;;) {
+    const response = await fetcher(`${registry.replace(/\/$/, '')}/${encodeURIComponent(name)}`, {
+      redirect: 'error', headers: { accept: 'application/vnd.npm.install-v1+json' },
+    });
+    if (response.ok) {
+      const doc = await response.json();
+      requireThat(doc?.name === name && doc.versions && typeof doc.versions === 'object' && !Array.isArray(doc.versions), 'registry installation metadata has a different or malformed package identity');
+      if (Object.hasOwn(doc.versions, version)) {
+        const release = doc.versions[version];
+        requireThat(release?.name === name && release.version === version, 'registry installation metadata returned a different package/version');
+        requireThat(release.dist?.integrity === integrity, 'registry installation metadata has conflicting artifact integrity');
+        return release;
+      }
+    } else requireThat(response.status === 404, `registry installation metadata: HTTP ${response.status}`);
+    const remaining = deadline - now();
+    requireThat(remaining > 0, 'published package is not yet visible to npm install; retry confirmation, never upload this version again');
+    await sleep(Math.min(intervalMs, remaining));
+  }
+}
+export function registryURL(value, registry) {
+  const url = new URL(value);
+  requireThat(url.origin === new URL(registry).origin && !url.username && !url.password && !url.hash, 'artifact and attestation URLs must remain on the policy registry');
+  return url.href;
+}
+export const integrityOf = (bytes) => `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+export function verifyArtifact(bytes, submission, doc) {
+  requireThat(doc.dist?.integrity === submission.integrity && integrityOf(bytes) === submission.integrity, 'artifact integrity mismatch');
+}
+/** Called only after npm audit signatures has verified the installed artifact's attestations. */
+export function attestedIdentity(document, source, bytes) {
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  const sha512 = createHash('sha512').update(bytes).digest('hex');
+  const expected = `https://github.com/${source.repository}/.github/workflows/${source.workflow ?? 'release.yml'}@`;
+  const attestations = document.attestations ?? [];
+  for (const attestation of attestations) {
+    const bundle = attestation.bundle;
+    const material = bundle?.verificationMaterial;
+    const raw = material?.certificate?.rawBytes ?? material?.x509CertificateChain?.certificates?.[0]?.rawBytes;
+    if (!raw || !bundle?.dsseEnvelope?.payload) continue;
+    const cert = new X509Certificate(Buffer.from(raw, 'base64'));
+    const san = /URI:([^,]+)/.exec(cert.subjectAltName ?? '')?.[1];
+    const statement = JSON.parse(Buffer.from(bundle.dsseEnvelope.payload, 'base64').toString('utf8'));
+    if (!['https://slsa.dev/provenance/v1', 'https://slsa.dev/provenance/v0.2'].includes(statement.predicateType)) continue;
+    if (!san?.startsWith(expected) || !statement.subject?.some(({ digest: d }) => d && (d.sha512 === sha512 || d.sha256 === sha256) && (!d.sha512 || d.sha512 === sha512) && (!d.sha256 || d.sha256 === sha256))) continue;
+    const dependency = statement.predicate?.buildDefinition?.resolvedDependencies?.find((item) => item.uri?.startsWith(`git+https://github.com/${source.repository}@`));
+    const sourceCommit = dependency?.digest?.gitCommit;
+    return { signer: san, subjectSha256: sha256, subjectSha512: sha512, predicateType: statement.predicateType, ...(sourceCommit && /^[a-f0-9]{40}$/.test(sourceCommit) ? { sourceCommit } : {}), bundle };
+  }
+  throw new Error('verified attestation does not bind this tarball to the registered repository and workflow');
+}
+
+/** Verify the exact downloaded bundle, so its identity cannot be swapped after npm's audit. */
+export async function verifiedProvenance(document, source, bytes, verifier) {
+  const expected = `https://github.com/${source.repository}/.github/workflows/${source.workflow ?? 'release.yml'}@`;
+  const regex = `^${expected.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.+$`;
+  for (const attestation of document.attestations ?? []) {
+    if (!attestation.bundle?.dsseEnvelope?.payload) continue;
+    try {
+      // npm also supplies a publish receipt signed with its public key. Only repository provenance qualifies here.
+      const identity = attestedIdentity({ attestations: [attestation] }, source, bytes);
+      await verifier(attestation.bundle, undefined, { certificateIssuer: 'https://token.actions.githubusercontent.com', certificateIdentityURI: regex });
+      return identity;
+    } catch { /* another subject, signer, predicate or an invalid bundle cannot confer readiness */ }
+  }
+  throw new Error('no verified registered-workflow provenance for this artifact');
+}

package/lib/runner.mjs

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdtempSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { digest, write, requireThat } from './model.mjs';
+
+/** Own a credential-free container workspace; assessment and transport verification share its boundary. */
+export function withContainer(root, input, output, execute, { spawn = spawnSync } = {}) {
+  const id = `twin-catalog-${randomUUID()}`;
+  const runOwner = process.env.GITHUB_RUN_ID ? `${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT ?? 1}` : id;
+  const work = mkdtempSync(join(tmpdir(), 'twin-catalog-input-'));
+  // mkdtemp is 0700; the container's unprivileged uid must traverse this data-only input directory.
+  chmodSync(work, 0o755);
+  write(join(work, 'input.json'), input);
+  chmodSync(join(work, 'input.json'), 0o644);
+  const imageFile = join(work, 'image-id');
+  const logs = [];
+  const run = (args, allowFailure = false) => {
+    const r = spawn('docker', args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+    logs.push({ command: args[0], status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '', error: r.error?.message });
+    if (!allowFailure) requireThat(r.status === 0, `container ${args[0]} failed: ${r.error?.message ?? r.stderr}`);
+    return r;
+  };
+  let volume = false;
+  try {
+    const tools = input.policy.tools;
+    run(['build', '--iidfile', imageFile, '--build-arg', `NODE_IMAGE=${input.policy.nodeImage}`, '--build-arg', `BUN_VERSION=${input.policy.bun}`, '--build-arg', `STANDARD_VERSION=${tools['@volter/twin-standard']}`, '--build-arg', `CORE_VERSION=${tools['@volter/world-core']}`, '--build-arg', `RUNTIME_VERSION=${tools['@volter/world-runtime']}`, '--build-arg', `PLAYWRIGHT_VERSION=${tools.playwright}`, '-f', join(root, 'runner/Dockerfile'), root]);
+    const image = readFileSync(imageFile, 'utf8').trim();
+    requireThat(/^sha256:[a-f0-9]{64}$/.test(image), 'container image has no immutable identity');
+    run(['volume', 'create', '--label', `twin-catalog.owner=${id}`, '--label', `twin-catalog.run=${runOwner}`, id]); volume = true;
+    // Docker volumes start root-owned. Only this task's new volume is changed.
+    run(['run', '--rm', '--label', `twin-catalog.owner=${id}`, '--label', `twin-catalog.run=${runOwner}`, '--network', 'none', '--user', '0', '--entrypoint', 'chown', '-v', `${id}:/work`, image, '1000:1000', '/work']);
+    const common = ['run', '--rm', '--label', `twin-catalog.owner=${id}`, '--label', `twin-catalog.run=${runOwner}`, '--init', '--shm-size', '256m', '--read-only', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--tmpfs', '/tmp:rw,nosuid,nodev', '-e', 'HOME=/tmp/home', '-e', 'npm_config_cache=/tmp/npm-cache', '-v', `${id}:/work`, '-v', `${work}:/input:ro`];
+    return execute({ image, common, run, owner: id });
+  } finally {
+    const cleanup = volume ? run(['volume', 'rm', id], true) : null;
+    write(`${output}.logs.json`, logs);
+    // Retain input identity and diagnostics on failure; no other actor's resources are touched.
+    requireThat(!cleanup || cleanup.status === 0, `owned volume teardown could not be verified: ${id}`);
+  }
+}
+
+/** The host never imports a candidate. Docker supplies the enforced offline evaluation boundary. */
+export function evaluate(root, input, output, options = {}) {
+  requireThat(input.policy.requireProvenance === true, 'admission requires verified provenance');
+  let phase = 'container-setup';
+  let imageIdentity = null;
+  try {
+    return withContainer(root, input, output, ({ image, common, run, owner }) => {
+      imageIdentity = image;
+      phase = 'artifact-preparation';
+      run([...common, image, '/opt/catalog/runner/prepare.mjs']);
+      const prepared = JSON.parse(run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/prepared.json","utf8"))']).stdout);
+      requireThat(prepared.integrity === input.submission.integrity, 'prepared artifact identity changed');
+      const lock = run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/package-lock.json","utf8"))']).stdout;
+      requireThat(digest(lock) === prepared.dependencyLockSha256, 'dependency lock identity changed');
+      write(`${output}.lock.json`, JSON.parse(lock));
+      phase = 'offline-assessment';
+      const result = run([...common, '--network', 'none', '--entrypoint', 'bun', image, '/opt/catalog/node_modules/@volter/world-runtime/src/cli.ts', 'run', '/work/world.json', '--root', '/work', '--env-out', '/work/world.env', '--owner', owner, '--', 'bun', '/opt/catalog/runner/evaluate.mjs'], true);
+      const reportRead = run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/report.json","utf8"))'], true);
+      const report = reportRead.status === 0 ? JSON.parse(reportRead.stdout) : null;
+      requireThat(!report || (report.schemaVersion === 1 && report.package === input.submission.package && report.version === input.submission.version && report.integrity === input.submission.integrity), 'evaluator returned a mismatched report');
+      const envelope = { schemaVersion: 1, inputSha256: digest(input), input, image, prepared, dependencyLock: JSON.parse(lock), status: result.status === 0 && report?.ready === true ? 'ready' : 'changes-needed', report, evaluatedAt: new Date().toISOString() };
+      write(output, envelope);
+      return envelope;
+    }, options);
+  } catch (error) {
+    const envelope = { schemaVersion: 1, inputSha256: digest(input), input, image: imageIdentity, status: 'changes-needed', phase, error: String(error.message ?? error), report: null, evaluatedAt: new Date().toISOString() };
+    write(output, envelope);
+    return envelope;
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@volter/twin-catalog",
+  "version": "0.2.2",
+  "description": "The moderated twin distribution: approved versions and submission tooling for independent publishers.",
+  "type": "module",
+  "bin": {
+    "twin-catalog": "bin/twin-catalog.mjs"
+  },
+  "exports": {
+    "./browse": {
+      "types": "./lib/browse.d.mts",
+      "default": "./lib/browse.mjs"
+    },
+    "./*": "./*"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin-catalog-open.git"
+  },
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "sources.json",
+    "vendors",
+    "README.md",
+    "LICENSE",
+    "catalog.json",
+    "recommendations.json",
+    "revocations.json",
+    "policy.json",
+    "bin",
+    "lib",
+    "runner",
+    "docs",
+    "evidence"
+  ],
+  "catalog": {
+    "sourceCommit": "646cb5db50f24248f177e1fab1ccdeb681e7005b",
+    "digest": "1c1ad9dfb2fd6cba0923988b3a1f17c6da892efc3a5ec36f230a91c88a437ff6"
+  }
+}

package/policy.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "registry": "https://registry.npmjs.org",
+  "tools": {
+    "@volter/world-core": "3.0.59",
+    "@volter/world-runtime": "3.0.59",
+    "@volter/twin-standard": "1.0.51",
+    "playwright": "1.63.0"
+  },
+  "bun": "1.3.11",
+  "nodeImage": "node:24-bookworm-slim",
+  "requireProvenance": true,
+  "reviewBypassUsers": [
+    "yueranyuan"
+  ],
+  "internalBotAuthors": [
+    {
+      "id": 338186041,
+      "login": "volter-twin-catalog-publisher[bot]"
+    }
+  ],
+  "internalRepositories": [
+    "volter-ai/twin-packs-open"
+  ],
+  "trustedAccounts": [
+    {
+      "id": 2255943,
+      "login": "yueranyuan",
+      "type": "User"
+    },
+    {
+      "id": 253602084,
+      "login": "portable-one",
+      "type": "User"
+    }
+  ]
+}

package/recommendations.json

@@ -0,0 +1 @@
+{}

package/revocations.json

@@ -0,0 +1 @@
+[]

package/runner/Dockerfile

@@ -0,0 +1,20 @@
+ARG NODE_IMAGE=node:24-bookworm-slim
+FROM ${NODE_IMAGE}
+ARG BUN_VERSION=1.3.11
+ARG STANDARD_VERSION=1.0.37
+ARG CORE_VERSION=3.0.45
+ARG RUNTIME_VERSION=3.0.45
+ARG PLAYWRIGHT_VERSION=1.63.0
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright
+RUN apt-get update && apt-get install -y --no-install-recommends git openssl ca-certificates libfaketime && rm -rf /var/lib/apt/lists/*
+WORKDIR /opt/catalog
+RUN npm install --ignore-scripts --no-audit --no-fund --save-exact \
+    @oven/bun-linux-x64@${BUN_VERSION} @volter/twin-standard@${STANDARD_VERSION} \
+    @volter/world-core@${CORE_VERSION} @volter/world-runtime@${RUNTIME_VERSION} tar@7.5.7 semver@7.8.5 sigstore@4.1.1 playwright@${PLAYWRIGHT_VERSION}
+ENV PATH="/opt/catalog/node_modules/@oven/bun-linux-x64/bin:/opt/catalog/node_modules/.bin:${PATH}"
+RUN ./node_modules/.bin/playwright install --with-deps chromium
+COPY lib /opt/catalog/lib
+COPY runner /opt/catalog/runner
+USER node
+WORKDIR /work
+ENTRYPOINT ["node"]

package/runner/browser-fixture.ts

@@ -0,0 +1,17 @@
+// Mechanism regression, not a pack or an admission verdict. Invoked only by the offline Actions container.
+import assert from 'node:assert/strict';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createPack, verifyBrowserTransport } from '@volter/twin-standard';
+import { write } from '../lib/model.mjs';
+assert.ok(process.env.VOLTER_WORLD, 'browser fixture must run through a World');
+const authored = '/work/packs/authoring-fixture';
+await createPack([authored, '--init', 'authoring-fixture', '--package', '@independent/payments']);
+mkdirSync(join(authored, 'src/generated'), { recursive: true });
+write(join(authored, 'src/generated/surface.gen.json'), { version: '1', operations: [], resources: [] });
+write(join(authored, 'journeys/decisions.json'), { decisions: [] });
+await createPack([authored, '--index']);
+assert.equal(JSON.parse(readFileSync(join(authored, 'package.json'), 'utf8')).name, '@independent/payments');
+assert.ok(readFileSync(join(authored, 'src/index.ts'), 'utf8').includes('createAuthoringFixtureTwinServer'));
+const report = await verifyBrowserTransport('/work/packs/browser-fixture');
+write('/work/browser-report.json', { ...report, authoringWithoutPlatformCheckout: true, independentPackageIdentity: '@independent/payments' });

package/runner/cleanup.mjs

@@ -0,0 +1,12 @@
+// A cancellation may lose the controller; remove only resources explicitly owned by this workflow run.
+import { spawnSync } from 'node:child_process';
+const run = (...args) => spawnSync('docker', args, { encoding: 'utf8' });
+if (!/^[0-9]+-[0-9]+$/.test(process.env.CATALOG_RUN ?? '')) throw new Error('workflow run identity required');
+const containers = run('ps', '-aq', '--filter', `label=twin-catalog.run=${process.env.CATALOG_RUN}`);
+if (containers.status !== 0) throw new Error('cannot inspect owned containers');
+const ids = containers.stdout.trim().split(/\s+/).filter(Boolean);
+if (ids.length && run('rm', '-f', ...ids).status !== 0) throw new Error('owned container teardown failed');
+// Volume ownership is also tagged by the host controller, and no unlabelled resource is eligible.
+const volumes = run('volume', 'ls', '-q', '--filter', `label=twin-catalog.run=${process.env.CATALOG_RUN}`);
+if (volumes.status !== 0) throw new Error('cannot inspect owned volumes');
+for (const id of volumes.stdout.trim().split(/\s+/).filter(Boolean)) if (run('volume', 'rm', id).status !== 0) throw new Error(`owned volume teardown failed: ${id}`);

package/runner/evaluate.mjs

@@ -0,0 +1,15 @@
+// Runs only inside the offline container and a task-owned World. The released standard owns all pack checks.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { read, requireThat, write, compareReports } from '../lib/model.mjs';
+requireThat(Boolean(process.env.VOLTER_WORLD), 'evaluation must run inside a World');
+const { submission: s } = read('/input/input.json');
+const requireFromPack = createRequire('/work/package.json');
+const { assessPack } = await import(requireFromPack.resolve('@volter/twin-standard'));
+const assessment = await assessPack(join('/work/packs', s.vendor), { browser: true });
+requireThat(assessment.package === s.package && assessment.version === s.version && assessment.vendor === s.vendor, 'assessment returned a different artifact identity');
+const report = { ...assessment, integrity: s.integrity, prepared: read('/work/prepared.json') };
+report.comparison = compareReports(report, existsSync('/input/baseline.json') ? read('/input/baseline.json') : null);
+write('/work/report.json', report);
+process.exit(report.ready ? 0 : 1);

package/runner/prepare.mjs

@@ -0,0 +1,81 @@
+// No credentials enter this container. This phase downloads data; scripts are disabled.
+import { readFileSync, writeFileSync, mkdirSync, cpSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { x } from 'tar';
+import semver from 'semver';
+import { verify as verifyBundle } from 'sigstore';
+import { read, write, requireThat, digest } from '../lib/model.mjs';
+import { metadata, installationMetadata, registryURL, verifyArtifact, verifiedProvenance } from '../lib/registry.mjs';
+
+const input = read('/input/input.json');
+const { submission: s, source, policy } = input;
+const doc = await metadata(s.package, s.version, policy.registry, fetch, {});
+requireThat(doc.dist?.attestations?.url, 'npm provenance required; this version has no attestation');
+const tarResponse = await fetch(registryURL(doc.dist.tarball, policy.registry), { redirect: 'error' });
+requireThat(tarResponse.ok, `tarball: HTTP ${tarResponse.status}`);
+const bytes = Buffer.from(await tarResponse.arrayBuffer());
+verifyArtifact(bytes, s, doc);
+writeFileSync('/work/artifact.tgz', bytes);
+mkdirSync('/work/unpacked', { recursive: true });
+await x({ file: '/work/artifact.tgz', cwd: '/work/unpacked', strict: true, filter: (path, entry) => {
+  requireThat(path.startsWith('package/') && !path.split('/').includes('..') && !path.includes('\\') && ['File', 'Directory'].includes(entry.type), `unsafe archive entry: ${path}`);
+  requireThat(!path.split('/').includes('node_modules') && !path.endsWith('/.npmrc'), 'artifact carries installation configuration or dependencies');
+  return true;
+} });
+const pack = read('/work/unpacked/package/package.json');
+requireThat(pack.name === s.package && pack.version === s.version, 'artifact manifest identity mismatch');
+requireThat(typeof pack.license === 'string' && pack.license.trim() && pack.license !== 'UNLICENSED', 'artifact needs a redistributable license declaration for moderator review');
+const repository = typeof pack.repository === 'string' ? pack.repository : pack.repository?.url;
+requireThat(repository?.replace(/^git\+/, '').replace(/\.git$/, '') === `https://github.com/${source.repository}`, 'artifact repository differs from registered source');
+const facts = read('/work/unpacked/package/generated/pack-facts.json');
+requireThat(Object.keys(facts.packs ?? {}).length === 1 && facts.packs[s.vendor]?.protocol?.declared === '3', 'artifact facts must identify the submitted vendor and Protocol 3');
+for (const group of ['dependencies', 'optionalDependencies', 'peerDependencies', 'devDependencies']) {
+  for (const [name, range] of Object.entries(pack[group] ?? {})) requireThat(typeof range === 'string' && semver.validRange(range), `${name}: registry semver dependencies only; git, file, URL and alias dependencies are not admitted`);
+}
+// npm verifies the registry artifact itself, not a local-directory replacement.
+// The standard's client cases and the pack's declared SDK examples need their pinned development clients too.
+// This installs data only; candidate scripts never execute in the networked preparation phase.
+const standardManifest = read('/opt/catalog/node_modules/@volter/twin-standard/package.json');
+const dependencies = { ...standardManifest.devDependencies, ...pack.devDependencies, ...policy.tools, [s.package]: s.version };
+requireThat(!Object.hasOwn(policy.tools, s.package), 'submission collides with evaluator tooling');
+write('/work/package.json', { name: 'catalog-assessment', private: true, dependencies });
+await installationMetadata(s, policy.registry);
+const npm = (args) => {
+  const r = spawnSync('npm', [...args, '--registry', policy.registry], { cwd: '/work', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  requireThat(r.status === 0, `npm ${args[0]} failed: ${r.stderr || r.stdout}`);
+  return r.stdout;
+};
+npm(['install', '--ignore-scripts', '--no-audit', '--no-fund']);
+const lock = read('/work/package-lock.json');
+for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+  if (!path) continue;
+  requireThat(!entry.link && entry.resolved && entry.integrity, `${path}: dependency is not a locked registry artifact`);
+  registryURL(entry.resolved, policy.registry);
+}
+for (const [name, version] of Object.entries(policy.tools)) requireThat(lock.packages?.[`node_modules/${name}`]?.version === version, `${name}: evaluator version differs from policy`);
+requireThat(lock.packages?.[`node_modules/${s.package}`]?.integrity === s.integrity, 'installed artifact differs from submission');
+const candidateRequire = createRequire(join('/work/node_modules', s.package, 'package.json'));
+const evaluatorRequire = createRequire('/work/package.json');
+requireThat(candidateRequire.resolve('@volter/world-core/runtime') === evaluatorRequire.resolve('@volter/world-core/runtime'), 'candidate resolves a different kernel from the policy-pinned assessment; adjust its SDK range');
+const clientSdkLocks = [];
+for (const directory of standardManifest.assessmentClientSdks ?? []) {
+  requireThat(typeof directory === 'string' && /^[a-z][a-z0-9-]*$/.test(directory), 'standard client SDK directory must be a package-local name');
+  const sdkRoot = join('/work/node_modules/@volter/twin-standard', directory);
+  const sdkLock = readFileSync(join(sdkRoot, 'bun.lock'), 'utf8');
+  const installed = spawnSync('bun', ['install', '--frozen-lockfile', '--ignore-scripts', '--registry', policy.registry], { cwd: sdkRoot, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  requireThat(installed.status === 0, `standard client SDK preparation failed: ${installed.stderr}`);
+  requireThat(readFileSync(join(sdkRoot, 'bun.lock'), 'utf8') === sdkLock, 'standard client SDK lock changed during frozen installation');
+  clientSdkLocks.push({ directory, manifest: read(join(sdkRoot, 'package.json')), lock: sdkLock, sha256: digest(sdkLock) });
+}
+const audit = npm(['audit', 'signatures', '--json']);
+writeFileSync('/work/signatures.json', audit);
+const response = await fetch(registryURL(doc.dist.attestations.url, policy.registry), { redirect: 'error' });
+requireThat(response.ok, `attestation: HTTP ${response.status}`);
+const provenance = await verifiedProvenance(await response.json(), source, bytes, verifyBundle);
+// Keep a vendor-named package directory for the standard's public directory API; preserve the installed artifact.
+mkdirSync('/work/packs', { recursive: true });
+cpSync(join('/work/node_modules', s.package), join('/work/packs', s.vendor), { recursive: true });
+write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, tools: policy.tools });
+write('/work/world.json', { id: 'catalog-assessment', network: { egress: [] }, services: [] });