@runeditrun/rer 0.2.0 → 0.2.2

package/modules/release/signature.mjs

@@ -0,0 +1,336 @@
+// Shared release authentication: dependency-free, with one WebCrypto code path.
+export const PAYLOAD_TYPE = 'application/vnd.runeditrun.release-statement.v1+json';
+export const ENROLMENT_TYPE = 'application/vnd.runeditrun.key-enrolment.v1+json';
+export const LIMITS = Object.freeze({ envelopeBytes: 65536, files: 256, fileBytes: 1073741824 });
+const encoder = new TextEncoder();
+const trusted = new WeakMap();
+const codes = new Set(('SIGNATURE_MISSING INPUT_TOO_LARGE ENVELOPE_INVALID KEY_TEST_REFUSED KEY_UNKNOWN SIGNATURE_INVALID STATEMENT_NOT_CANONICAL STATEMENT_INVALID PUBLISHER_MISMATCH KEY_OUTSIDE_VALIDITY KEY_RETIRED KEY_REVOKED ISSUED_IN_FUTURE SUBJECT_MISMATCH FILE_MISSING FILE_UNDECLARED DIGEST_MISMATCH PATH_UNSAFE VERSION_ROLLBACK VERSION_REUSED ANCHORS_INVALID ANCHORS_STALE').split(' '));
+export class Refusal extends Error {
+  constructor(code) { const safe = codes.has(code) ? code : 'STATEMENT_INVALID'; super(safe); this.name = 'Refusal'; this.code = safe; }
+}
+const refuse = code => { throw new Refusal(code); };
+function sanitized(error, code) { refuse(error instanceof Refusal && codes.has(error.code) ? error.code : code); }
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const matches = (value, pattern) => typeof value === 'string' && pattern.test(value);
+function shape(value, required, optional = []) {
+  if (!record(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  return required.every(key => Object.hasOwn(value, key)) && keys.every(key => typeof key === 'string'
+    && (required.includes(key) || optional.includes(key)) && Object.getOwnPropertyDescriptor(value, key)?.value !== undefined);
+}
+function ascii(value) { return typeof value === 'string' && value.length > 0 && !/[^\x20-\x7e]/.test(value); }
+const namespace = /^[a-z0-9][a-z0-9-]{0,38}$/;
+// Names are literal printable ASCII components, not URLs. Do not case-fold them.
+export function validRelativePath(path) {
+  return ascii(path) && !path.includes('\\') && path.split('/').every(part => part && part !== '.' && part !== '..');
+}
+export function validProject(value) {
+  if (!validRelativePath(value)) return false;
+  const parts = value.split('/');
+  return parts.length === 2 && namespace.test(parts[0]);
+}
+const repositoryPattern = /^https:\/\/github\.com\/[a-z0-9][a-z0-9-]{0,38}\/[a-z0-9._-]{1,100}$/;
+const hex40 = /^[a-f0-9]{40}$/, hex64 = /^[a-f0-9]{64}$/;
+const keyPattern = /^(rer|test)-ed25519-[a-f0-9]{32}$/;
+function version(value) {
+  return matches(value, /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/)
+    && value.split('.').every(part => Number.isSafeInteger(Number(part)));
+}
+function instant(value) {
+  return matches(value, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value.replace('Z', '.000Z');
+}
+function bytes(value, code) { if (!(value instanceof Uint8Array)) refuse(code); return value; }
+function serialize(value, ancestors) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value);
+  if ((!Array.isArray(value) && !record(value)) || ancestors.has(value)) refuse('STATEMENT_INVALID');
+  ancestors.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    if (Reflect.ownKeys(value).length !== value.length + 1) refuse('STATEMENT_INVALID');
+    result = '[' + Array.from({ length: value.length }, (_, i) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+      if (!descriptor || !('value' in descriptor)) refuse('STATEMENT_INVALID');
+      return serialize(descriptor.value, ancestors);
+    }).join(',') + ']';
+  } else {
+    const keys = Reflect.ownKeys(value);
+    if (keys.some(key => typeof key !== 'string')) refuse('STATEMENT_INVALID');
+    result = '{' + keys.sort().map(key => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor.enumerable || !('value' in descriptor)) refuse('STATEMENT_INVALID');
+      return JSON.stringify(key) + ':' + serialize(descriptor.value, ancestors);
+    }).join(',') + '}';
+  }
+  ancestors.delete(value);
+  return result;
+}
+export function canonical(value) {
+  try { return serialize(value, new Set()); } catch (error) { sanitized(error, 'STATEMENT_INVALID'); }
+}
+export const canonicalBytes = value => encoder.encode(canonical(value));
+export function pae(type, body) {
+  try {
+    if (typeof type !== 'string') refuse('ENVELOPE_INVALID');
+    bytes(body, 'ENVELOPE_INVALID');
+    const prefix = encoder.encode(`DSSEv1 ${encoder.encode(type).length} ${type} ${body.length} `);
+    const result = new Uint8Array(prefix.length + body.length);
+    result.set(prefix); result.set(body, prefix.length); return result;
+  } catch (error) { sanitized(error, 'ENVELOPE_INVALID'); }
+}
+export function b64(value) {
+  try { bytes(value, 'ENVELOPE_INVALID'); let text = ''; for (const byte of value) text += String.fromCharCode(byte); return btoa(text); }
+  catch (error) { sanitized(error, 'ENVELOPE_INVALID'); }
+}
+function unb64(value) {
+  if (!matches(value, /^[A-Za-z0-9+/]*={0,2}$/)) refuse('ENVELOPE_INVALID');
+  let result;
+  try { result = Uint8Array.from(atob(value), char => char.charCodeAt(0)); } catch { refuse('ENVELOPE_INVALID'); }
+  if (b64(result) !== value) refuse('ENVELOPE_INVALID');
+  return result;
+}
+export async function sha256(value) {
+  try { return [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes(value, 'STATEMENT_INVALID')))].map(byte => byte.toString(16).padStart(2, '0')).join(''); }
+  catch (error) { sanitized(error, 'STATEMENT_INVALID'); }
+}
+export async function keyIdFor(scope, raw) {
+  if (!['rer', 'test'].includes(scope) || !(raw instanceof Uint8Array) || raw.length !== 32) refuse('ANCHORS_INVALID');
+  return `${scope}-ed25519-${(await sha256(raw)).slice(0, 32)}`;
+}
+export function compareVersion(a, b) {
+  if (!version(a) || !version(b)) refuse('STATEMENT_INVALID');
+  const x = a.split('.').map(Number), y = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i] ? 1 : -1;
+  return 0;
+}
+const requiredFiles = ['public-source.tar', 'release-receipt.json', 'publish-check.json'];
+const filePattern = /^(public-source\.tar|release-receipt\.json|publish-check\.json|site\/[a-z0-9]+(?:-[a-z0-9]+)*\/[^/]+\/(?:release\.json|documents\/.+))$/;
+function safePath(path) {
+  return validRelativePath(path) && matches(path, filePattern);
+}
+export function validateStatement(s) {
+  try {
+    if (!shape(s, ['schemaVersion', 'publisher', 'project', 'version', 'tag', 'repository', 'publicCommit', 'publicTree', 'tagObject', 'files', 'issuedAt', 'keyId'])
+      || s.schemaVersion !== 1 || !matches(s.publisher, namespace) || !validProject(s.project)
+      || !s.project.startsWith(s.publisher + '/') || !version(s.version) || s.tag !== 'v' + s.version
+      || !matches(s.repository, repositoryPattern) || ['.', '..'].includes(s.repository.split('/')[4])
+      || !matches(s.publicCommit, hex40) || !matches(s.publicTree, hex40) || !matches(s.tagObject, hex40)
+      || !instant(s.issuedAt) || !matches(s.keyId, keyPattern) || !Array.isArray(s.files)) refuse('STATEMENT_INVALID');
+    if (s.files.length > LIMITS.files) refuse('INPUT_TOO_LARGE');
+    if (s.files.length < 4) refuse('STATEMENT_INVALID');
+    let previous = '';
+    for (const f of s.files) {
+      if (!shape(f, ['path', 'sha256', 'size']) || !safePath(f.path) || !matches(f.sha256, hex64)
+        || !Number.isSafeInteger(f.size) || f.size < 0 || f.path <= previous) refuse('STATEMENT_INVALID');
+      if (f.size > LIMITS.fileBytes) refuse('INPUT_TOO_LARGE');
+      previous = f.path;
+    }
+    const releases = s.files.filter(f => /^site\/[^/]+\/[^/]+\/release\.json$/.test(f.path));
+    if (releases.length !== 1 || releases[0].path.split('/')[2] !== s.version) refuse('STATEMENT_INVALID');
+    const prefix = releases[0].path.slice(0, -'release.json'.length);
+    if (requiredFiles.some(path => !s.files.some(f => f.path === path))
+      || s.files.some(f => f.path.startsWith('site/') && !f.path.startsWith(prefix))) refuse('STATEMENT_INVALID');
+  } catch (error) { sanitized(error, 'STATEMENT_INVALID'); }
+}
+function parseJSON(value, code) {
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(value)); } catch { refuse(code); }
+}
+function envelopeParts(envelope, type) {
+  if (!shape(envelope, ['payloadType', 'payload', 'signatures']) || envelope.payloadType !== type
+    || !Array.isArray(envelope.signatures) || envelope.signatures.length !== 1
+    || !shape(envelope.signatures[0], ['keyid', 'sig']) || !matches(envelope.signatures[0].keyid, keyPattern)) refuse('ENVELOPE_INVALID');
+  const payload = unb64(envelope.payload), signature = unb64(envelope.signatures[0].sig);
+  if (signature.length !== 64) refuse('ENVELOPE_INVALID');
+  return { keyid: envelope.signatures[0].keyid, payload, signature };
+}
+function canonicalPayload(payload) {
+  const statement = parseJSON(payload, 'STATEMENT_NOT_CANONICAL');
+  let again;
+  try { again = canonicalBytes(statement); } catch { refuse('STATEMENT_NOT_CANONICAL'); }
+  if (again.length !== payload.length || again.some((byte, index) => byte !== payload[index])) refuse('STATEMENT_NOT_CANONICAL');
+  return statement;
+}
+async function checkSignature(key, type, payload, signature) {
+  try { if (await crypto.subtle.verify('Ed25519', key, signature, pae(type, payload))) return; } catch { /* Sanitized below. */ }
+  refuse('SIGNATURE_INVALID');
+}
+function freeze(value) {
+  if (value && typeof value === 'object') { for (const item of Object.values(value)) freeze(item); Object.freeze(value); }
+  return value;
+}
+function floors(value, publisher) {
+  return record(value) && Object.entries(value).every(([project, maximum]) => validProject(project)
+    && (!publisher || project.startsWith(publisher + '/')) && version(maximum));
+}
+// Returns a separate immutable snapshot. Only this module can create trusted anchors.
+// minimumSerial is the last accepted serial: equal and older imports are stale.
+export async function loadAnchors(raw, environment = 'production', options = {}) {
+  try {
+    if (!['production', 'test'].includes(environment) || !shape(options, [], ['minimumSerial'])
+      || (Object.hasOwn(options, 'minimumSerial') && (!Number.isSafeInteger(options.minimumSerial) || options.minimumSerial < 0))) refuse('ANCHORS_INVALID');
+    const anchors = raw instanceof Uint8Array ? parseJSON(raw, 'ANCHORS_INVALID')
+      : typeof raw === 'string' ? JSON.parse(raw) : JSON.parse(canonical(raw));
+    if (!shape(anchors, ['schemaVersion', 'environment', 'serial', 'legacyUnsigned', 'keys']) || anchors.schemaVersion !== 1
+      || anchors.environment !== environment || !Number.isSafeInteger(anchors.serial) || anchors.serial < 1
+      || !Array.isArray(anchors.keys) || !floors(anchors.legacyUnsigned)) refuse('ANCHORS_INVALID');
+    const lookup = new Map(), owners = new Map();
+    for (const k of anchors.keys) {
+      if (!shape(k, ['keyId', 'publicKey', 'publisher', 'githubOwner', 'notBefore', 'notAfter', 'status', 'enrolment', 'review'], ['retiredAt', 'compromisedAt', 'keepStatements'])
+        || !matches(k.keyId, keyPattern) || lookup.has(k.keyId) || !matches(k.publisher, namespace)
+        || !shape(k.githubOwner, ['login', 'id']) || !matches(k.githubOwner.login, namespace)
+        || !Number.isSafeInteger(k.githubOwner.id) || k.githubOwner.id <= 0 || !ascii(k.review)
+        || !instant(k.notBefore) || !instant(k.notAfter) || k.notBefore >= k.notAfter
+        || !['active', 'retired', 'compromised'].includes(k.status)) refuse('ANCHORS_INVALID');
+      const maximum = new Date(k.notBefore); maximum.setUTCFullYear(maximum.getUTCFullYear() + 2);
+      if (Date.parse(k.notAfter) > maximum.getTime()) refuse('ANCHORS_INVALID');
+      if ((k.status === 'retired' && !Object.hasOwn(k, 'retiredAt'))
+        || (k.status === 'active' && Object.hasOwn(k, 'retiredAt'))
+        || (k.status === 'compromised') !== Object.hasOwn(k, 'compromisedAt')
+        || (Object.hasOwn(k, 'retiredAt') && !instant(k.retiredAt))
+        || (Object.hasOwn(k, 'compromisedAt') && !instant(k.compromisedAt))
+        || (Object.hasOwn(k, 'keepStatements') && (k.status !== 'compromised' || !Array.isArray(k.keepStatements)
+          || k.keepStatements.some(hash => !matches(hash, hex64)) || new Set(k.keepStatements).size !== k.keepStatements.length))) refuse('ANCHORS_INVALID');
+      const owner = canonical(k.githubOwner);
+      if (owners.has(k.publisher) && owners.get(k.publisher) !== owner) refuse('ANCHORS_INVALID');
+      owners.set(k.publisher, owner);
+      const scope = k.keyId.split('-')[0], publicBytes = unb64(k.publicKey);
+      if ((environment === 'production' && scope !== 'rer') || publicBytes.length !== 32
+        || k.keyId !== await keyIdFor(scope, publicBytes)) refuse('ANCHORS_INVALID');
+      if (canonicalBytes(k.enrolment).length > LIMITS.envelopeBytes) refuse('ANCHORS_INVALID');
+      const { keyid, payload, signature } = envelopeParts(k.enrolment, ENROLMENT_TYPE);
+      if (keyid !== k.keyId) refuse('ANCHORS_INVALID');
+      const publicKey = await crypto.subtle.importKey('raw', publicBytes, 'Ed25519', false, ['verify']);
+      await checkSignature(publicKey, ENROLMENT_TYPE, payload, signature);
+      const claim = canonicalPayload(payload);
+      const claimFields = ['schemaVersion', 'keyId', 'publicKey', 'publisher', 'githubOwner', 'notBefore', 'notAfter', 'issuedAt', 'unsignedThrough'];
+      if (!shape(claim, claimFields) || claim.schemaVersion !== 1 || !instant(claim.issuedAt) || !floors(claim.unsignedThrough, k.publisher)
+        || ['keyId', 'publicKey', 'publisher', 'notBefore', 'notAfter'].some(field => claim[field] !== k[field])
+        || canonical(claim.githubOwner) !== owner) refuse('ANCHORS_INVALID');
+      k.unsignedThrough = claim.unsignedThrough;
+      lookup.set(k.keyId, { anchor: k, publicKey });
+    }
+    if (Object.keys(anchors.legacyUnsigned).some(project => owners.has(project.split('/')[0]))) refuse('ANCHORS_INVALID');
+    if (options.minimumSerial !== undefined && anchors.serial <= options.minimumSerial) refuse('ANCHORS_STALE');
+    freeze(anchors); trusted.set(anchors, lookup); return anchors;
+  } catch (error) { if (error instanceof Refusal && error.code === 'ANCHORS_STALE') throw error; refuse('ANCHORS_INVALID'); }
+}
+function contextRecord(context) {
+  if (!record(context)) refuse('STATEMENT_INVALID');
+  const allowed = ['environment', 'now', 'expect', 'files', 'checkPaths', 'highest', 'unsigned'];
+  if (Reflect.ownKeys(context).some(key => typeof key !== 'string' || !allowed.includes(key)
+    || !('value' in Object.getOwnPropertyDescriptor(context, key)))) refuse('STATEMENT_INVALID');
+  return { ...context };
+}
+function expectedSubject(expect, statement) {
+  if (expect === undefined) return;
+  const fields = ['publisher', 'project', 'version', 'repository', 'tag', 'publicCommit', 'publicTree', 'tagObject'];
+  const valid = (field, value) => field === 'publisher' ? matches(value, namespace)
+    : field === 'project' ? validProject(value) : field === 'version' ? version(value)
+      : field === 'repository' ? matches(value, repositoryPattern) : field === 'tag' ? typeof value === 'string' && value.startsWith('v') && version(value.slice(1))
+        : matches(value, hex40);
+  if (!shape(expect, [], fields) || Object.entries(expect).some(([field, value]) => !valid(field, value)
+    || (statement !== undefined && statement[field] !== value))) refuse('SUBJECT_MISMATCH');
+}
+function versionOrder(highest, versionValue, digest) {
+  if (highest === undefined) return;
+  if (!shape(highest, ['version', 'statementSha256']) || !version(highest.version) || !matches(highest.statementSha256, hex64)) refuse('STATEMENT_INVALID');
+  const order = compareVersion(versionValue, highest.version);
+  if (order < 0) refuse('VERSION_ROLLBACK');
+  if (order === 0 && digest !== highest.statementSha256) refuse('VERSION_REUSED');
+}
+async function checkFiles(statement, context) {
+  if (context.checkPaths !== undefined && typeof context.checkPaths !== 'function') refuse('PATH_UNSAFE');
+  if (context.files === undefined) {
+    return;
+  }
+  if (!(context.files instanceof Map)) refuse('PATH_UNSAFE');
+  if (context.files.size > LIMITS.files) refuse('INPUT_TOO_LARGE');
+  const files = new Map(context.files), selected = new Map();
+  const select = path => {
+    if (!selected.has(path)) {
+      let answer;
+      try { answer = context.checkPaths === undefined ? true : context.checkPaths(path); } catch { refuse('PATH_UNSAFE'); }
+      if (typeof answer !== 'boolean') refuse('PATH_UNSAFE');
+      selected.set(path, answer);
+    }
+    return selected.get(path);
+  };
+  for (const [path, value] of files) {
+    if (!safePath(path) || !(value instanceof Uint8Array)) refuse('PATH_UNSAFE');
+    if (value.byteLength > LIMITS.fileBytes) refuse('INPUT_TOO_LARGE');
+  }
+  for (const entry of statement.files) {
+    if (!select(entry.path)) continue;
+    if (!files.has(entry.path)) refuse('FILE_MISSING');
+    const value = files.get(entry.path);
+    if (value.byteLength !== entry.size || await sha256(value) !== entry.sha256) refuse('DIGEST_MISMATCH');
+  }
+  const declared = new Set(statement.files.map(entry => entry.path));
+  for (const path of files.keys()) if (select(path) && !declared.has(path)) refuse('FILE_UNDECLARED');
+}
+// Context omits files for service admission, or selects site/ paths for a site
+// build. Base passes all artifact files. Input failures never expose contents.
+export async function verifyRelease(envelopeBytes, loadedAnchors, input = {}) {
+  try {
+    // Release failures follow the spec's order: size, envelope, scope, lookup,
+    // signature, canonical bytes, schema, identity, time, subject, files, version.
+    let parts;
+    if (envelopeBytes !== null) {
+      bytes(envelopeBytes, 'ENVELOPE_INVALID');
+      if (envelopeBytes.byteLength > LIMITS.envelopeBytes) refuse('INPUT_TOO_LARGE');
+      parts = envelopeParts(parseJSON(envelopeBytes, 'ENVELOPE_INVALID'), PAYLOAD_TYPE);
+    }
+    const context = contextRecord(input);
+    const environment = context.environment === undefined ? 'production' : context.environment;
+    if (!['production', 'test'].includes(environment)) refuse('ANCHORS_INVALID');
+    if (parts && environment === 'production' && parts.keyid.startsWith('test-')) refuse('KEY_TEST_REFUSED');
+    if (!trusted.has(loadedAnchors) || loadedAnchors.environment !== environment) refuse('ANCHORS_INVALID');
+    if (!parts) {
+      const unsigned = context.unsigned;
+      if (unsigned === undefined) refuse('SIGNATURE_MISSING');
+      if (!shape(unsigned, ['project', 'version']) || !validProject(unsigned.project) || !version(unsigned.version)) refuse('STATEMENT_INVALID');
+      // A legacy floor authenticates no bytes or Git subjects. Callers retain
+      // their existing pins; these optional inputs still must be well formed.
+      expectedSubject(context.expect);
+      if (context.files !== undefined || context.checkPaths !== undefined) {
+        // Bytes are not authenticated by a legacy floor, but malformed inputs still fail closed.
+        if ((context.files !== undefined && !(context.files instanceof Map)) || (context.checkPaths !== undefined && typeof context.checkPaths !== 'function')) refuse('PATH_UNSAFE');
+        if (context.files?.size > LIMITS.files) refuse('INPUT_TOO_LARGE');
+        for (const [path, value] of context.files ?? []) {
+          if (!safePath(path) || !(value instanceof Uint8Array)) refuse('PATH_UNSAFE');
+          if (value.byteLength > LIMITS.fileBytes) refuse('INPUT_TOO_LARGE');
+        }
+      }
+      if (context.now !== undefined && (!Number.isSafeInteger(context.now) || Math.abs(context.now) > 8640000000000000)) refuse('STATEMENT_INVALID');
+      const keys = loadedAnchors.keys.filter(key => key.publisher === unsigned.project.split('/')[0]);
+      const ceilings = keys.length ? keys.map(key => key.unsignedThrough[unsigned.project]) : [loadedAnchors.legacyUnsigned[unsigned.project]];
+      if (!ceilings.some(ceiling => ceiling !== undefined && compareVersion(unsigned.version, ceiling) <= 0)) refuse('SIGNATURE_MISSING');
+      versionOrder(context.highest, unsigned.version, undefined);
+      return { verdict: 'UNSIGNED_LEGACY', project: unsigned.project, version: unsigned.version };
+    }
+    const found = trusted.get(loadedAnchors).get(parts.keyid);
+    if (!found) refuse('KEY_UNKNOWN');
+    await checkSignature(found.publicKey, PAYLOAD_TYPE, parts.payload, parts.signature);
+    const statement = canonicalPayload(parts.payload);
+    validateStatement(statement);
+    if (statement.keyId !== parts.keyid) refuse('STATEMENT_INVALID');
+    const anchor = found.anchor;
+    if (statement.publisher !== anchor.publisher || statement.repository.split('/')[3] !== anchor.githubOwner.login) refuse('PUBLISHER_MISMATCH');
+    const statementSha256 = await sha256(parts.payload);
+    const now = context.now === undefined ? Date.now() : context.now;
+    if (!Number.isSafeInteger(now) || Math.abs(now) > 8640000000000000) refuse('STATEMENT_INVALID');
+    const issued = Date.parse(statement.issuedAt);
+    if (issued > now + 300000) refuse('ISSUED_IN_FUTURE');
+    if (issued < Date.parse(anchor.notBefore) || issued >= Date.parse(anchor.notAfter)) refuse('KEY_OUTSIDE_VALIDITY');
+    if (anchor.status === 'retired' && issued >= Date.parse(anchor.retiredAt)) refuse('KEY_RETIRED');
+    if (anchor.status === 'compromised' && !(anchor.keepStatements ?? []).includes(statementSha256)) refuse('KEY_REVOKED');
+    if (context.unsigned !== undefined && (!shape(context.unsigned, ['project', 'version'])
+      || context.unsigned.project !== statement.project || context.unsigned.version !== statement.version)) refuse('SUBJECT_MISMATCH');
+    expectedSubject(context.expect, statement);
+    await checkFiles(statement, context);
+    versionOrder(context.highest, statement.version, statementSha256);
+    return { verdict: 'VERIFIED', statementSha256, keyId: parts.keyid, publisher: statement.publisher, project: statement.project, version: statement.version };
+  } catch (error) { sanitized(error, 'STATEMENT_INVALID'); }
+}

package/modules/release/signing-cli.mjs

@@ -0,0 +1,56 @@
+import { Refusal, validProject } from './signature.mjs';
+
+const semver = '(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)';
+const versionOK = value => new RegExp(`^${semver}$`).test(value) && value.split('.').every(part => Number.isSafeInteger(Number(part)));
+const dateOK = value => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value.replace('Z', '.000Z');
+function parse(verb, args) {
+  const fields = { sign: ['artifact', 'key-file', 'scope'], receipt: ['artifact', 'anchors', 'environment', 'after'],
+    keygen: ['scope', 'publisher', 'github-owner', 'github-owner-id', 'anchor-out', 'not-before', 'not-after', 'unsigned-through'] }[verb];
+  const options = { unsignedThrough: {} };
+  const invalid = () => { throw new TypeError('ARGUMENT_INVALID'); };
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (verb === 'sign' && flag === '--key-stdin' && !options['key-stdin']) { options['key-stdin'] = true; continue; }
+    if (!flag.startsWith('--') || !fields.includes(flag.slice(2))) invalid();
+    const name = flag.slice(2), value = args[++index];
+    if (!value || value.startsWith('--') || (name !== 'unsigned-through' && options[name] !== undefined)) invalid();
+    if (name === 'unsigned-through') {
+      const match = new RegExp(`^(.+):(${semver})$`).exec(value);
+      if (!match || !validProject(match[1]) || !versionOK(match[2]) || Object.hasOwn(options.unsignedThrough, match[1])) invalid();
+      options.unsignedThrough[match[1]] = match[2];
+    } else options[name] = value;
+  }
+  if (options.scope !== undefined && !['test', 'rer'].includes(options.scope)) invalid();
+  if (verb === 'receipt' && (!options.artifact || !options.anchors || (options.environment !== undefined && options.environment !== 'test') || (options.after && (!new RegExp(`^${semver}:[a-f0-9]{64}$`).test(options.after) || !versionOK(options.after.split(':')[0]))))) invalid();
+  if (verb === 'sign' && (!options.artifact || Boolean(options['key-file']) === Boolean(options['key-stdin']))) invalid();
+  if (verb === 'keygen') {
+    if (!options.scope || !options['anchor-out'] || !/^[a-z0-9][a-z0-9-]{0,38}$/.test(options.publisher ?? '') || !/^[a-z0-9][a-z0-9-]{0,38}$/.test(options['github-owner'] ?? '') || !/^[1-9]\d*$/.test(options['github-owner-id'] ?? '') || !Number.isSafeInteger(Number(options['github-owner-id']))) invalid();
+    for (const name of ['not-before', 'not-after']) if (options[name] !== undefined && !dateOK(options[name])) invalid();
+    const start = new Date(options['not-before'] ?? Date.now()), maximum = new Date(start);
+    maximum.setUTCFullYear(maximum.getUTCFullYear() + 2);
+    if (options['not-after'] && (Date.parse(options['not-after']) <= start.getTime() || Date.parse(options['not-after']) > maximum.getTime())) invalid();
+    if (Object.keys(options.unsignedThrough).some(project => !project.startsWith(options.publisher + '/'))) invalid();
+    if (process.stdout.isTTY) invalid();
+  }
+  return options;
+}
+
+export async function dispatchSigning(verb, args) {
+  let options;
+  try { options = parse(verb, args); }
+  catch { console.log(JSON.stringify({ verdict: 'REFUSED', code: 'ARGUMENT_INVALID' })); return 2; }
+  if (verb === 'sign' && options['key-stdin'] && process.stdin.isTTY) {
+    console.log(JSON.stringify({ verdict: 'REFUSED', code: 'ARGUMENT_INVALID', message: 'Pipe the private key from a vault or file; --key-stdin does not accept terminal input.' }));
+    return 2;
+  }
+  try {
+    if (verb === 'sign') console.log(await (await import('./sign.mjs')).signArtifact(options));
+    else if (verb === 'keygen') await (await import('./keygen.mjs')).keygen(options);
+    else { await (await import('./verify.mjs')).receipt(options); console.log(JSON.stringify({ verdict: 'VERIFIED' })); }
+    return 0;
+  } catch (error) {
+    const code = error instanceof Refusal ? error.code : 'STATEMENT_INVALID';
+    console.log(JSON.stringify({ verdict: 'REFUSED', code }));
+    return 1;
+  }
+}

package/modules/release/signing-io.mjs

@@ -0,0 +1,61 @@
+import { constants, lstatSync, openSync, closeSync, readSync, writeFileSync, fstatSync } from 'node:fs';
+import { resolve, dirname, parse } from 'node:path';
+import { Refusal } from './signature.mjs';
+
+export const SIGNATURE_FILE = 'rer-release.dsse.json';
+export const FILE_LIMIT = 1024 ** 3;
+export function refuse(code) { throw new Refusal(code); }
+
+// Check every parent too: O_NOFOLLOW alone only protects the final component.
+export function safePath(path, { missing = false } = {}) {
+  const absolute = resolve(path), root = parse(absolute).root;
+  let current = root;
+  for (const part of absolute.slice(root.length).split('/').filter(Boolean)) {
+    current = resolve(current, part);
+    let stat;
+    try { stat = lstatSync(current); }
+    catch (error) {
+      if (error.code === 'ENOENT' && missing && current === absolute) return absolute;
+      refuse('FILE_MISSING');
+    }
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile()) || (current !== absolute && !stat.isDirectory())) refuse('PATH_UNSAFE');
+  }
+  return absolute;
+}
+
+export function readBounded(path, limit = FILE_LIMIT) {
+  const absolute = safePath(path);
+  let fd;
+  try {
+    const before = lstatSync(absolute);
+    if (!before.isFile()) refuse('PATH_UNSAFE');
+    if (before.size > limit) refuse('INPUT_TOO_LARGE');
+    fd = openSync(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) refuse('PATH_UNSAFE');
+    if (stat.size > limit) refuse('INPUT_TOO_LARGE');
+    // A bounded read also prevents a concurrently growing file from exhausting memory.
+    const bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (!count) refuse('DIGEST_MISMATCH');
+      offset += count;
+    }
+    const after = fstatSync(fd);
+    if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) refuse('DIGEST_MISMATCH');
+    return bytes;
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+export function writeNew(path, bytes) {
+  safePath(dirname(resolve(path)));
+  safePath(path, { missing: true });
+  // Exclusive creation never replaces another receipt, key entry or symlink.
+  try { writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 }); }
+  catch { refuse('PATH_UNSAFE'); }
+}
+
+export function parseJSON(bytes, code = 'STATEMENT_INVALID') {
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)); } catch { refuse(code); }
+}

package/modules/release/signing-key.mjs

@@ -0,0 +1,22 @@
+import { createPublicKey, sign } from 'node:crypto';
+import { b64, canonicalBytes, pae, keyIdFor, ENROLMENT_TYPE } from './signature.mjs';
+
+export const timestamp = date => date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+export function validity(now = new Date()) {
+  const start = new Date(timestamp(now)), end = new Date(start);
+  end.setUTCFullYear(end.getUTCFullYear() + 2);
+  return { notBefore: timestamp(start), notAfter: timestamp(end) };
+}
+export function envelope(privateKey, keyId, type, claim) {
+  const payload = canonicalBytes(claim);
+  return { payloadType: type, payload: b64(payload), signatures: [{ keyid: keyId, sig: b64(sign(null, pae(type, payload), privateKey)) }] };
+}
+export async function publicEntry(privateKey, { scope, publisher, githubOwner, notBefore, notAfter, unsignedThrough = {}, issuedAt = timestamp(new Date()) }) {
+  const jwk = createPublicKey(privateKey).export({ format: 'jwk' });
+  const raw = Buffer.from(jwk.x, 'base64url');
+  const keyId = await keyIdFor(scope, raw), publicKey = b64(raw);
+  const claim = { schemaVersion: 1, keyId, publicKey, publisher, githubOwner, notBefore, notAfter, issuedAt, unsignedThrough };
+  return { keyId, publicKey, publisher, githubOwner, notBefore, notAfter, status: 'active',
+    enrolment: envelope(privateKey, keyId, ENROLMENT_TYPE, claim), review: 'pending' };
+}
+export const anchorSet = (entry, scope) => ({ schemaVersion: 1, environment: scope === 'test' ? 'test' : 'production', serial: 1, legacyUnsigned: {}, keys: [entry] });

package/modules/release/statement.mjs

@@ -0,0 +1,80 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { resolve, posix } from 'node:path';
+import { sha256, validateStatement, validRelativePath as pathOK } from './signature.mjs';
+import { FILE_LIMIT, SIGNATURE_FILE, safePath, readBounded, parseJSON, refuse } from './signing-io.mjs';
+
+const required = ['public-source.tar', 'release-receipt.json', 'publish-check.json'];
+export function repositoryURL(value) {
+  if (typeof value !== 'string' || !/^https:\/\/github\.com\/[a-z0-9-]+\/[a-z0-9_.-]+(?:\.git)?$/i.test(value)) refuse('SUBJECT_MISMATCH');
+  return value.toLowerCase().replace(/\.git$/, '');
+}
+
+export async function readArtifact(directory) {
+  const root = safePath(directory);
+  if (!lstatSync(root).isDirectory()) refuse('PATH_UNSAFE');
+  const receiptBytes = readBounded(resolve(root, 'release-receipt.json'));
+  const receipt = parseJSON(receiptBytes);
+  const manifestPath = receipt?.siteRelease?.path;
+  if (!pathOK(manifestPath) || !/^site\/[a-z0-9]+(?:-[a-z0-9]+)*\/(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\/release\.json$/.test(manifestPath)) refuse('PATH_UNSAFE');
+  const base = posix.dirname(manifestPath);
+  const selected = new Map();
+  const walk = (relative = '') => {
+    for (const name of readdirSync(resolve(root, relative)).sort()) {
+      const path = relative ? `${relative}/${name}` : name;
+      const ancillary = path === 'public-git' || path.startsWith('public-git/');
+      // Unsigned source names may be Unicode; only the root Git metadata may
+      // use .git. Signed paths retain the statement's printable ASCII rules.
+      if (ancillary) {
+        if (path.includes('\0') || path.includes('\\') || path.split('/').some((part, index) =>
+          !part || part === '.' || part === '..' || (part === '.git' && index !== 1))) refuse('PATH_UNSAFE');
+      } else if (!pathOK(path)) refuse('PATH_UNSAFE');
+      const stat = lstatSync(resolve(root, path));
+      if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) refuse('PATH_UNSAFE');
+      if (stat.isFile() && stat.size > FILE_LIMIT) refuse('INPUT_TOO_LARGE');
+      if (stat.isDirectory()) {
+        if (!ancillary && path !== 'site' && path !== posix.dirname(base) && path !== base && path !== `${base}/documents` && !path.startsWith(`${base}/documents/`)) refuse('FILE_UNDECLARED');
+        walk(path);
+      } else if (required.includes(path) || path === manifestPath || path.startsWith(`${base}/documents/`)) {
+        selected.set(path, stat.size);
+        if (selected.size > 256) refuse('INPUT_TOO_LARGE');
+      } else if (!ancillary && !['PUBLISH.md', 'site/registry.json', SIGNATURE_FILE].includes(path)) refuse('FILE_UNDECLARED');
+    }
+  };
+  walk();
+  for (const path of [...required, manifestPath]) if (!selected.has(path)) refuse('FILE_MISSING');
+  const files = new Map();
+  for (const path of [...selected.keys()].sort()) files.set(path, path === 'release-receipt.json' ? receiptBytes : readBounded(resolve(root, path)));
+  const manifest = parseJSON(files.get(manifestPath));
+  const publicExport = receipt.publicExport;
+  if (!publicExport || publicExport.path !== 'public-source.tar' || !manifest?.provenance || !manifest?.listing) refuse('SUBJECT_MISMATCH');
+  const subject = { publisher: manifest.project?.split('/')[0], project: manifest.project, version: manifest.release,
+    repository: repositoryURL(manifest.provenance.repository), tag: publicExport.tag,
+    publicCommit: publicExport.commit, publicTree: publicExport.tree, tagObject: publicExport.tagObject };
+  if (manifestPath !== `site/${manifest.listing.id}/${subject.version}/release.json` || manifest.listing.version !== subject.version || repositoryURL(manifest.listing.repository) !== subject.repository ||
+      manifest.provenance.revision !== subject.publicCommit || manifest.provenance.tree !== subject.publicTree || manifest.provenance.tag !== subject.tag || receipt.tag?.name !== subject.tag) refuse('SUBJECT_MISMATCH');
+  const entries = [];
+  for (const [path, bytes] of files) entries.push({ path, sha256: await sha256(bytes), size: bytes.length });
+  const digests = new Map(entries.map(entry => [entry.path, entry.sha256]));
+  const match = (path, digest) => { if (typeof digest !== 'string' || digests.get(path) !== digest) refuse('DIGEST_MISMATCH'); };
+  match('public-source.tar', publicExport.sha256);
+  match('publish-check.json', receipt.gates?.publishCheck?.reportSha256);
+  match(manifestPath, receipt.siteRelease.sha256);
+  if (!Array.isArray(manifest.artifacts)) refuse('STATEMENT_INVALID');
+  const declared = new Set();
+  for (const artifact of manifest.artifacts) {
+    if (!pathOK(artifact?.path) || !artifact.path.startsWith('documents/')) refuse('PATH_UNSAFE');
+    const path = `${base}/${artifact.path}`;
+    if (declared.has(path)) refuse('STATEMENT_INVALID');
+    declared.add(path);
+    if (!files.has(path)) refuse('FILE_MISSING');
+    match(path, artifact.sha256);
+  }
+  for (const path of files.keys()) if (path.startsWith(`${base}/documents/`) && !declared.has(path)) refuse('FILE_UNDECLARED');
+  return { root, receipt, subject, files, entries };
+}
+
+export function statementFor(artifact, keyId, issuedAt) {
+  const statement = { schemaVersion: 1, ...artifact.subject, files: artifact.entries, issuedAt, keyId };
+  validateStatement(statement);
+  return statement;
+}