@synoi/gateway-lite 0.1.0

package/dist/gap/cited-oracle-inputs.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * gap/cited-oracle-inputs.ts — cited_oracle_inputs[] receipt schema.
+ *
+ * Spec: DEMO_PREWORK_SCHEMAS_2026-06-17.md Specification 1 (Sections 1.1-1.9).
+ * Status: PARTIAL (visible-receipt citation of oracle inputs SHIPPED for
+ *   invocation and denial receipt subtypes; freshness-budget and cache-cursor
+ *   primitives remain PAPER, deferred to ADR_005 revision task #37).
+ *
+ * PII note (Section 1.8 + ADR_009 Section 9):
+ *   raw_value for "ofac" subject_type carries the recipient name (GDPR/CCPA).
+ *   raw_value for "sms_hitl" carries the E.164 phone number.
+ *   These are tenant-partitioned under tenant:steve-demo-<date> per #47
+ *   confirmation. raw_value MUST NOT be logged at INFO level; it is only
+ *   present inside the hybrid-signed receipt body for verifier use.
+ *
+ * Canonicalization rule (Section 1.3.5):
+ *   value_hash = sha256("sha256:" prefix NOT included in hash input) over
+ *   the JCS-canonical form of raw_value. Concretely:
+ *     value_hash = "sha256:" + sha256hex(canonicalize(raw_value))
+ *   The gate verifies this before signing; mismatch fails closed with
+ *   CITED_ORACLE_HASH_MISMATCH error code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORACLE_SUBJECT_TYPES = void 0;
+exports.canonicalizeRawValue = canonicalizeRawValue;
+exports.computeValueHash = computeValueHash;
+exports.verifyValueHash = verifyValueHash;
+exports.validateCitedOracleInput = validateCitedOracleInput;
+exports.validateCitedOracleInputs = validateCitedOracleInputs;
+exports.buildCitedOracleEntry = buildCitedOracleEntry;
+const node_crypto_1 = require("node:crypto");
+const sraid_1 = require("@synoi/sraid");
+exports.ORACLE_SUBJECT_TYPES = new Set([
+    'weather',
+    'ofac',
+    'time',
+    'sms_hitl',
+    'webhook',
+    'cve',
+    'incident_status',
+]);
+// ── Allowed known keys (strict mode per Section 1.1) ─────────────────────────
+const REQUIRED_KEYS = new Set([
+    'subject_type',
+    'value_hash',
+    'raw_value',
+    'fetched_at',
+    'source_url',
+]);
+const OPTIONAL_KEYS = new Set([
+    'feed_claimed_at',
+    'source_cursor',
+]);
+const ALL_KNOWN_KEYS = new Set([
+    ...REQUIRED_KEYS,
+    ...OPTIONAL_KEYS,
+]);
+// ── Canonicalization helper (Section 1.3.5) ───────────────────────────────────
+/**
+ * Produce the JCS-canonical string form of a raw_value object.
+ * This is the exact string whose SHA-256 is used for value_hash.
+ * Uses @synoi/sraid canonicalize (RFC 8785 conformant).
+ */
+function canonicalizeRawValue(raw_value) {
+    return (0, sraid_1.canonicalize)(raw_value);
+}
+// ── value_hash computation ────────────────────────────────────────────────────
+/**
+ * Compute value_hash = "sha256:" + sha256hex(canonicalize(raw_value)).
+ *
+ * This is the hash the gate embeds in each CitedOracleInput entry before
+ * signing the receipt. The verifier calls verifyValueHash() to confirm
+ * the embedded hash still matches the embedded raw_value.
+ */
+function computeValueHash(raw_value) {
+    const canonical = canonicalizeRawValue(raw_value);
+    const hex = (0, node_crypto_1.createHash)('sha256').update(canonical, 'utf8').digest('hex');
+    return 'sha256:' + hex;
+}
+// ── value_hash verification (gate pre-signing check + verifier check) ─────────
+/**
+ * Recompute value_hash from raw_value and compare to the embedded hash.
+ *
+ * Returns true on match, throws on mismatch.
+ * Fail-closed: used by the gate before signing the receipt (Section 2.5
+ * adapter_value_hash_mismatch) and by the verifier (Section 1.3.5).
+ *
+ * Error code on mismatch: "adapter_value_hash_mismatch" for gate use,
+ * "integrity_error: ...value_hash does not match sha256(JCS(raw_value))"
+ * for verifier use (Section 1.7.2 negative #2).
+ */
+function verifyValueHash(entry, index) {
+    const expected = computeValueHash(entry.raw_value);
+    if (entry.value_hash !== expected) {
+        throw new Error(`integrity_error: cited_oracle_inputs[${index}].value_hash does not match sha256(JCS(raw_value))` +
+            ` (embedded=${entry.value_hash}, computed=${expected})`);
+    }
+    return true;
+}
+// ── Strict-mode schema validation (Section 1.1 + Section 1.7.2) ──────────────
+/** RFC 3339 UTC ms pattern: must end with Z, must have ms component. */
+const RFC3339_UTC_MS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/**
+ * Validate a single cited_oracle_inputs[] entry in strict mode.
+ *
+ * Checks:
+ *   - All required fields present (Section 1.7.2 negative #1).
+ *   - No unknown keys (Section 1.7.2 negative #3 -- strict mode).
+ *   - null forbidden for optional fields (Section 1.3.3).
+ *   - subject_type is a known enum value.
+ *   - value_hash format is "sha256:" + 64 hex chars.
+ *   - fetched_at and feed_claimed_at match RFC 3339 UTC ms.
+ *   - value_hash matches sha256(JCS(raw_value)) (Section 1.3.5).
+ *
+ * Does NOT validate per-subject_type raw_value structure beyond type presence.
+ * That validation is left to per-adapter code.
+ *
+ * @param entry - the raw parsed object (unknown type for safety).
+ * @param index - array index for error messages.
+ * @returns the typed CitedOracleInput on success; throws CitedOracleError on failure.
+ */
+function validateCitedOracleInput(entry, index) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}] must be a non-null object`,
+        };
+    }
+    const obj = entry;
+    // Unknown key check (strict mode).
+    for (const k of Object.keys(obj)) {
+        if (!ALL_KNOWN_KEYS.has(k)) {
+            throw {
+                code: 'schema_error',
+                message: `cited_oracle_inputs[${index}] unknown key '${k}'`,
+            };
+        }
+    }
+    // Required fields.
+    for (const k of REQUIRED_KEYS) {
+        if (!(k in obj) || obj[k] === undefined) {
+            throw {
+                code: 'schema_error',
+                message: `cited_oracle_inputs[${index}].${k} missing`,
+            };
+        }
+    }
+    // null forbidden for optional fields.
+    for (const k of OPTIONAL_KEYS) {
+        if (k in obj && obj[k] === null) {
+            throw {
+                code: 'schema_error',
+                message: `cited_oracle_inputs[${index}].${k} must not be null; omit the key instead`,
+            };
+        }
+    }
+    const subject_type = obj['subject_type'];
+    if (typeof subject_type !== 'string' || !exports.ORACLE_SUBJECT_TYPES.has(subject_type)) {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}].subject_type must be one of: ${[...exports.ORACLE_SUBJECT_TYPES].join(', ')}; got ${JSON.stringify(subject_type)}`,
+        };
+    }
+    const value_hash = obj['value_hash'];
+    if (typeof value_hash !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(value_hash)) {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}].value_hash must be "sha256:" followed by 64 lowercase hex characters`,
+        };
+    }
+    const raw_value = obj['raw_value'];
+    if (typeof raw_value !== 'object' || raw_value === null || Array.isArray(raw_value)) {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}].raw_value must be a non-null object`,
+        };
+    }
+    const fetched_at = obj['fetched_at'];
+    if (typeof fetched_at !== 'string' || !RFC3339_UTC_MS_RE.test(fetched_at)) {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}].fetched_at must be RFC 3339 UTC with milliseconds (e.g. 2026-06-17T19:32:18.412Z)`,
+        };
+    }
+    const source_url = obj['source_url'];
+    if (typeof source_url !== 'string' || source_url.trim() === '') {
+        throw {
+            code: 'schema_error',
+            message: `cited_oracle_inputs[${index}].source_url must be a non-empty string`,
+        };
+    }
+    if ('feed_claimed_at' in obj && obj['feed_claimed_at'] !== undefined) {
+        const fca = obj['feed_claimed_at'];
+        if (typeof fca !== 'string' || !RFC3339_UTC_MS_RE.test(fca)) {
+            throw {
+                code: 'schema_error',
+                message: `cited_oracle_inputs[${index}].feed_claimed_at must be RFC 3339 UTC with milliseconds when present`,
+            };
+        }
+    }
+    if ('source_cursor' in obj && obj['source_cursor'] !== undefined) {
+        if (typeof obj['source_cursor'] !== 'string') {
+            throw {
+                code: 'schema_error',
+                message: `cited_oracle_inputs[${index}].source_cursor must be a string when present`,
+            };
+        }
+    }
+    // Integrity check: value_hash must equal sha256(JCS(raw_value)).
+    try {
+        verifyValueHash({ raw_value: raw_value, value_hash: value_hash }, index);
+    }
+    catch (err) {
+        throw {
+            code: 'integrity_error',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const result = {
+        subject_type: subject_type,
+        value_hash: value_hash,
+        raw_value: raw_value,
+        fetched_at: fetched_at,
+        source_url: source_url,
+    };
+    if ('feed_claimed_at' in obj && typeof obj['feed_claimed_at'] === 'string') {
+        result.feed_claimed_at = obj['feed_claimed_at'];
+    }
+    if ('source_cursor' in obj && typeof obj['source_cursor'] === 'string') {
+        result.source_cursor = obj['source_cursor'];
+    }
+    return result;
+}
+/**
+ * Validate an entire cited_oracle_inputs array.
+ * Returns the typed array on success; throws CitedOracleError on first failure.
+ * Array order is preserved (Section 1.3.2).
+ * Empty array and omission are both accepted (Section 1.3.4).
+ */
+function validateCitedOracleInputs(inputs) {
+    if (inputs === undefined || inputs === null)
+        return [];
+    if (!Array.isArray(inputs)) {
+        throw {
+            code: 'schema_error',
+            message: 'cited_oracle_inputs must be an array when present',
+        };
+    }
+    return inputs.map((entry, i) => validateCitedOracleInput(entry, i));
+}
+// ── Receipt integration helpers ───────────────────────────────────────────────
+/**
+ * Build a CitedOracleInput entry from adapter-produced fields.
+ *
+ * The gate calls this after each oracle fetch and before signing the receipt.
+ * If value_hash is provided (from the adapter), it is verified; if not, it is
+ * computed here so the adapter does not have to.
+ *
+ * Fails closed with an error if the provided hash mismatches (Section 2.5:
+ * programmer error in the adapter -- emit denial with adapter_value_hash_mismatch).
+ */
+function buildCitedOracleEntry(params) {
+    const computed_hash = computeValueHash(params.raw_value);
+    if (params.value_hash !== undefined && params.value_hash !== computed_hash) {
+        throw new Error(`adapter_value_hash_mismatch: subject_type=${params.subject_type} ` +
+            `adapter_hash=${params.value_hash} computed=${computed_hash}`);
+    }
+    const entry = {
+        subject_type: params.subject_type,
+        value_hash: computed_hash,
+        raw_value: params.raw_value,
+        fetched_at: params.fetched_at,
+        source_url: params.source_url,
+    };
+    if (params.feed_claimed_at !== undefined) {
+        entry.feed_claimed_at = params.feed_claimed_at;
+    }
+    if (params.source_cursor !== undefined) {
+        entry.source_cursor = params.source_cursor;
+    }
+    return entry;
+}