@emilia-protocol/gate 0.19.0 → 0.20.0

package/src/receipt-census.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Governed-taxonomy aggregate receipt census with coarse primary suppression. */
+import { RISK_DIGEST, riskDigest, riskExact, riskIdentifier, riskInstant, riskRecord, riskFreeze, type RiskRecord } from './reliance-risk-crypto.js';
+
+export const RECEIPT_CENSUS_VERSION = 'EP-RECEIPT-CENSUS-v1';
+export const RECEIPT_CENSUS_CLAIM_BOUNDARY = 'aggregate_observation_with_primary_suppression_not_differential_privacy_or_identifier_detection_not_causation_coverage_legal_liability_adjudication_solvency_payment_population_completeness_or_authorization';
+const PERIOD_KEYS = ['start', 'end'] as const;
+const PROGRAM_KEYS = ['program_id', 'version', 'source_digest', 'program_digest'] as const;
+const BUCKET_KEYS = ['action_class', 'program_version', 'outcome', 'count', 'open_exposure_amount_minor', 'reported_loss_amount_minor', 'currency'] as const;
+const BODY_KEYS = ['@version', 'census_id', 'relying_party_id', 'period', 'program', 'taxonomy_digest', 'minimum_bucket_count', 'buckets', 'suppressed', 'source_inventory_digest', 'generated_at', 'claim_boundary'] as const;
+
+export interface ReceiptCensusTaxonomy {
+  taxonomy_id: string;
+  allowed_action_classes: readonly string[];
+  allowed_outcomes: readonly string[];
+}
+
+const utf8 = new TextEncoder();
+
+function utf8ByteCompare(left: string, right: string): number {
+  const a = utf8.encode(left);
+  const b = utf8.encode(right);
+  const length = Math.min(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return a.length - b.length;
+}
+
+function normalizeTaxonomy(value: unknown): RiskRecord {
+  if (!riskExact(value, ['taxonomy_id', 'allowed_action_classes', 'allowed_outcomes'])
+      || !riskIdentifier(value.taxonomy_id)
+      || !Array.isArray(value.allowed_action_classes) || value.allowed_action_classes.length < 1
+      || value.allowed_action_classes.length > 10_000
+      || !value.allowed_action_classes.every(riskIdentifier)
+      || new Set(value.allowed_action_classes).size !== value.allowed_action_classes.length
+      || !Array.isArray(value.allowed_outcomes) || value.allowed_outcomes.length < 1
+      || value.allowed_outcomes.length > 1_000
+      || !value.allowed_outcomes.every(riskIdentifier)
+      || new Set(value.allowed_outcomes).size !== value.allowed_outcomes.length) {
+    throw new TypeError('receipt census taxonomy is invalid');
+  }
+  return {
+    taxonomy_id: value.taxonomy_id,
+    allowed_action_classes: [...value.allowed_action_classes].sort(utf8ByteCompare),
+    allowed_outcomes: [...value.allowed_outcomes].sort(utf8ByteCompare),
+  };
+}
+
+export function receiptCensusTaxonomyDigest(taxonomy: ReceiptCensusTaxonomy): string {
+  return riskDigest(normalizeTaxonomy(taxonomy));
+}
+
+function money(value: unknown): value is string { return typeof value === 'string' && /^(?:0|[1-9][0-9]{0,39})$/.test(value); }
+function validProgram(value: unknown): value is RiskRecord {
+  return riskExact(value, PROGRAM_KEYS) && riskIdentifier(value.program_id)
+    && Number.isSafeInteger(value.version) && value.version >= 1
+    && RISK_DIGEST.test(value.source_digest) && RISK_DIGEST.test(value.program_digest);
+}
+function validBucket(value: unknown): value is RiskRecord {
+  return riskExact(value, BUCKET_KEYS) && riskIdentifier(value.action_class)
+    && Number.isSafeInteger(value.program_version) && value.program_version >= 1
+    && riskIdentifier(value.outcome) && Number.isSafeInteger(value.count) && value.count >= 0
+    && money(value.open_exposure_amount_minor) && money(value.reported_loss_amount_minor)
+    && typeof value.currency === 'string' && /^[A-Z]{3}$/.test(value.currency);
+}
+
+function bucketKey(bucket: RiskRecord): string {
+  return JSON.stringify([
+    bucket.action_class,
+    bucket.program_version,
+    bucket.outcome,
+    bucket.currency,
+  ]);
+}
+
+function uniqueSortedBuckets(buckets: RiskRecord[]): boolean {
+  let prior: string | null = null;
+  for (const bucket of buckets) {
+    const current = bucketKey(bucket);
+    if (prior !== null && utf8ByteCompare(prior, current) >= 0) return false;
+    prior = current;
+  }
+  return true;
+}
+
+export function createReceiptCensus(input: RiskRecord, taxonomy: ReceiptCensusTaxonomy): RiskRecord {
+  const normalizedTaxonomy = normalizeTaxonomy(taxonomy);
+  const allowedActionClasses = new Set(normalizedTaxonomy.allowed_action_classes as string[]);
+  const allowedOutcomes = new Set(normalizedTaxonomy.allowed_outcomes as string[]);
+  const allowedInput = ['census_id', 'relying_party_id', 'period', 'program', 'minimum_bucket_count', 'buckets', 'source_inventory_digest', 'generated_at'];
+  if (!riskExact(input, allowedInput) || !riskIdentifier(input.census_id) || !riskIdentifier(input.relying_party_id)
+      || !riskExact(input.period, PERIOD_KEYS) || !validProgram(input.program)
+      || !Number.isSafeInteger(input.minimum_bucket_count) || input.minimum_bucket_count < 2
+      || input.minimum_bucket_count > 1000 || !Array.isArray(input.buckets) || input.buckets.length > 10_000
+      || !input.buckets.every(validBucket) || !RISK_DIGEST.test(input.source_inventory_digest)
+      || !Number.isFinite(riskInstant(input.generated_at))) throw new TypeError('receipt census input or bucket fields are invalid');
+  if (!input.buckets.every((bucket: RiskRecord) => allowedActionClasses.has(bucket.action_class)
+      && allowedOutcomes.has(bucket.outcome) && bucket.program_version === input.program.version)) {
+    throw new TypeError('receipt census bucket is outside the relying-party taxonomy');
+  }
+  const start = riskInstant(input.period.start); const end = riskInstant(input.period.end);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start || riskInstant(input.generated_at) < end) {
+    throw new TypeError('receipt census period is invalid');
+  }
+  const keys = input.buckets.map((bucket: RiskRecord) => bucketKey(bucket));
+  if (new Set(keys).size !== keys.length) throw new TypeError('receipt census contains duplicate bucket identities');
+  const visible = input.buckets
+    .filter((bucket: RiskRecord) => bucket.count >= input.minimum_bucket_count)
+    .map((bucket: RiskRecord) => ({ ...bucket }))
+    .sort((left: RiskRecord, right: RiskRecord) => utf8ByteCompare(bucketKey(left), bucketKey(right)));
+  const hidden = input.buckets.filter((bucket: RiskRecord) => bucket.count < input.minimum_bucket_count);
+  const body = {
+    '@version': RECEIPT_CENSUS_VERSION,
+    census_id: input.census_id,
+    relying_party_id: input.relying_party_id,
+    period: input.period,
+    program: input.program,
+    taxonomy_digest: riskDigest(normalizedTaxonomy),
+    minimum_bucket_count: input.minimum_bucket_count,
+    buckets: visible,
+    suppressed: { bucket_count: hidden.length, record_count: hidden.reduce((sum: number, bucket: RiskRecord) => sum + bucket.count, 0) },
+    source_inventory_digest: input.source_inventory_digest,
+    generated_at: input.generated_at,
+    claim_boundary: RECEIPT_CENSUS_CLAIM_BOUNDARY,
+  };
+  return riskFreeze({ ...body, census_digest: riskDigest(body) });
+}
+
+export function validateReceiptCensus(value: unknown, taxonomy?: ReceiptCensusTaxonomy) {
+  try {
+    if (taxonomy === undefined) return { valid: false, reason: 'census_taxonomy_required' };
+    const normalizedTaxonomy = normalizeTaxonomy(taxonomy);
+    const taxonomyDigest = riskDigest(normalizedTaxonomy);
+    const allowedActionClasses = new Set(normalizedTaxonomy.allowed_action_classes as string[]);
+    const allowedOutcomes = new Set(normalizedTaxonomy.allowed_outcomes as string[]);
+    if (!riskRecord(value) || !Object.hasOwn(value, 'census_digest')) return { valid: false, reason: 'census_shape_invalid' };
+    const { census_digest: supplied, ...body } = value;
+    if (!riskExact(body, BODY_KEYS) || body['@version'] !== RECEIPT_CENSUS_VERSION
+        || !riskIdentifier(body.census_id) || !riskIdentifier(body.relying_party_id)
+        || !riskExact(body.period, PERIOD_KEYS) || !validProgram(body.program)
+        || body.taxonomy_digest !== taxonomyDigest
+        || !Number.isSafeInteger(body.minimum_bucket_count) || body.minimum_bucket_count < 2
+        || body.minimum_bucket_count > 1000
+        || !Array.isArray(body.buckets) || body.buckets.length > 10_000
+        || !body.buckets.every(validBucket)
+        || !body.buckets.every((bucket: RiskRecord) => allowedActionClasses.has(bucket.action_class)
+          && allowedOutcomes.has(bucket.outcome) && bucket.program_version === body.program.version)
+        || !body.buckets.every((bucket: RiskRecord) => bucket.count >= body.minimum_bucket_count)
+        || !uniqueSortedBuckets(body.buckets)
+        || !riskExact(body.suppressed, ['bucket_count', 'record_count'])
+        || !Number.isSafeInteger(body.suppressed.bucket_count) || body.suppressed.bucket_count < 0
+        || !Number.isSafeInteger(body.suppressed.record_count) || body.suppressed.record_count < 0
+        || !RISK_DIGEST.test(body.source_inventory_digest)
+        || !Number.isFinite(riskInstant(body.generated_at))
+        || body.claim_boundary !== RECEIPT_CENSUS_CLAIM_BOUNDARY
+        || !RISK_DIGEST.test(supplied) || riskDigest(body) !== supplied) return { valid: false, reason: 'census_integrity_invalid' };
+    const start = riskInstant(body.period.start); const end = riskInstant(body.period.end);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start
+        || riskInstant(body.generated_at) < end) return { valid: false, reason: 'census_period_invalid' };
+    return { valid: true, reason: null, census_digest: supplied };
+  } catch { return { valid: false, reason: 'census_invalid' }; }
+}

package/src/reliance-risk-crypto.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+import crypto from 'node:crypto';
+import { canonicalize, hashCanonical } from './execution-binding.js';
+
+export type RiskRecord = Record<string, any>;
+export type TrustedRiskKeys = Record<string, { issuer_id: string; public_key: string }>;
+
+export const RISK_DIGEST = /^sha256:[0-9a-f]{64}$/;
+export const RISK_CAID = /^caid:1:[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*\.[1-9][0-9]*:jcs-sha256:[A-Za-z0-9_-]{43}$/;
+export const RISK_ID = /^[A-Za-z0-9][A-Za-z0-9:_.@/+\-]{0,511}$/;
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/;
+
+export function riskRecord(value: unknown): value is RiskRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  return Reflect.ownKeys(value).every((key) => {
+    if (typeof key !== 'string') return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor?.enumerable === true && Object.hasOwn(descriptor, 'value');
+  });
+}
+
+export function riskExact(value: unknown, keys: readonly string[]): value is RiskRecord {
+  return riskRecord(value) && Reflect.ownKeys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function riskIdentifier(value: unknown): value is string {
+  return typeof value === 'string' && RISK_ID.test(value);
+}
+
+export function riskInstant(value: unknown): number {
+  if (typeof value !== 'string') return NaN;
+  const match = value.match(RFC3339);
+  if (!match) return NaN;
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) return NaN;
+  return new Date(parsed).toISOString().slice(0, 19) === value.slice(0, 19) ? parsed : NaN;
+}
+
+export function riskDigest(value: unknown): string {
+  return `sha256:${hashCanonical(value)}`;
+}
+
+export function riskClone<T>(value: T): T {
+  return JSON.parse(canonicalize(value));
+}
+
+export function riskFreeze<T>(value: T): T {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value as RiskRecord)) riskFreeze(child);
+  return value;
+}
+
+function signingBytes(version: string, body: RiskRecord): Buffer {
+  return Buffer.from(`${version}\0${canonicalize(body)}`, 'utf8');
+}
+
+export function signRiskBody(
+  version: string,
+  bodyInput: RiskRecord,
+  signer: { issuer_id: string; key_id: string; private_key: crypto.KeyLike },
+): RiskRecord {
+  const key = signer.private_key instanceof crypto.KeyObject
+    ? signer.private_key : crypto.createPrivateKey(signer.private_key);
+  if (key.asymmetricKeyType !== 'ed25519') throw new TypeError('risk artifact signing key must be Ed25519');
+  if (!riskIdentifier(signer.issuer_id) || !riskIdentifier(signer.key_id)) throw new TypeError('risk artifact issuer is invalid');
+  const body = riskClone({ ...bodyInput, issuer: { id: signer.issuer_id, key_id: signer.key_id } });
+  const bodyDigest = riskDigest(body);
+  const proof = {
+    algorithm: 'Ed25519',
+    key_id: signer.key_id,
+    body_digest: bodyDigest,
+    signature_b64u: crypto.sign(null, signingBytes(version, body), key).toString('base64url'),
+  };
+  return riskFreeze({ ...body, proof });
+}
+
+export function verifyRiskBody(
+  artifact: unknown,
+  version: string,
+  trustedKeys: TrustedRiskKeys | undefined,
+): { valid: boolean; reason: string | null; body: RiskRecord | null; artifact_digest: string | null } {
+  const refuse = (reason: string) => ({ valid: false, reason, body: null, artifact_digest: null });
+  try {
+    if (!riskRecord(artifact) || !riskRecord(artifact.proof) || !riskRecord(artifact.issuer)) return refuse('artifact_shape_invalid');
+    const proof = artifact.proof;
+    const { proof: _proof, ...body } = artifact;
+    if (artifact['@version'] !== version || !riskExact(artifact.issuer, ['id', 'key_id'])
+        || !riskIdentifier(artifact.issuer.id) || !riskIdentifier(artifact.issuer.key_id)
+        || !riskExact(proof, ['algorithm', 'key_id', 'body_digest', 'signature_b64u'])
+        || proof.algorithm !== 'Ed25519' || proof.key_id !== artifact.issuer.key_id
+        || typeof proof.body_digest !== 'string' || !RISK_DIGEST.test(proof.body_digest)
+        || typeof proof.signature_b64u !== 'string' || !/^[A-Za-z0-9_-]+$/.test(proof.signature_b64u)) {
+      return refuse('artifact_signature_envelope_invalid');
+    }
+    if (riskDigest(body) !== proof.body_digest) return refuse('digest_mismatch');
+    const pin = trustedKeys?.[artifact.issuer.key_id];
+    if (!pin || pin.issuer_id !== artifact.issuer.id) return refuse('issuer_untrusted');
+    const keyBytes = Buffer.from(pin.public_key, 'base64url');
+    if (keyBytes.toString('base64url') !== pin.public_key) return refuse('pinned_key_invalid');
+    const key = crypto.createPublicKey({ key: keyBytes, type: 'spki', format: 'der' });
+    if (key.asymmetricKeyType !== 'ed25519') return refuse('pinned_key_invalid');
+    const signature = Buffer.from(proof.signature_b64u, 'base64url');
+    if (signature.length !== 64 || signature.toString('base64url') !== proof.signature_b64u
+        || !crypto.verify(null, signingBytes(version, body), key, signature)) return refuse('signature_invalid');
+    return { valid: true, reason: null, body, artifact_digest: riskDigest(artifact) };
+  } catch {
+    return refuse('artifact_invalid');
+  }
+}
+