@entrorove/skill 0.1.22 → 0.1.24

package/local-evidence-verification.mjs

@@ -0,0 +1,199 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+
+const EVIDENCE_SCHEMA = 'entrorove.test-evidence/2.0';
+const EXECUTION_SCHEMA = 'validator.execution-receipt/1.0';
+const GENERIC_SCHEMA = 'entrorove.runner-receipt/1.0';
+const KINDS = new Set(['test', 'build', 'lint', 'security', 'benchmark']);
+const RUNNERS = new Set(['local', 'trusted-runner', 'sandbox']);
+const SHA = /^[0-9a-f]{64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const FIELDS = new Set(['schemaVersion', 'evidenceId', 'kind', 'runner', 'command', 'exitCode', 'durationMs',
+  'summary', 'artifactSha256', 'subject', 'subjectDigest', 'receipt', 'flowId', 'stepId']);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const digest = value => createHash('sha256').update(value).digest('hex');
+const text = (value, max) => typeof value === 'string' && value.trim().length > 0 && value.length <= max;
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+
+function canonical(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (!object(value)) fail('ENTROROVE_EVIDENCE_JSON', 'Evidence must contain finite JSON values');
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+
+function state(status, details = {}) {
+  return { verified: false, authentic: false, successful: false, status, evidenceState: status, ...details };
+}
+
+function validateEvidence(evidence) {
+  if (!object(evidence) || Object.keys(evidence).some(key => !FIELDS.has(key)) || evidence.schemaVersion !== EVIDENCE_SCHEMA
+    || !text(evidence.evidenceId, 200) || !KINDS.has(evidence.kind) || !RUNNERS.has(evidence.runner)
+    || !text(evidence.command, 2000) || !Number.isInteger(evidence.exitCode) || evidence.exitCode < -128 || evidence.exitCode > 255
+    || !Number.isSafeInteger(evidence.durationMs) || evidence.durationMs < 0 || evidence.durationMs > 86_400_000
+    || !text(evidence.summary, 4000) || !SHA.test(String(evidence.artifactSha256 ?? ''))) {
+    fail('ENTROROVE_EVIDENCE_SCHEMA', 'Evidence schema is invalid');
+  }
+  canonical(evidence);
+}
+
+function publicKey(encoded) {
+  if (typeof encoded !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) fail('ENTROROVE_EVIDENCE_KEY', 'Independent receipt public key encoding is invalid');
+  const bytes = Buffer.from(encoded, 'base64');
+  if (bytes.toString('base64') !== encoded) fail('ENTROROVE_EVIDENCE_KEY', 'Receipt public key must use canonical base64');
+  let key; try { key = createPublicKey({ key: bytes, format: 'der', type: 'spki' }); }
+  catch { fail('ENTROROVE_EVIDENCE_KEY', 'Receipt public key is invalid'); }
+  if (key.asymmetricKeyType !== 'ed25519' || !key.export({ format: 'der', type: 'spki' }).equals(bytes)) {
+    fail('ENTROROVE_EVIDENCE_KEY', 'Receipt public key must be canonical Ed25519 SPKI');
+  }
+  return { key, keyId: digest(bytes) };
+}
+
+function verifySignature(receipt, payload, encoded) {
+  if (!object(receipt) || !SHA.test(String(receipt.keyId ?? '')) || typeof receipt.signature !== 'string'
+    || !/^[A-Za-z0-9_-]{86}$/.test(receipt.signature)) fail('ENTROROVE_EVIDENCE_SIGNATURE', 'Receipt signature fields are invalid');
+  const trusted = publicKey(encoded); const signature = Buffer.from(receipt.signature, 'base64url');
+  if (signature.length !== 64 || signature.toString('base64url') !== receipt.signature || trusted.keyId !== receipt.keyId
+    || (receipt.publicKey !== undefined && receipt.publicKey !== encoded)
+    || !verify(null, Buffer.from(canonical(payload)), trusted.key, signature)) {
+    fail('ENTROROVE_EVIDENCE_SIGNATURE', 'Receipt key identity or signature is invalid');
+  }
+  return trusted.keyId;
+}
+
+function receiptPayload(evidence) {
+  const receipt = evidence.receipt;
+  if (receipt?.schemaVersion === GENERIC_SCHEMA) return Object.fromEntries(Object.entries(evidence).filter(([key]) => key !== 'receipt'));
+  if (receipt?.schemaVersion !== EXECUTION_SCHEMA) fail('ENTROROVE_EVIDENCE_RECEIPT', 'Signed receipt schema is invalid');
+  if (!object(evidence.subject) || evidence.subjectDigest !== digest(canonical(evidence.subject))
+    || receipt.subjectDigest !== evidence.subjectDigest) fail('ENTROROVE_EVIDENCE_SUBJECT', 'Execution receipt subject digest is not bound');
+  return Object.fromEntries(Object.entries(receipt).filter(([key]) => key !== 'signature'));
+}
+
+function manifest(subject) {
+  if (!Array.isArray(subject.files) || !subject.files.length || subject.files.length > 512) fail('ENTROROVE_EVIDENCE_MANIFEST', 'Subject requires a nonempty bounded file manifest');
+  for (const [index, file] of subject.files.entries()) {
+    if (!object(file) || Object.keys(file).sort().join('|') !== 'path|sha256' || !text(file.path, 4096)
+      || file.path !== file.path.normalize('NFC') || file.path.startsWith('/') || /^[A-Za-z]:/.test(file.path)
+      || /[\\\u0000-\u001f\u007f]/.test(file.path) || file.path.split('/').some(part => !part || part === '.' || part === '..')
+      || !SHA.test(String(file.sha256 ?? '')) || (index > 0 && subject.files[index - 1].path >= file.path)) {
+      fail('ENTROROVE_EVIDENCE_MANIFEST', 'Subject manifest paths must be normalized, sorted and unique');
+    }
+  }
+  const actual = digest(`validator.file-manifest/1.0\n${subject.files.map(file => `${file.path}\0${file.sha256}`).join('\n')}`);
+  if (subject.artifactSha256 !== actual) fail('ENTROROVE_EVIDENCE_ARTIFACT', 'Subject artifact does not match its actual file manifest');
+}
+
+function validateSubject(evidence, options) {
+  const subject = evidence.subject; const policy = subject?.policy;
+  if (!object(subject) || subject.schemaVersion !== 'validator.validation-subject/1.0' || !object(policy)
+    || !ID.test(String(subject.planId ?? '')) || !ID.test(String(subject.validationRunId ?? ''))
+    || !text(subject.memberId, 128) || !ID.test(String(subject.chainId ?? '')) || !Number.isFinite(Date.parse(subject.executedAt))
+    || !SHA.test(String(evidence.subjectDigest ?? '')) || evidence.subjectDigest !== digest(canonical(subject))
+    || policy.command !== evidence.command || policy.requiredExitCode !== 0 || subject.artifactSha256 !== evidence.artifactSha256) {
+    fail('ENTROROVE_EVIDENCE_SUBJECT', 'Evidence command, artifact or validation subject is not bound');
+  }
+  manifest(subject);
+  const kind = policy.evidenceKind ?? 'test'; const runner = policy.evidenceRunner ?? 'trusted-runner';
+  if (!KINDS.has(kind) || !RUNNERS.has(runner) || evidence.kind !== kind || evidence.runner !== runner) {
+    fail('ENTROROVE_EVIDENCE_SEMANTICS', 'Evidence kind and runner must match signed policy');
+  }
+  if (!Array.isArray(subject.tests) || !subject.tests.length || subject.tests.some(item => !object(item)
+    || !ID.test(String(item.testId ?? '')) || !subject.files.some(file => file.path === item.path))) {
+    fail('ENTROROVE_EVIDENCE_TESTS', 'Subject tests must be bound to manifest files');
+  }
+  validateBaseline(subject);
+  validateBinding(evidence, subject, options);
+  if (options.expectedSubject !== undefined && canonical(options.expectedSubject) !== canonical(subject)) {
+    fail('ENTROROVE_EVIDENCE_SUBJECT', 'Evidence belongs to a different expected subject');
+  }
+  return subject;
+}
+
+function validateBaseline(subject) {
+  const baseline = subject.goldenBaseline; const source = baseline?.source;
+  if (!object(baseline) || baseline.schemaVersion !== 'validator.golden-baseline/1.0' || baseline.frozen !== true
+    || !ID.test(String(baseline.baselineId ?? '')) || !ID.test(String(baseline.version ?? ''))
+    || !ID.test(String(baseline.frozenBy ?? '')) || !Number.isFinite(Date.parse(baseline.frozenAt))
+    || !object(source) || !['repository-commit', 'artifact', 'approved-record'].includes(source.kind)
+    || !text(source.locator, 4096) || !SHA.test(String(source.digestSha256 ?? ''))
+    || baseline.testsSha256 !== digest(canonical(subject.tests))) fail('ENTROROVE_EVIDENCE_BASELINE', 'A frozen traceable baseline must bind the actual subject tests');
+}
+
+function validateBinding(evidence, subject, options) {
+  const workflow = subject.policy.workflowBinding;
+  if (workflow !== undefined && !object(workflow)) fail('ENTROROVE_EVIDENCE_BINDING', 'Signed workflow binding is invalid');
+  const values = { flowId: workflow?.flowId ?? subject.chainId, stepId: workflow?.stepId ?? subject.validationRunId,
+    snapshotDigest: subject.contracts?.aimlock?.snapshotSha256 ?? subject.snapshotDigest,
+    contractDigest: subject.contracts?.archguard?.contractSha256 ?? subject.contractDigest };
+  if (!ID.test(String(values.flowId ?? '')) || !ID.test(String(values.stepId ?? ''))) fail('ENTROROVE_EVIDENCE_BINDING', 'Signed flow and step are required');
+  for (const field of ['flowId', 'stepId']) {
+    if (evidence[field] !== undefined && evidence[field] !== values[field]) fail('ENTROROVE_EVIDENCE_BINDING', 'Outer evidence flow or step differs from signed subject');
+  }
+  for (const field of ['snapshotDigest', 'contractDigest']) {
+    if (subject[field] !== undefined && subject[field] !== values[field]) fail('ENTROROVE_EVIDENCE_BINDING', 'Subject has conflicting contract digest bindings');
+  }
+  const binding = options.binding ?? {};
+  for (const field of ['flowId', 'stepId', 'snapshotDigest', 'contractDigest']) {
+    if ((options.requireBinding || binding[field] !== undefined) && (binding[field] === undefined || values[field] !== binding[field]
+      || (field.endsWith('Digest') && !SHA.test(String(values[field] ?? ''))))) {
+      fail('ENTROROVE_EVIDENCE_BINDING', `Evidence is not bound to requested ${field}`);
+    }
+  }
+  for (const field of ['artifactSha256', 'subjectDigest']) {
+    if (binding[field] !== undefined && evidence[field] !== binding[field]) fail('ENTROROVE_EVIDENCE_BINDING', `Evidence ${field} does not match requested subject`);
+  }
+}
+
+function executionResult(evidence, subject, now) {
+  const receipt = evidence.receipt; const result = receipt.result;
+  const issued = Date.parse(receipt.issuedAt); const expires = Date.parse(receipt.expiresAt);
+  if (!ID.test(String(receipt.nonce ?? '')) || !Number.isFinite(issued) || !Number.isFinite(expires)
+    || issued > now + 60_000 || expires <= now || expires <= issued || expires - issued > 600_000) {
+    fail('ENTROROVE_EVIDENCE_LIFETIME', 'Execution receipt lifetime or nonce is invalid');
+  }
+  if (!object(result) || result.runner !== 'trusted-runner' || typeof result.passed !== 'boolean'
+    || result.exitCode !== evidence.exitCode || result.durationMs !== evidence.durationMs || result.summary !== evidence.summary) {
+    fail('ENTROROVE_EVIDENCE_RESULT', 'Execution receipt result is not bound to evidence');
+  }
+  if (subject.execution !== undefined) {
+    const execution = subject.execution;
+    if (!object(execution) || (execution.exitCode === null ? 1 : execution.exitCode) !== evidence.exitCode || typeof execution.timedOut !== 'boolean'
+      || typeof execution.outputLimitExceeded !== 'boolean' || (execution.signal !== null && !text(execution.signal, 64))) {
+      fail('ENTROROVE_EVIDENCE_RESULT', 'Signed process result is invalid');
+    }
+    const passed = execution.exitCode === 0 && execution.signal === null && !execution.timedOut && !execution.outputLimitExceeded;
+    if (passed !== result.passed) fail('ENTROROVE_EVIDENCE_RESULT', 'Receipt passed flag differs from signed process result');
+  }
+  if (result.passed && evidence.exitCode !== 0) fail('ENTROROVE_EVIDENCE_RESULT', 'Successful receipt must exit zero');
+  return result.passed && evidence.exitCode === 0;
+}
+
+export function verifyEvidenceIntegrity(evidence, options = {}) {
+  try {
+    validateEvidence(evidence); const receipt = evidence.receipt; const payload = receiptPayload(evidence);
+    const keyId = verifySignature(receipt, payload, options.publicKey ?? receipt?.publicKey);
+    if (receipt.schemaVersion === EXECUTION_SCHEMA) {
+      const subject = validateSubject(evidence, options);
+      executionResult(evidence, subject, options.now ?? Date.now());
+    }
+    return state('incomplete', { authentic: true, integrity: 'verified', keyId, evidence,
+      reason: 'Signature integrity alone does not establish independent successful execution' });
+  } catch (error) { return state('blocked', { integrity: 'invalid', code: error.code ?? 'ENTROROVE_EVIDENCE_INVALID', reason: error.message }); }
+}
+
+export function verifyTestEvidence(evidence, options = {}) {
+  try {
+    validateEvidence(evidence);
+    if (evidence.runner === 'local' || !options.publicKey) return state('incomplete', { evidence,
+      reason: 'Local evidence or an unconfigured independent verifier cannot establish trusted execution' });
+    const now = options.now ?? Date.now();
+    if (!Number.isSafeInteger(now) || now < 0) fail('ENTROROVE_EVIDENCE_TIME', 'Trusted verification time is invalid');
+    const payload = receiptPayload(evidence); const keyId = verifySignature(evidence.receipt, payload, options.publicKey);
+    if (evidence.receipt.schemaVersion === GENERIC_SCHEMA) return state('incomplete', { authentic: true, integrity: 'verified', keyId, evidence,
+      reason: 'Generic signatures have no signed execution lifetime or result authority' });
+    const subject = validateSubject(evidence, options); const successful = executionResult(evidence, subject, now);
+    return state(successful ? 'verified' : 'blocked', { verified: true, authentic: true, successful, keyId, evidence,
+      integrity: 'verified', reason: successful ? 'Independent signed execution passed' : 'Independent signed execution failed' });
+  } catch (error) { return state('blocked', { code: error.code ?? 'ENTROROVE_EVIDENCE_INVALID', reason: error.message }); }
+}