334 lines
14 KiB
JavaScript
334 lines
14 KiB
JavaScript
import crypto from 'node:crypto';
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
|
|
import Ajv2020 from 'ajv/dist/2020.js';
|
|
|
|
const EXPECTED_KIND = 'DecisionRecordArtifact';
|
|
const EXPECTED_API_VERSION = 'reporting-governance/v1alpha1';
|
|
const CANONICAL_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
|
|
const SOURCE_EVENT_ID_PATTERN = /^(?:evt_[A-Za-z0-9._:-]+|\/?[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i;
|
|
const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
|
const RECEIPT_DELIVERY_STATES = new Set(['prepared', 'queued', 'dispatched', 'pending_external_send', 'acked', 'blocked', 'failed', 'partial']);
|
|
const RECEIPT_STATUS_RULES = {
|
|
planned: ['prepared', 'queued', 'dispatched', 'pending_external_send', 'partial'],
|
|
acked: ['acked'],
|
|
blocked: ['blocked'],
|
|
degraded: ['partial', 'failed', 'blocked'],
|
|
failed: ['failed']
|
|
};
|
|
|
|
const packageRoot = path.resolve(import.meta.dirname, '..', '..');
|
|
const repoRoot = path.resolve(packageRoot, '..', '..');
|
|
const decisionSchemaPath = path.resolve(repoRoot, 'schemas', 'reporting-governance', 'decision.schema.json');
|
|
const decisionRecordArtifactSchemaPath = path.resolve(repoRoot, 'schemas', 'reporting-governance', 'decision-record-artifact.schema.json');
|
|
|
|
const ajv = new Ajv2020({ allErrors: true, strict: false });
|
|
const decisionSchema = JSON.parse(fs.readFileSync(decisionSchemaPath, 'utf8'));
|
|
const decisionRecordArtifactSchema = JSON.parse(fs.readFileSync(decisionRecordArtifactSchemaPath, 'utf8'));
|
|
ajv.addSchema(decisionSchema);
|
|
const validateDecisionRecordArtifactSchema = ajv.compile(decisionRecordArtifactSchema);
|
|
|
|
function formatAjvErrors(errors = []) {
|
|
if (!Array.isArray(errors) || errors.length === 0) {
|
|
return 'schema validation failed';
|
|
}
|
|
|
|
return errors.map((error) => {
|
|
const keyword = error.keyword;
|
|
const instancePath = error.instancePath || '/';
|
|
|
|
if (keyword === 'required') {
|
|
const missing = error.params?.missingProperty ?? 'unknown';
|
|
return `${instancePath} missing required property ${missing}`;
|
|
}
|
|
|
|
if (keyword === 'additionalProperties') {
|
|
const extra = error.params?.additionalProperty ?? 'unknown';
|
|
return `${instancePath} must not include additional property ${extra}`;
|
|
}
|
|
|
|
if (keyword === 'const') {
|
|
return `${instancePath} must equal ${JSON.stringify(error.params?.allowedValue)}`;
|
|
}
|
|
|
|
if (keyword === 'enum') {
|
|
const allowed = Array.isArray(error.params?.allowedValues)
|
|
? error.params.allowedValues.join(', ')
|
|
: 'allowed set';
|
|
return `${instancePath} must be one of: ${allowed}`;
|
|
}
|
|
|
|
return `${instancePath} ${error.message}`.trim();
|
|
}).join('; ');
|
|
}
|
|
|
|
function assertNonEmptyString(value, label) {
|
|
if (typeof value !== 'string' || value.trim() === '') {
|
|
throw new Error(`${label} must be a non-empty string`);
|
|
}
|
|
return value.trim();
|
|
}
|
|
|
|
function assertObjectRecord(value, label) {
|
|
if (!value || typeof value !== 'object' || Array.isArray(value)) {
|
|
throw new Error(`${label} must be an object record`);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function sanitizeFileSegment(value, fallback) {
|
|
const normalized = String(value ?? '')
|
|
.trim()
|
|
.replace(/[^a-zA-Z0-9._-]+/g, '-')
|
|
.replace(/^-+|-+$/g, '')
|
|
.replace(/^(?:\.+-*)+/, '')
|
|
.replace(/(?:-+\.)+$/g, '')
|
|
.replace(/^-+|-+$/g, '');
|
|
return normalized || fallback;
|
|
}
|
|
|
|
function assertCanonicalIsoTimestamp(value, label) {
|
|
const normalized = assertNonEmptyString(value, label);
|
|
if (!CANONICAL_TIMESTAMP_PATTERN.test(normalized) || Number.isNaN(Date.parse(normalized))) {
|
|
throw new Error(`${label} must be a canonical ISO-8601 UTC timestamp with millisecond precision`);
|
|
}
|
|
return normalized;
|
|
}
|
|
|
|
function assertSourceEventId(value, label) {
|
|
const normalized = assertNonEmptyString(value, label);
|
|
if (!SOURCE_EVENT_ID_PATTERN.test(normalized)) {
|
|
throw new Error(`${label} must be a stable event reference (evt_* | path-like artifact ref | UUID)`);
|
|
}
|
|
return normalized;
|
|
}
|
|
|
|
function normalizeUuidLike(value) {
|
|
if (typeof value !== 'string') {
|
|
return value;
|
|
}
|
|
return UUID_PATTERN.test(value) ? value.toLowerCase() : value;
|
|
}
|
|
|
|
function projectCanonicalDecision(decision) {
|
|
if (!decision || typeof decision !== 'object' || Array.isArray(decision)) {
|
|
return decision;
|
|
}
|
|
|
|
return {
|
|
decision: decision.decision,
|
|
policy_id: decision.policy_id,
|
|
severity: decision.severity,
|
|
reason: decision.reason,
|
|
rewritten_message: decision.rewritten_message ?? null,
|
|
suggested_status: decision.suggested_status ?? null,
|
|
required_actions: decision.required_actions,
|
|
operator_notice: decision.operator_notice ?? null,
|
|
};
|
|
}
|
|
|
|
function normalizeArtifactShape(artifact) {
|
|
if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
|
|
return;
|
|
}
|
|
|
|
if (artifact.metadata && typeof artifact.metadata === 'object' && !Array.isArray(artifact.metadata)) {
|
|
artifact.metadata.event_id = normalizeUuidLike(artifact.metadata.event_id);
|
|
}
|
|
|
|
if (artifact.spec?.source && typeof artifact.spec.source === 'object' && !Array.isArray(artifact.spec.source)) {
|
|
artifact.spec.source.event_id = normalizeUuidLike(artifact.spec.source.event_id);
|
|
}
|
|
|
|
if (artifact.spec?.decision && typeof artifact.spec.decision === 'object' && !Array.isArray(artifact.spec.decision)) {
|
|
artifact.spec.decision = projectCanonicalDecision(artifact.spec.decision);
|
|
}
|
|
}
|
|
|
|
function validateReceiptContract(receipt) {
|
|
const deliveryState = assertNonEmptyString(receipt.delivery_state, 'decision record artifact spec.receipt.delivery_state');
|
|
if (!RECEIPT_DELIVERY_STATES.has(deliveryState)) {
|
|
throw new Error(`decision record artifact spec.receipt.delivery_state must be one of: ${Array.from(RECEIPT_DELIVERY_STATES).join(', ')}`);
|
|
}
|
|
|
|
const status = assertNonEmptyString(receipt.status, 'decision record artifact spec.receipt.status');
|
|
const allowedStates = RECEIPT_STATUS_RULES[status];
|
|
if (!allowedStates) {
|
|
throw new Error(`decision record artifact spec.receipt.status must be one of: ${Object.keys(RECEIPT_STATUS_RULES).join(', ')}`);
|
|
}
|
|
if (!allowedStates.includes(deliveryState)) {
|
|
throw new Error(`decision record artifact spec.receipt.status=${status} is incompatible with delivery_state=${deliveryState}`);
|
|
}
|
|
|
|
if (receipt.operator_notice_required != null && typeof receipt.operator_notice_required !== 'boolean') {
|
|
throw new Error('decision record artifact spec.receipt.operator_notice_required must be a boolean when present');
|
|
}
|
|
if (!Array.isArray(receipt.enforcement_intent)) {
|
|
throw new Error('decision record artifact spec.receipt.enforcement_intent must be an array');
|
|
}
|
|
if (!Array.isArray(receipt.blocked_actions)) {
|
|
throw new Error('decision record artifact spec.receipt.blocked_actions must be an array');
|
|
}
|
|
if (!Array.isArray(receipt.notes)) {
|
|
throw new Error('decision record artifact spec.receipt.notes must be an array');
|
|
}
|
|
|
|
if (status === 'failed') {
|
|
const failureReason = receipt.failure_reason == null
|
|
? null
|
|
: assertNonEmptyString(receipt.failure_reason, 'decision record artifact spec.receipt.failure_reason');
|
|
if (!failureReason) {
|
|
throw new Error('decision record artifact spec.receipt.failure_reason is required when status=failed');
|
|
}
|
|
}
|
|
|
|
if (deliveryState === 'partial') {
|
|
if (receipt.blocked_actions.length === 0) {
|
|
throw new Error('decision record artifact spec.receipt.blocked_actions must be non-empty when delivery_state=partial');
|
|
}
|
|
if (receipt.enforcement_intent.length === 0) {
|
|
throw new Error('decision record artifact spec.receipt.enforcement_intent must be non-empty when delivery_state=partial');
|
|
}
|
|
}
|
|
|
|
return { deliveryState, status };
|
|
}
|
|
|
|
function validateDecisionRecordArtifactSchemaContract(artifact) {
|
|
const candidate = structuredClone(artifact);
|
|
normalizeArtifactShape(candidate);
|
|
|
|
if (!validateDecisionRecordArtifactSchema(candidate)) {
|
|
throw new Error(`decision record artifact schema validation failed: ${formatAjvErrors(validateDecisionRecordArtifactSchema.errors)}`);
|
|
}
|
|
|
|
return candidate;
|
|
}
|
|
|
|
export function validateDecisionRecordArtifact(artifact) {
|
|
if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
|
|
throw new Error('decision record artifact must be an object');
|
|
}
|
|
if (artifact.kind !== EXPECTED_KIND) {
|
|
throw new Error(`decision record artifact kind must be ${EXPECTED_KIND}`);
|
|
}
|
|
if (artifact.apiVersion !== EXPECTED_API_VERSION) {
|
|
throw new Error(`decision record artifact apiVersion must be ${EXPECTED_API_VERSION}`);
|
|
}
|
|
|
|
const metadata = assertObjectRecord(artifact.metadata, 'decision record artifact metadata');
|
|
const spec = assertObjectRecord(artifact.spec, 'decision record artifact spec');
|
|
const decision = assertObjectRecord(spec.decision, 'decision record artifact spec.decision');
|
|
const receipt = assertObjectRecord(spec.receipt, 'decision record artifact spec.receipt');
|
|
const source = spec.source == null ? null : assertObjectRecord(spec.source, 'decision record artifact spec.source');
|
|
|
|
const recordedAt = assertCanonicalIsoTimestamp(metadata.recorded_at, 'decision record artifact metadata.recorded_at');
|
|
const metadataPolicyId = assertNonEmptyString(metadata.policy_id, 'decision record artifact metadata.policy_id');
|
|
const metadataDecision = assertNonEmptyString(metadata.decision, 'decision record artifact metadata.decision');
|
|
const decisionPolicyId = assertNonEmptyString(decision.policy_id, 'decision record artifact spec.decision.policy_id');
|
|
const decisionName = assertNonEmptyString(decision.decision, 'decision record artifact spec.decision.decision');
|
|
const { deliveryState, status } = validateReceiptContract(receipt);
|
|
|
|
if (metadataPolicyId !== decisionPolicyId) {
|
|
throw new Error('decision record artifact policy_id mismatch between metadata and spec.decision');
|
|
}
|
|
if (metadataDecision !== decisionName) {
|
|
throw new Error('decision record artifact decision mismatch between metadata and spec.decision');
|
|
}
|
|
|
|
const metadataEventId = metadata.event_id == null ? null : assertSourceEventId(metadata.event_id, 'decision record artifact metadata.event_id');
|
|
const sourceEventId = source?.event_id == null ? null : assertSourceEventId(source.event_id, 'decision record artifact spec.source.event_id');
|
|
if ((metadataEventId == null) !== (sourceEventId == null)) {
|
|
throw new Error('decision record artifact event_id must be present in both metadata and spec.source when either side declares it');
|
|
}
|
|
if (metadataEventId != null && sourceEventId != null && metadataEventId !== sourceEventId) {
|
|
throw new Error('decision record artifact event_id mismatch between metadata and spec.source');
|
|
}
|
|
if (source != null && source.task_id == null && source.correlation_id == null && sourceEventId == null) {
|
|
throw new Error('decision record artifact spec.source must declare at least one linkage field');
|
|
}
|
|
if (source?.task_id != null) {
|
|
const sourceTaskId = assertNonEmptyString(source.task_id, 'decision record artifact spec.source.task_id');
|
|
if (metadata.task_id != null && assertNonEmptyString(metadata.task_id, 'decision record artifact metadata.task_id') !== sourceTaskId) {
|
|
throw new Error('decision record artifact task_id mismatch between metadata and spec.source');
|
|
}
|
|
}
|
|
if (source?.correlation_id != null) {
|
|
const sourceCorrelationId = assertNonEmptyString(source.correlation_id, 'decision record artifact spec.source.correlation_id');
|
|
if (metadata.correlation_id != null && assertNonEmptyString(metadata.correlation_id, 'decision record artifact metadata.correlation_id') !== sourceCorrelationId) {
|
|
throw new Error('decision record artifact correlation_id mismatch between metadata and spec.source');
|
|
}
|
|
}
|
|
|
|
const schemaValidated = validateDecisionRecordArtifactSchemaContract(artifact);
|
|
|
|
metadata.recorded_at = recordedAt;
|
|
metadata.policy_id = metadataPolicyId;
|
|
metadata.decision = metadataDecision;
|
|
metadata.event_id = schemaValidated.metadata.event_id;
|
|
spec.decision = schemaValidated.spec.decision;
|
|
receipt.delivery_state = deliveryState;
|
|
receipt.status = status;
|
|
if (source != null) {
|
|
source.event_id = schemaValidated.spec.source.event_id;
|
|
}
|
|
|
|
return artifact;
|
|
}
|
|
|
|
export function createDecisionRecordArtifact({ decision, receipt, recordedAt = new Date().toISOString(), source = {} } = {}) {
|
|
const normalizedDecision = assertObjectRecord(decision, 'decision');
|
|
const normalizedReceipt = assertObjectRecord(receipt, 'receipt');
|
|
const policyId = assertNonEmptyString(normalizedDecision.policy_id, 'decision.policy_id');
|
|
const decisionName = assertNonEmptyString(normalizedDecision.decision, 'decision.decision');
|
|
|
|
return validateDecisionRecordArtifact({
|
|
kind: EXPECTED_KIND,
|
|
apiVersion: EXPECTED_API_VERSION,
|
|
metadata: {
|
|
record_id: `dec_${crypto.randomUUID()}`,
|
|
recorded_at: assertCanonicalIsoTimestamp(recordedAt, 'recordedAt'),
|
|
policy_id: policyId,
|
|
decision: decisionName,
|
|
correlation_id: source.correlation_id ?? null,
|
|
task_id: source.task_id ?? null,
|
|
event_id: source.event_id ?? null,
|
|
},
|
|
spec: {
|
|
decision: normalizedDecision,
|
|
receipt: normalizedReceipt,
|
|
source: {
|
|
event_id: source.event_id ?? null,
|
|
task_id: source.task_id ?? null,
|
|
correlation_id: source.correlation_id ?? null,
|
|
},
|
|
},
|
|
});
|
|
}
|
|
|
|
export function createDecisionRecordFileName(artifact) {
|
|
const metadata = assertObjectRecord(artifact?.metadata, 'decision record artifact metadata');
|
|
const recordedAt = assertCanonicalIsoTimestamp(metadata.recorded_at, 'decision record artifact metadata.recorded_at');
|
|
const policyId = assertNonEmptyString(metadata.policy_id, 'decision record artifact metadata.policy_id');
|
|
const decision = assertNonEmptyString(metadata.decision, 'decision record artifact metadata.decision');
|
|
const recordId = assertNonEmptyString(metadata.record_id, 'decision record artifact metadata.record_id');
|
|
|
|
return [
|
|
recordedAt.replace(/[.:]/g, '-'),
|
|
sanitizeFileSegment(policyId, 'policy'),
|
|
sanitizeFileSegment(decision, 'decision'),
|
|
`${recordId}.json`,
|
|
].join('-');
|
|
}
|
|
|
|
export const __testables = {
|
|
EXPECTED_KIND,
|
|
EXPECTED_API_VERSION,
|
|
sanitizeFileSegment,
|
|
CANONICAL_TIMESTAMP_PATTERN,
|
|
SOURCE_EVENT_ID_PATTERN,
|
|
RECEIPT_DELIVERY_STATES,
|
|
RECEIPT_STATUS_RULES,
|
|
};
|