@runeditrun/rer 0.0.0-stage → 0.1.1

package/operations/operations.mjs

@@ -0,0 +1,168 @@
+import { readFile, access } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+function usefulEnvironmentSource(source) {
+  if (typeof source !== 'string') return false;
+  const value = source.trim();
+  if (source !== value || value.length < 8 || value.length > 180 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value)) return false;
+  if (/(?:[a-z][a-z\d+.-]{1,20}:\/\/|www\.)/i.test(value)) return false;
+  if (/(?:[a-z\d-]+\.)+[a-z]{2,}(?::\d+)?(?:[/?#]\S*)?/i.test(value)
+      && !/\.(?:md|txt|jsonc?|ya?ml|toml|m?js|cjs|tsx?|jsx?|py|pdf|docx?|csv|env|sh|html?|xml|sql|log|rst|adoc|conf|ini)(?:[/:#][^\s]*)?$/i.test(value)) return false;
+  // Sources identify where to obtain a value, never assign one. Reject equals
+  // assignments regardless of the variable name and colon labels containing a
+  // credential term, including prefixed/suffixed names and quoted JSON keys.
+  if (value.includes('=')) return false;
+  if (/[\w.-]*(?:key|authorization|credential|password|passwd|secret|token|pwd)[\w.-]*["'`]?\s*:/i.test(value)) return false;
+  if (/\b(?:bearer|basic)\s+[A-Za-z0-9._~+/-]{12,}/i.test(value)) return false;
+  if (/\b(?:sk|pk|rk|ghp|gho|ghu|ghs|ghr|github_pat|xox[baprs]|glpat|AIza|AKIA)[_-][A-Za-z0-9._-]{8,}\b/i.test(value)) return false;
+  if (/\b(?:SG\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|whsec_[A-Za-z0-9]+|(?:AKIA|ASIA)[A-Z0-9]{16}|AIza[A-Za-z0-9_-]{16,})\b/.test(value)) return false;
+  if (/(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{16,}(?![A-Za-z0-9_-])/.test(value)) return false;
+  if (/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(value)) return false;
+  return (value.match(/[A-Za-z0-9]+/g) ?? []).length >= 2;
+}
+
+export function validateEnvironmentSources(descriptor, knownNames) {
+  const sources = descriptor.environmentSources;
+  if (sources === undefined) return;
+  if (!sources || typeof sources !== 'object' || Array.isArray(sources)) throw new Error('Invalid environment source declaration.');
+  for (const [name, source] of Object.entries(sources)) {
+    if (!knownNames.has(name) || !usefulEnvironmentSource(source)) throw new Error('Invalid environment source declaration.');
+  }
+}
+
+export async function readOperations(root) {
+  const descriptor = JSON.parse(await readFile(resolve(root, 'OPERATIONS.json'), 'utf8'));
+  if (descriptor.version === 2) {
+    const { readProjectOperations } = await import('./project-operations.mjs');
+    return readProjectOperations(root, descriptor, validateEnvironmentSources);
+  }
+  if (descriptor.version !== 1 || typeof descriptor.edition !== 'string' || !descriptor.edition || !Array.isArray(descriptor.requiredEnvironment) || descriptor.requiredEnvironment.some(name => typeof name !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(name)) || descriptor.acceptance?.document !== 'ACCEPTANCE.md') throw new Error('Invalid operations descriptor.');
+  validateEnvironmentSources(descriptor, new Set(descriptor.requiredEnvironment));
+  await access(resolve(root, 'OPERATIONS.md'));
+  await access(resolve(root, descriptor.acceptance.document));
+  await access(resolve(root, 'scripts/operations-config.mjs'));
+  const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
+  const commands = [];
+  for (const name of ['setup', 'deploy', 'verify']) {
+    const command = descriptor.commands?.[name];
+    const argv = command?.argv;
+    if (!Array.isArray(argv) || argv.length < 3 || argv.some(arg => typeof arg !== 'string' || !arg) || argv[0] !== 'pnpm' || argv[1] !== 'run' || typeof command.effects !== 'string' || !command.effects || typeof pkg.scripts?.[argv[2]] !== 'string') throw new Error('Invalid operation command.');
+    let available = true;
+    // Resolve script file references as well as the package-script entry.
+    if (available) for (const match of pkg.scripts[argv[2]].matchAll(/(?:^|\s)node\s+([\w./-]+\.mjs)(?=\s|$)/g)) {
+      try { await access(resolve(root, match[1])); } catch { available = false; }
+    }
+    commands.push({ name, available });
+  }
+  return { descriptor, commands };
+}
+
+async function inspectLoadedOperations(root, env, { descriptor, commands }) {
+  const missingEnvironment = descriptor.requiredEnvironment.filter(name => typeof env[name] !== 'string' || !env[name].trim());
+  let configuration = 'valid';
+  let loops = [];
+  if (descriptor.version === 2) {
+    const { inspectRequiredLoops } = await import('./project-operations.mjs');
+    loops = inspectRequiredLoops(descriptor, env);
+  }
+  try {
+    const module = descriptor.version === 2 ? descriptor.configuration?.module : 'scripts/operations-config.mjs';
+    if (module) {
+      const adapter = await import(pathToFileURL(resolve(root, module)));
+      await adapter.validateConfiguration(env);
+    }
+  } catch { configuration = 'invalid'; }
+  return { version: descriptor.version, ...(descriptor.version === 2 ? { project: descriptor.project, runtime: descriptor.runtime } : { edition: descriptor.edition }), scope: 'local-inputs-only', ok: commands.every(c => c.available) && !missingEnvironment.length && configuration === 'valid' && loops.every(loop => ['ready', 'optional-disabled'].includes(loop.status)), ...(descriptor.version === 2 ? { loops } : {}), commands, missingEnvironment, configuration,
+    unchecked: ['installed runtime versions and command executables', 'generated deployment caches and build artifacts', 'provider identity and permissions', 'remote resources and deployed health', 'provider credentials and delivery', 'product acceptance'],
+    guidance: 'See the project operating documentation. Configuration errors are suppressed to avoid disclosing input values.' };
+}
+
+export async function inspectOperations(root, env = process.env) {
+  return inspectLoadedOperations(root, env, await readOperations(root));
+}
+
+export async function describeOperations(root) {
+  const { descriptor, commands } = await readOperations(root);
+  if (commands.some(command => !command.available)) throw new Error('Unavailable operation target.');
+  return descriptor;
+}
+
+const displayArgv = argv => argv.map(argument => {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(argument)) return argument;
+  return `'${argument.replaceAll("'", "'\\''")}'`;
+}).join(' ');
+// A project without RER names this inspector by the path it was actually run from.
+const invoked = root => displayArgv(['node', relative(root, process.argv[1] ?? 'operations.mjs')]);
+
+async function checkSummary(result, descriptor, root) {
+  const missing = [...new Set([
+    ...result.missingEnvironment,
+    ...(result.loops ?? []).flatMap(loop => loop.missingEnvironment)
+  ])];
+  const documentation = descriptor.version === 1
+    ? 'OPERATIONS.md'
+    : descriptor.documentation?.document ?? 'the project setup documentation';
+  const declaredInputs = descriptor.version === 2
+    ? (await import('./project-operations.mjs')).knownEnvironmentNames(descriptor)
+    : new Set(descriptor.requiredEnvironment ?? []);
+  const lines = [];
+  if (missing.length) lines.push('Missing inputs are expected before a deployment is configured.');
+  else lines.push(result.ok
+    ? 'Operations check passed: declared local inputs expected before deployment are configured.'
+    : 'Operations check failed: resolve local configuration or target issues before deployment.');
+  if (missing.length) {
+    const sources = descriptor?.environmentSources ?? {};
+    lines.push('Missing inputs:');
+    for (const name of missing) lines.push(`  ${name} — ${sources[name] ?? `see ${documentation}`}`);
+    lines.push('Configuration is checked again once these inputs are set.');
+  }
+  const unavailable = result.commands.filter(command => !command.available).map(command => command.name);
+  if (unavailable.length) lines.push(`Unavailable targets: ${unavailable.join(', ')}.`);
+  if (result.configuration === 'invalid' && !missing.length) {
+    lines.push('Configuration is invalid; validator details are suppressed.');
+    if (declaredInputs.size) lines.push(`Check the values you set for these declared input names: ${[...declaredInputs].sort().join(', ')}.`);
+  }
+  const blockedLoops = (result.loops ?? []).filter(loop => !['ready', 'optional-disabled'].includes(loop.status));
+  if (blockedLoops.length) lines.push(`Loops needing attention: ${blockedLoops.map(loop => `${loop.id} (${loop.status})`).join(', ')}.`);
+  if (result.ok) lines.push('Remote deployment, provider access, and product acceptance remain unchecked.');
+  else {
+    const setup = descriptor.commands?.setup;
+    if (setup?.argv) lines.push(`Next: read ${documentation}, then run the declared setup command when ready: ${displayArgv(setup.argv)}. For secondary descriptor inspection, run ${invoked(root)} describe.`);
+    else lines.push(`Next: read ${documentation} for setup guidance. No setup command is declared. For secondary descriptor inspection, run ${invoked(root)} describe.`);
+  }
+  return lines.join('\n');
+}
+
+export async function main(args = process.argv.slice(2), root = process.cwd()) {
+  const rer = resolve(root, 'scripts/rer.mjs');
+  if (!['describe', 'check'].includes(args[0]) || (args.length !== 1 && !existsSync(rer))) throw new Error('Unsupported operations command.');
+  // First-party projects describe and check through their RER command.
+  if (existsSync(rer)) {
+    process.exitCode = spawnSync(process.execPath, [rer, ...args], { cwd: root, stdio: 'inherit' }).status ?? 1;
+    return;
+  }
+  let result;
+  let descriptor;
+  if (args[0] === 'describe') result = await describeOperations(root);
+  else {
+    const loaded = await readOperations(root);
+    descriptor = loaded.descriptor;
+    result = await inspectLoadedOperations(root, process.env, loaded);
+  }
+  console.log(JSON.stringify(result, null, 2));
+  if (args[0] === 'check') {
+    console.error(await checkSummary(result, descriptor, root));
+    if (!result.ok) process.exitCode = 1;
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { await main(); } catch {
+    if (process.argv.slice(2).length === 1 && process.argv[2] === 'check') console.error('Operations check failed: descriptor or local configuration is invalid or unreadable; details are suppressed. Next: read OPERATIONS.md for recovery guidance, repair the descriptor or its referenced files, then rerun check.');
+    const usage = existsSync(resolve('scripts/rer.mjs')) ? 'node scripts/rer.mjs' : invoked(process.cwd());
+    console.error(JSON.stringify({ ok: false, error: `Invalid command or unreadable operations files. Usage: ${usage} describe|check` }));
+    process.exitCode = 1;
+  }
+}

package/operations/project-operations.mjs

@@ -0,0 +1,157 @@
+import { stat, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+const text = value => typeof value === 'string' && value.trim().length > 0;
+
+const environmentName = value => typeof value === 'string' && value === value.trim() && /^[A-Z][A-Z0-9_]*$/.test(value);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const has = (value, key) => Object.hasOwn(value, key);
+const hostedProviders = ['sendgrid', 'resend', 'cloudflare'];
+const fixedProviders = {
+  sendgrid: { apiKeyEnvironment: 'SENDGRID_API_KEY' },
+  resend: { apiKeyEnvironment: 'RESEND_API_KEY' },
+  cloudflare: { apiKeyEnvironment: 'CLOUDFLARE_EMAIL_API_TOKEN', accountIdEnvironment: 'CLOUDFLARE_EMAIL_ACCOUNT_ID' }
+};
+
+function fields(value, allowed) {
+  if (!record(value) || Object.keys(value).some(key => !allowed.includes(key))) throw new Error('Invalid loop declaration.');
+}
+
+function mailInputs(provider, declaration, fallback = false) {
+  fields(declaration, ['apiKeyEnvironment', 'requiredEnvironment', 'accountIdEnvironment', 'development', ...(fallback ? ['provider'] : [])]);
+  if (![...hostedProviders, ...(fallback ? [] : ['development'])].includes(provider)
+      || !Array.isArray(declaration.requiredEnvironment) || declaration.requiredEnvironment.some(name => !environmentName(name))) throw new Error('Invalid mail binding declaration.');
+  const names = [...declaration.requiredEnvironment];
+  if (provider === 'development') {
+    if (has(declaration, 'apiKeyEnvironment') || has(declaration, 'accountIdEnvironment')) throw new Error('Invalid development mail binding.');
+    fields(declaration.development, ['modeEnvironment', 'originEnvironment']);
+    if (!environmentName(declaration.development.modeEnvironment) || !environmentName(declaration.development.originEnvironment)) throw new Error('Invalid development mail binding.');
+    names.push(declaration.development.modeEnvironment, declaration.development.originEnvironment);
+  } else {
+    if (!environmentName(declaration.apiKeyEnvironment) || has(declaration, 'development')) throw new Error('Invalid hosted mail binding.');
+    names.unshift(declaration.apiKeyEnvironment);
+    if (provider === 'cloudflare') {
+      if (!environmentName(declaration.accountIdEnvironment)) throw new Error('Invalid hosted mail binding.');
+      names.push(declaration.accountIdEnvironment);
+    } else if (has(declaration, 'accountIdEnvironment')) throw new Error('Invalid hosted mail binding.');
+  }
+  return { ...declaration, provider, names: [...new Set(names)] };
+}
+
+// All consumers use the same validated input declarations, including disabled loops.
+function normalizedLoops(descriptor) {
+  const loops = descriptor.loops === undefined ? [] : descriptor.loops;
+  if (!Array.isArray(loops) || new Set(loops.map(loop => loop?.id)).size !== loops.length) throw new Error('Invalid loop declarations.');
+  return loops.map(loop => {
+    fields(loop, ['id', 'type', 'required', 'enabled', ...(loop?.type === 'mail' ? ['provider', 'binding'] : [])]);
+    if (typeof loop.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(loop.id) || typeof loop.required !== 'boolean' || typeof loop.enabled !== 'boolean' || !['worker', 'mail'].includes(loop.type)) throw new Error('Invalid loop declaration.');
+    if (loop.type === 'worker') return { ...loop, names: [] };
+    if (!has(loop, 'binding')) {
+      if (!hostedProviders.includes(loop.provider)) throw new Error('Invalid mail provider declaration.');
+      const selected = mailInputs(loop.provider, { ...fixedProviders[loop.provider], requiredEnvironment: [] });
+      return { ...loop, selected, names: ['MAIL_PROVIDER', ...selected.names] };
+    }
+    if (has(loop, 'provider')) throw new Error('Invalid mail binding declaration.');
+    const binding = loop.binding;
+    fields(binding, ['providerEnvironment', 'providers', 'whenUnset']);
+    if (!environmentName(binding.providerEnvironment) || !record(binding.providers) || !Object.keys(binding.providers).length) throw new Error('Invalid mail binding declaration.');
+    const providers = Object.fromEntries(Object.entries(binding.providers).map(([provider, inputs]) => [provider, mailInputs(provider, inputs)]));
+    const whenUnset = has(binding, 'whenUnset') ? mailInputs(binding.whenUnset?.provider, binding.whenUnset, true) : undefined;
+    return { ...loop, binding: { ...binding, providers, whenUnset }, names: [...new Set([binding.providerEnvironment, ...Object.values(providers).flatMap(inputs => inputs.names), ...(whenUnset?.names ?? [])])] };
+  });
+}
+
+export function knownEnvironmentNames(descriptor) {
+  return new Set([...descriptor.requiredEnvironment, ...normalizedLoops(descriptor).flatMap(loop => loop.names)]);
+}
+
+function localDevelopmentOrigin(value) {
+  if (typeof value !== 'string') return false;
+  try {
+    const url = new URL(value);
+    return ['http:', 'https:'].includes(url.protocol) && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+      && !url.username && !url.password && !url.search && !url.hash && url.pathname === '/'
+      && (value === url.origin || value === `${url.origin}/`);
+  } catch { return false; }
+}
+
+function inspectMailInputs(selected, env) {
+  const missingEnvironment = selected.names.filter(name => !text(env[name]));
+  let status = 'ready';
+  const missing = name => { if (!missingEnvironment.includes(name)) missingEnvironment.push(name); };
+  if (selected.accountIdEnvironment && (typeof env[selected.accountIdEnvironment] !== 'string' || !/^[a-f0-9]{32}$/i.test(env[selected.accountIdEnvironment]))) missing(selected.accountIdEnvironment);
+  if (selected.development) {
+    const { modeEnvironment, originEnvironment } = selected.development;
+    if (env[modeEnvironment] !== 'development') missing(modeEnvironment);
+    if (!localDevelopmentOrigin(env[originEnvironment])) missing(originEnvironment);
+    if (missingEnvironment.includes(modeEnvironment) || missingEnvironment.includes(originEnvironment)) status = 'invalid-development-mail';
+  }
+  if (missingEnvironment.length && status === 'ready') status = 'missing-inputs';
+  return { status, missingEnvironment };
+}
+
+// Descriptors can identify only files in their own checkout, including through symlinks.
+async function localFile(root, path) {
+  if (!text(path) || isAbsolute(path) || path.split(/[\\/]/).includes('..')) throw new Error('Invalid project input path.');
+  const target = await realpath(resolve(root, path));
+  const inside = relative(await realpath(root), target);
+  if (inside.startsWith('..') || isAbsolute(inside)) throw new Error('Project input escapes checkout.');
+  if (!(await stat(target)).isFile()) throw new Error('Project input is not a file.');
+}
+
+export async function readProjectOperations(root, descriptor, validateSources) {
+  if (descriptor.seedContract !== undefined) {
+    const contract = descriptor.seedContract;
+    if (!contract || contract.version !== 1 || contract.profile !== 'first-party' || !text(contract.adapter)
+        || Object.keys(contract).some(key => !['version', 'profile', 'adapter'].includes(key))) throw new Error('Invalid seed command contract.');
+    await localFile(root, contract.adapter);
+  }
+  if (!text(descriptor.project) || !Array.isArray(descriptor.requiredEnvironment)
+      || descriptor.requiredEnvironment.some(name => !environmentName(name))
+      || !Array.isArray(descriptor.runtime?.requirements)
+      || descriptor.runtime.requirements.some(item => !text(item?.name) || !text(item?.version))
+      || !descriptor.commands || Array.isArray(descriptor.commands)
+      || !Object.keys(descriptor.commands).length) throw new Error('Invalid project operations descriptor.');
+  inspectRequiredLoops(descriptor, {});
+  if (typeof validateSources !== 'function') throw new Error('Environment source validation is unavailable.');
+  validateSources(descriptor, knownEnvironmentNames(descriptor));
+  for (const path of [descriptor.documentation?.document, descriptor.acceptance?.document, descriptor.configuration?.module].filter(value => value !== undefined)) await localFile(root, path);
+  const commands = [];
+  for (const [name, command] of Object.entries(descriptor.commands)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name) || !Array.isArray(command?.argv) || !command.argv.length
+        || command.argv.some(arg => typeof arg !== 'string') || !text(command.argv[0])
+        || !text(command.effects) || !Array.isArray(command.inputs)) throw new Error('Invalid project operation command.');
+    let available = true;
+    for (const path of command.inputs) {
+      // Malformed paths are descriptor errors; missing declared files are unavailable targets.
+      if (!text(path) || isAbsolute(path) || path.split(/[\\/]/).includes('..')) throw new Error('Invalid project input path.');
+      try { await localFile(root, path); } catch (error) {
+        if (error.code === 'ENOENT') available = false;
+        else throw error;
+      }
+    }
+    commands.push({ name, available });
+  }
+  return { descriptor, commands };
+}
+
+/** Declarative local loop checks. Never imports a module, sends mail, queries DNS or invokes a command. */
+export function inspectRequiredLoops(descriptor, env) {
+  return normalizedLoops(descriptor).map(loop => {
+    let result = { status: 'ready', missingEnvironment: [] };
+    if (!loop.enabled) result.status = loop.required ? 'disabled-required' : 'optional-disabled';
+    else if (loop.type === 'mail') {
+      if (loop.binding) {
+        const { providerEnvironment, providers, whenUnset } = loop.binding;
+        const provider = env[providerEnvironment];
+        const selected = provider === undefined ? whenUnset : typeof provider === 'string' && has(providers, provider) ? providers[provider] : undefined;
+        result = selected ? inspectMailInputs(selected, env) : { status: 'invalid-mail-provider', missingEnvironment: [providerEnvironment] };
+      } else {
+        result = inspectMailInputs(loop.selected, env);
+        // Preserve the fixed-provider contract's truthy-selector mismatch behavior.
+        if (env.MAIL_PROVIDER && env.MAIL_PROVIDER !== loop.provider) result.status = 'mail-provider-mismatch';
+      }
+    }
+    return { id: loop.id, required: loop.required, ...result };
+  });
+}

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@runeditrun/rer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "rer": "global/rer.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/scripts/publish-check/README.md

@@ -0,0 +1,72 @@
+# Publication scan implementation
+
+See [setup, command and scope](../publish-check-README.md).
+
+`git_history.py` delegates revision resolution, traversal, tree inventory and
+blob reads to system Git (`rev-parse`, `rev-list`, `ls-tree`, `cat-file --batch`).
+`gitleaks.py` runs the pinned scanner in git, directory and stdin modes and keeps
+its report private until translating it into the value-free v3 envelope.
+Hexadecimal credential assignments also use a Gitleaks rule without generic
+entropy or English stopword filters. Both assignment rules go through the same
+location-bound Source/module identity proof; provider and environment findings
+remain independent.
+`tree_scan.py` applies the kept text and licence policy. `history_scan.py`
+assigns release, working-tree and historical scopes. The Node entry point bounds
+the whole operation and stops its private process group on timeout/cancellation.
+
+Binary metadata decoding, Git protocol/object/ref modelling, frozen comparison,
+resumable inspection and their tests have been removed. Tests live in `tests.py`
+and `coverage_tests.py` and construct disposable repositories with actual Git.
+
+`content_identities.py` classifies only exact generic-api-key occurrences at
+proved Source key locations. It requires same-tree edition/lock selections,
+manifest and archive hashes, valid retained file records, and exact native match
+bytes. Retained archive bytes must hash to the maintained Source serializer's
+`hash(json(saved))` as well as the selected pin. `source_hashes.mjs` reuses that
+serializer. Duplicate JSON fields, non-JSON constants (including ignored fields),
+incorrect types, missing preimages, mismatched pins and unrecognized locations keep
+the native finding. Each selection's complete dependency closure must have valid
+archive and pin proofs before any location in that graph is allowed; unrelated
+coherent selections remain eligible. Normal origin repositories obey the maintained
+Source schema, including rejection of strings starting with `-`.
+Original/private keys and arbitrary copies of a known digest
+are not proofs. Provider and environment findings are unaffected. Native git/dir
+matches are held only in the private temporary report and memory for this proof;
+matched values are never added to the public report. This classification does not
+replace or relax the edition-authoring check.
+
+`copy_identities.py` proves the maintained `base-copies.json` and portable
+`base/PROVENANCE.json` copy-inventory SHA-256 values
+against every declared file's bytes and regular-file mode in the same scanned
+tree. Historical matches use only that commit's blobs; present files cannot
+rescue a historical mismatch. Working-tree preimages reject linked paths.
+Only the exact native match at a proved inventory field is classified. There
+is no filename, hash-value or comma-delimited credential exemption.
+
+`checksum_maps.py` classifies a file-name to digest map (`'0005_operator_auth.sql':
+'<sha256>'`, in JSON, JavaScript, YAML or similar) in any file outside the
+content-identity documents above. The native match must sit in a run of
+`name: digest` entries separated only by commas, semicolons, whitespace and line
+comments, and every entry in that run must name a regular file in the same scanned
+tree (a path, or a trailing path component) whose bytes hash to that SHA-256. One
+entry that does not prove, a 40-hex value, a key that names no tree file, or a hex
+value with no file-name key keeps the native finding. Historical matches use only
+that commit's blobs and working-tree preimages reject linked paths. There is no
+path, filename, hash-value or repository exemption. `hit_location.py` resolves
+the native match's exact bytes for both proofs.
+
+`trust_bundle.py` classifies an email match as public CA certificate metadata
+only when all of these hold: the file's path is an artifact listed by a committed
+`trust-bundle.json` in its directory and its bytes hash to the SHA-256 pinned
+there; that manifest's webpki-roots release and checksum are exactly the one the
+same directory's `Cargo.lock` locks from crates.io; and the match lies entirely
+inside an attribute value of a subject Name parsed (`der.py`, strict DER) from
+those bytes, where the anchor's subject Name and SubjectPublicKeyInfo DER both
+occur in the file and hash to one anchor entry of the manifest. With the verified
+subject values blanked, no email may remain, and every match must be one found
+inside them; otherwise the file keeps `hygiene.email`. Historical blobs use their
+own commit's manifest and lock; working-tree files use the selected commit's.
+The build that produces the artifacts (`modules/egress-service/tls/build.mjs`)
+regenerates the manifest, and its `--check` mode rejects a stale one. An
+alphabetic top-level domain label ends before a following digit, so a match
+ends at the DER string's boundary rather than absorbing the next tag byte.

package/scripts/publish-check/checksum_maps.py

@@ -0,0 +1,52 @@
+"""Classify file-name to SHA-256 maps whose every digest is a same-tree file's hash.
+
+A map is a run of `name: "digest"` entries separated only by commas, semicolons,
+whitespace and line comments. The native finding inside it is classified only
+when every entry names a regular file in the scanned tree whose bytes hash to
+that entry's digest. One unproved entry, or a hex value no entry keys to a file,
+keeps the finding. No path, filename or repository is exempt.
+"""
+import hashlib
+import re
+from copy_identities import relative_path
+from hit_location import match_spans
+
+ENTRY = re.compile(
+    rb'''(?<![\w./@+-])(?:(?P<q>["'`])(?P<quoted>[^"'`\\\r\n]{1,200})(?P=q)|(?P<bare>[\w./@+-]{1,200}))'''
+    rb'''[ \t]*(?::|=>|=)[ \t]*(?P<v>["'`]?)(?P<digest>[a-f0-9]{64}|[a-f0-9]{40})(?P=v)(?![a-f0-9\w])''')
+SEPARATOR = re.compile(rb'(?:[\s,;]|(?://|#)[^\n]*)*')
+
+
+class ChecksumMaps:
+    def __init__(self, paths, read_regular):
+        self.paths, self.read_regular, self.hashes = sorted(paths), read_regular, {}
+
+    def digest(self, path):
+        if path not in self.hashes:
+            value = self.read_regular(path)
+            self.hashes[path] = hashlib.sha256(value[0]).hexdigest() if value else None
+        return self.hashes[path]
+
+    def names_file(self, name, digest):
+        return (relative_path(name) and len(digest) == 64
+                and any(self.digest(path) == digest for path in self.paths
+                        if path == name or path.endswith('/' + name)))
+
+    def matches(self, data, hit):
+        if hit.get('RuleID') not in ('generic-api-key', 'hex-api-key'):
+            return False
+        entries = list(ENTRY.finditer(data))
+        for left, right in match_spans(data, hit):
+            keyed = [i for i, e in enumerate(entries)
+                     if left <= e.start('digest') and e.end('digest') <= right
+                     and e.group('digest').decode() == hit.get('Secret')]
+            if len(keyed) != 1:
+                continue
+            first = last = keyed[0]
+            while first > 0 and SEPARATOR.fullmatch(data, entries[first - 1].end(), entries[first].start()):
+                first -= 1
+            while last + 1 < len(entries) and SEPARATOR.fullmatch(data, entries[last].end(), entries[last + 1].start()):
+                last += 1
+            return all(self.names_file((e.group('quoted') or e.group('bare')).decode('utf-8', 'replace'),
+                                       e.group('digest').decode()) for e in entries[first:last + 1])
+        return False

package/scripts/publish-check/cli.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from history_scan import scan
+
+
+class SafeParser(argparse.ArgumentParser):
+    def error(self, message):
+        self.exit(2, 'publish-check invalid arguments\n')
+
+
+def seconds(value):
+    result = float(value)
+    if not 0 < result <= 7200:
+        raise argparse.ArgumentTypeError('invalid timeout')
+    return result
+
+
+def main():
+    parser = SafeParser(description='Scan working files and full history with system Git and pinned Gitleaks.')
+    parser.add_argument('--repo', required=True)
+    parser.add_argument('--ref', default='HEAD')
+    for option in ('public-base', 'env-file', 'project', 'repository', 'cache-dir'):
+        parser.add_argument('--' + option)
+    parser.add_argument('--timeout-seconds', type=seconds, default=300)
+    args = parser.parse_args()
+    report = scan(args.repo, args.ref, args.public_base, args.env_file, args.project, args.repository,
+                  cache_dir=args.cache_dir, timeout=args.timeout_seconds)
+    print(json.dumps(report))
+    return {'PASS': 0, 'FAIL': 1, 'INCOMPLETE': 2}[report['status']]
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/scripts/publish-check/command_arguments.py

@@ -0,0 +1,51 @@
+"""Retain completed shell words and quoted parts before malformed outer text."""
+import shlex
+
+
+def completed_parts(source):
+    """Read completed components of the final, unfinished shell word.
+
+    An unknown wrapper can leave its closing quote after a complete quoted
+    command argument. shlex keeps that argument in its pending token and then
+    raises. Keep its closed quote components and leading unquoted component;
+    unquoted suffixes between later source quotes are not command arguments.
+    """
+    parts, leading, quoted = [], '', False
+    delimiter, opened, index = None, 0, 0
+    while index < len(source):
+        char = source[index]
+        if char == '\\' and delimiter != "'":
+            if not delimiter and not quoted:
+                leading += source[index:index + 2]
+            index += 2
+            continue
+        if delimiter:
+            if char == delimiter:
+                parts.extend(shlex.split(source[opened:index + 1], posix=True))
+                delimiter = None
+        elif char in ' \t\r\n':
+            parts, leading, quoted = [], '', False
+        elif char in '#;&|':
+            return []
+        elif char in "'\"":
+            if not quoted and leading:
+                parts.extend(shlex.split(leading, posix=True))
+            delimiter, opened, quoted = char, index, True
+        elif not quoted:
+            leading += char
+        index += 1
+    return parts
+
+
+def arguments(source):
+    shell = shlex.shlex(source, posix=True, punctuation_chars=';&|')
+    shell.whitespace_split = True
+    try:
+        for word in shell:
+            if word and all(char in ';&|' for char in word):
+                return
+            yield word
+    except ValueError:
+        # Completed words have already been yielded. A completed quoted part
+        # of the pending word must not disappear with a later unmatched quote.
+        yield from completed_parts(source)

package/scripts/publish-check/command_shell_quotes.py

@@ -0,0 +1,41 @@
+"""Bound literal arguments in documentary shell output commands."""
+import re
+import shlex
+
+OUTPUT = re.compile(r'(?m)^[ \t]*(?:(?:command|builtin)[ \t]+)?(?:echo|printf)[ \t]+')
+
+
+def output_quotes(source):
+    """Recognize explicit echo/printf statements without running a shell.
+
+    Arbitrary prose is often valid shell syntax, so shell tokenization alone
+    cannot establish a source context. These output statements explicitly
+    present their arguments as text. Custom executable names make no such
+    assertion about a document's prose.
+    """
+    found = set()
+    for match in OUTPUT.finditer(source):
+        quotes, delimiter = set(), None
+        index = match.end()
+        while index < len(source):
+            char = source[index]
+            if char == '\\' and delimiter != "'":
+                index += 2
+                continue
+            if delimiter:
+                if char == delimiter:
+                    delimiter = None
+            elif char in '\n;&|':
+                break
+            elif char == '#' and source[index - 1].isspace():
+                break
+            elif char in "'\"":
+                delimiter = char
+                quotes.add(index)
+            index += 1
+        try:
+            shlex.split(source[match.start():index], comments=True, posix=True)
+        except ValueError:
+            continue
+        found.update(quotes)
+    return found