@attestplane/attestplane 0.0.1 → 0.0.3-alpha

package/dist/proof_bundle.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Proof-bundle export and auditor-export builders (TypeScript port of
+ * `sdk/python/src/attestplane/proof_bundle.py`).
+ *
+ * The bundle shape matches `schemas/v1/proof_bundle.schema.json` exactly,
+ * and the auditor export matches `schemas/v1/auditor_export.schema.json`.
+ * Cross-language byte-stable: a chain produced by the Python SDK and a
+ * chain produced by the TypeScript SDK that go through the same builder
+ * inputs produce the same proof-bundle dict.
+ */
+import { type SignatureRecord } from './signing/base.js';
+import type { ChainedEvent } from './types.js';
+export declare const DEFAULT_FORBIDDEN_FIELDS: readonly string[];
+export type ImplementationStatus = 'mapping_target' | 'designed_toward' | 'field_supported' | 'verified_in_test';
+export interface FrameworkMapping {
+    readonly obligation_id: string;
+    readonly evidence_event_indexes: readonly number[];
+    readonly implementation_status_at_bundle_time: ImplementationStatus;
+}
+export interface ProofBundleBuilderInput {
+    readonly chain_id: string;
+    readonly producer_runtime: string;
+    readonly forbidden_fields?: readonly string[];
+    readonly anchor_ref?: string | null;
+}
+export interface ProofBundle {
+    readonly bundle_version: 1;
+    readonly chain_metadata: {
+        readonly chain_id: string;
+        readonly schema_version: number;
+        readonly genesis_hash_hex: string;
+        readonly head_hash_hex: string;
+        readonly head_seq: number;
+        readonly producer_runtime: string;
+        readonly evidence_taxonomy_version: 1;
+        readonly anchor_ref?: string;
+    };
+    readonly events: readonly SerializedChainedEvent[];
+    readonly verification_report: {
+        readonly ok: boolean;
+        readonly first_bad_index: number | null;
+        readonly reason: string | null;
+        readonly verified_at: string;
+        readonly verifier_version: string;
+        readonly verification_method: 'canonical-bytes-walk' | 'canonical-bytes-walk+anchor';
+    };
+    readonly framework_mappings: readonly FrameworkMapping[];
+    readonly forbidden_fields: readonly string[];
+    /**
+     * Additive `policy_trace_refs` field per ADR-0012 P1.2. Flat list of
+     * `event_hash_hex` for every ChainedEvent whose `event_type ==
+     * 'policy_check_event'`. Chain-seq-ascending order; deduplicated;
+     * absent when empty (preserves byte identity with bundles that have
+     * no policy_check_event rows).
+     */
+    readonly policy_trace_refs?: readonly string[];
+    /**
+     * Additive `signatures` field per ADR-0005 T5. Absent when no
+     * SignatureRecord has been added (preserves byte equality with
+     * v0.0.1-alpha bundles).
+     */
+    readonly signatures?: readonly SerializedSignatureRecord[];
+}
+/**
+ * Wire-format `SignatureRecord` per `_serialize_signature_record` in
+ * `sdk/python/src/attestplane/proof_bundle.py`. Field-by-field
+ * byte-stable copy of Python's encoding.
+ */
+export interface SerializedSignatureRecord {
+    readonly signature_schema_version: number;
+    readonly signed_seq: number;
+    readonly signed_event_hash_hex: string;
+    readonly signature_hex: string;
+    readonly key_id: string;
+    readonly public_key_der_b64: string;
+    readonly signing_cert_chain_b64: readonly string[];
+    readonly signed_at: string;
+    readonly signature_mode: 'segment_head' | 'per_event';
+    readonly signed_payload_b64: string;
+}
+export interface SerializedSubjectRef {
+    readonly scheme: 'sha256_salted' | 'opaque' | 'none';
+    readonly value: string;
+}
+export interface SerializedAuditEvent {
+    readonly schema_version: number;
+    readonly event_id: string;
+    readonly timestamp: string;
+    readonly event_type: string;
+    readonly actor: string;
+    readonly payload: Record<string, unknown>;
+    readonly subject_ref: SerializedSubjectRef | null;
+    readonly session_id: string | null;
+    readonly reference_db_ref: string | null;
+    readonly matched_input_ref: string | null;
+    readonly human_verifier: SerializedSubjectRef | null;
+}
+export interface SerializedChainedEvent {
+    readonly seq: number;
+    readonly prev_hash_hex: string;
+    readonly event_hash_hex: string;
+    readonly event: SerializedAuditEvent;
+}
+/**
+ * Encode a `SignatureRecord` as the wire-format dict per Python's
+ * `_serialize_signature_record`. Hex for fixed-length crypto values
+ * (event_hash, signature); base64 for variable blobs (public_key_der,
+ * cert_chain, signed_payload); RFC-3339 µs-Z for the datetime.
+ */
+export declare function serializeSignatureRecord(record: SignatureRecord): SerializedSignatureRecord;
+/**
+ * Inverse of `serializeSignatureRecord`. Validates the result via
+ * `validateSignatureRecord` so malformed records surface as a
+ * `SigningError`.
+ */
+export declare function deserializeSignatureRecord(raw: SerializedSignatureRecord): SignatureRecord;
+export declare function serializeChainedEvent(event: ChainedEvent): SerializedChainedEvent;
+/**
+ * Accumulator for one proof-bundle build.
+ *
+ * Not thread-safe — create one per bundle.
+ */
+export declare class ProofBundleBuilder {
+    private readonly _chain_id;
+    private readonly _producer_runtime;
+    private readonly _forbidden_fields;
+    private readonly _anchor_ref;
+    private readonly _events;
+    private readonly _framework_mappings;
+    private readonly _signatures;
+    constructor(input: ProofBundleBuilderInput);
+    extend(events: readonly ChainedEvent[]): void;
+    addFrameworkMapping(mapping: FrameworkMapping): void;
+    /**
+     * Add `SignatureRecord` instances per ADR-0005 T5. Each entry is
+     * validated immediately via `validateSignatureRecord`; the bundle's
+     * `signatures` field is emitted only when at least one record has
+     * been added (preserves byte equality with v0.0.1-alpha bundles).
+     */
+    extendSignatures(records: readonly SignatureRecord[]): void;
+    build(options?: {
+        readonly now?: Date;
+    }): ProofBundle;
+}
+export interface AuditorExport {
+    readonly export_version: 1;
+    readonly chain_summary: {
+        readonly chain_id: string;
+        readonly head_hash_hex: string;
+        readonly event_count: number;
+        readonly time_range: {
+            readonly earliest: string;
+            readonly latest: string;
+        };
+        readonly producer_runtime: string;
+        readonly event_type_histogram: Record<string, number>;
+        readonly anchor_status: 'unanchored' | 'anchored_partial' | 'anchored_full';
+    };
+    readonly verification_status: {
+        readonly ok: boolean;
+        readonly first_bad_index: number | null;
+        readonly reason: string | null;
+        readonly verified_at: string;
+        readonly verifier_version: string;
+        readonly verification_method: 'canonical-bytes-walk' | 'canonical-bytes-walk+anchor';
+    };
+    readonly framework_coverage: readonly {
+        readonly framework: string;
+        readonly article: string;
+        readonly obligation_ids_with_evidence: readonly string[];
+        readonly obligation_ids_without_evidence: readonly string[];
+    }[];
+    readonly redaction_policy: {
+        readonly forbidden_fields: readonly string[];
+        readonly redaction_status: 'enforced_by_adapter' | 'enforced_by_producer' | 'unenforced';
+        readonly consent_status?: 'consent_present' | 'consent_absent' | 'consent_not_applicable';
+    };
+    readonly legal_disclaimer: string;
+}
+export interface AuditorExportOptions {
+    readonly redaction_status?: AuditorExport['redaction_policy']['redaction_status'];
+    readonly consent_status?: 'consent_present' | 'consent_absent' | 'consent_not_applicable';
+    readonly legal_disclaimer?: string;
+}
+export declare function buildAuditorExport(bundle: ProofBundle, options?: AuditorExportOptions): AuditorExport;
+//# sourceMappingURL=proof_bundle.d.ts.map

package/dist/proof_bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof_bundle.d.ts","sourceRoot":"","sources":["../src/proof_bundle.ts"],"names":[],"mappings":"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"}

package/dist/proof_bundle.js

@@ -0,0 +1,299 @@
+// SPDX-FileCopyrightText: 2026 The Attestplane Authors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Proof-bundle export and auditor-export builders (TypeScript port of
+ * `sdk/python/src/attestplane/proof_bundle.py`).
+ *
+ * The bundle shape matches `schemas/v1/proof_bundle.schema.json` exactly,
+ * and the auditor export matches `schemas/v1/auditor_export.schema.json`.
+ * Cross-language byte-stable: a chain produced by the Python SDK and a
+ * chain produced by the TypeScript SDK that go through the same builder
+ * inputs produce the same proof-bundle dict.
+ */
+import { SCHEMA_VERSION, headOf, verifyChain } from './hashchain.js';
+import { VERSION as _SDK_VERSION } from './index_version.js';
+import { SIGNATURE_SCHEMA_VERSION, validateSignatureRecord, } from './signing/base.js';
+export const DEFAULT_FORBIDDEN_FIELDS = [
+    'customer_names',
+    'person_names',
+    'pii',
+    'raw_documents',
+    'contracts',
+    'scripts',
+    'tickets',
+    'emails',
+    'secrets',
+    'tokens',
+    'jwts',
+    'private_keys',
+    'raw_audit_payloads',
+];
+function bytesToHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const v = bytes[i].toString(16).padStart(2, '0');
+        out += v;
+    }
+    return out;
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error(`hex string has odd length: ${hex.length}`);
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error(`invalid hex at offset ${i * 2}: ${hex.slice(i * 2, i * 2 + 2)}`);
+        }
+        out[i] = byte;
+    }
+    return out;
+}
+function b64encode(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+function b64decode(b64) {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+function parseSignedAtTimestamp(ts) {
+    // Python emits "YYYY-MM-DDTHH:MM:SS.ffffffZ" (microsecond precision +
+    // literal Z). Date.parse accepts trailing-Z ISO; sub-millisecond
+    // digits are silently truncated to ms precision, which is acceptable
+    // because we only compare ISO-form on re-emit — never round-trip Date
+    // back to bytes.
+    const t = Date.parse(ts);
+    if (Number.isNaN(t)) {
+        throw new Error(`invalid signed_at timestamp: ${JSON.stringify(ts)}`);
+    }
+    return new Date(t);
+}
+/**
+ * Encode a `SignatureRecord` as the wire-format dict per Python's
+ * `_serialize_signature_record`. Hex for fixed-length crypto values
+ * (event_hash, signature); base64 for variable blobs (public_key_der,
+ * cert_chain, signed_payload); RFC-3339 µs-Z for the datetime.
+ */
+export function serializeSignatureRecord(record) {
+    return {
+        signature_schema_version: record.signature_schema_version,
+        signed_seq: record.signed_seq,
+        signed_event_hash_hex: bytesToHex(record.signed_event_hash),
+        signature_hex: bytesToHex(record.signature),
+        key_id: record.key_id,
+        public_key_der_b64: b64encode(record.public_key_der),
+        signing_cert_chain_b64: record.signing_cert_chain.map((c) => b64encode(c)),
+        signed_at: formatTimestampMicros(record.signed_at),
+        signature_mode: record.signature_mode,
+        signed_payload_b64: b64encode(record.signed_payload),
+    };
+}
+/**
+ * Inverse of `serializeSignatureRecord`. Validates the result via
+ * `validateSignatureRecord` so malformed records surface as a
+ * `SigningError`.
+ */
+export function deserializeSignatureRecord(raw) {
+    const required = [
+        'signature_schema_version',
+        'signed_seq',
+        'signed_event_hash_hex',
+        'signature_hex',
+        'key_id',
+        'public_key_der_b64',
+        'signing_cert_chain_b64',
+        'signed_at',
+        'signature_mode',
+        'signed_payload_b64',
+    ];
+    const obj = raw;
+    for (const k of required) {
+        if (!(k in obj)) {
+            throw new Error(`deserializeSignatureRecord: missing field ${k}`);
+        }
+    }
+    const record = {
+        signature_schema_version: Number(raw.signature_schema_version),
+        signed_seq: Number(raw.signed_seq),
+        signed_event_hash: hexToBytes(raw.signed_event_hash_hex),
+        signature: hexToBytes(raw.signature_hex),
+        key_id: String(raw.key_id),
+        public_key_der: b64decode(raw.public_key_der_b64),
+        signing_cert_chain: raw.signing_cert_chain_b64.map((c) => b64decode(c)),
+        signed_at: parseSignedAtTimestamp(raw.signed_at),
+        signature_mode: raw.signature_mode,
+        signed_payload: b64decode(raw.signed_payload_b64),
+    };
+    validateSignatureRecord(record);
+    return record;
+}
+function formatTimestampMicros(d) {
+    // ISO date with 6-digit microsecond precision and literal Z.
+    // JavaScript Date is millisecond-precision; we right-pad three zeros.
+    const isoMs = d.toISOString(); // "YYYY-MM-DDThh:mm:ss.sssZ"
+    // Replace ".sssZ" with ".sss000Z" to widen to microseconds.
+    return isoMs.replace(/\.(\d{3})Z$/, '.$1000Z');
+}
+function serializeSubject(ref) {
+    if (ref == null)
+        return null;
+    return { scheme: ref.scheme, value: ref.value };
+}
+export function serializeChainedEvent(event) {
+    return {
+        seq: event.seq,
+        prev_hash_hex: bytesToHex(event.prev_hash),
+        event_hash_hex: bytesToHex(event.event_hash),
+        event: {
+            schema_version: event.event.schema_version,
+            event_id: event.event.event_id,
+            timestamp: formatTimestampMicros(event.event.timestamp),
+            event_type: event.event.event_type,
+            actor: event.event.actor,
+            payload: event.event.payload,
+            subject_ref: serializeSubject(event.event.subject_ref),
+            session_id: event.event.session_id,
+            reference_db_ref: event.event.reference_db_ref,
+            matched_input_ref: event.event.matched_input_ref,
+            human_verifier: serializeSubject(event.event.human_verifier),
+        },
+    };
+}
+/**
+ * Accumulator for one proof-bundle build.
+ *
+ * Not thread-safe — create one per bundle.
+ */
+export class ProofBundleBuilder {
+    _chain_id;
+    _producer_runtime;
+    _forbidden_fields;
+    _anchor_ref;
+    _events = [];
+    _framework_mappings = [];
+    _signatures = [];
+    constructor(input) {
+        this._chain_id = input.chain_id;
+        this._producer_runtime = input.producer_runtime;
+        this._forbidden_fields = input.forbidden_fields ?? DEFAULT_FORBIDDEN_FIELDS;
+        this._anchor_ref = input.anchor_ref ?? null;
+    }
+    extend(events) {
+        for (const e of events)
+            this._events.push(e);
+    }
+    addFrameworkMapping(mapping) {
+        for (const idx of mapping.evidence_event_indexes) {
+            if (idx < 0 || idx >= this._events.length) {
+                throw new Error(`framework_mapping for ${mapping.obligation_id} references event index ${idx} ` +
+                    `but bundle has only ${this._events.length} events`);
+            }
+        }
+        this._framework_mappings.push(mapping);
+    }
+    /**
+     * Add `SignatureRecord` instances per ADR-0005 T5. Each entry is
+     * validated immediately via `validateSignatureRecord`; the bundle's
+     * `signatures` field is emitted only when at least one record has
+     * been added (preserves byte equality with v0.0.1-alpha bundles).
+     */
+    extendSignatures(records) {
+        for (const r of records) {
+            validateSignatureRecord(r);
+            if (r.signature_schema_version !== SIGNATURE_SCHEMA_VERSION) {
+                throw new Error(`extendSignatures: signature_schema_version must be ${SIGNATURE_SCHEMA_VERSION}, got ${r.signature_schema_version}`);
+            }
+            this._signatures.push(r);
+        }
+    }
+    build(options) {
+        const actualNow = options?.now ?? new Date();
+        const result = verifyChain(this._events);
+        const head = headOf(this._events);
+        const verifiedAt = formatTimestampMicros(actualNow);
+        const chainMetadata = {
+            chain_id: this._chain_id,
+            schema_version: SCHEMA_VERSION,
+            genesis_hash_hex: '0'.repeat(64),
+            head_hash_hex: bytesToHex(head.event_hash),
+            head_seq: head.seq,
+            producer_runtime: this._producer_runtime,
+            evidence_taxonomy_version: 1,
+            ...(this._anchor_ref != null ? { anchor_ref: this._anchor_ref } : {}),
+        };
+        const bundle = {
+            bundle_version: 1,
+            chain_metadata: chainMetadata,
+            events: this._events.map(serializeChainedEvent),
+            verification_report: {
+                ok: result.ok,
+                first_bad_index: result.first_bad_index,
+                reason: result.reason,
+                verified_at: verifiedAt,
+                verifier_version: _SDK_VERSION,
+                verification_method: 'canonical-bytes-walk',
+            },
+            framework_mappings: [...this._framework_mappings],
+            forbidden_fields: [...this._forbidden_fields],
+            // ADR-0012 P1.2: auto-derive policy_trace_refs (absent when empty).
+            ...(() => {
+                const refs = this._events
+                    .filter((ev) => ev.event.event_type === 'policy_check_event')
+                    .map((ev) => bytesToHex(ev.event_hash));
+                return refs.length > 0 ? { policy_trace_refs: refs } : {};
+            })(),
+            ...(this._signatures.length > 0
+                ? { signatures: this._signatures.map(serializeSignatureRecord) }
+                : {}),
+        };
+        return bundle;
+    }
+}
+const DEFAULT_DISCLAIMER = 'This export is a technical chain-integrity and framework-coverage summary. ' +
+    'It is not a compliance opinion. Consult qualified counsel for any regulatory determination.';
+export function buildAuditorExport(bundle, options) {
+    const histogram = {};
+    for (const ev of bundle.events) {
+        const key = ev.event.event_type;
+        histogram[key] = (histogram[key] ?? 0) + 1;
+    }
+    let earliest;
+    let latest;
+    const firstEvent = bundle.events[0];
+    if (firstEvent !== undefined) {
+        earliest = bundle.events.reduce((acc, ev) => (ev.event.timestamp < acc ? ev.event.timestamp : acc), firstEvent.event.timestamp);
+        latest = bundle.events.reduce((acc, ev) => (ev.event.timestamp > acc ? ev.event.timestamp : acc), firstEvent.event.timestamp);
+    }
+    else {
+        earliest = bundle.verification_report.verified_at;
+        latest = earliest;
+    }
+    return {
+        export_version: 1,
+        chain_summary: {
+            chain_id: bundle.chain_metadata.chain_id,
+            head_hash_hex: bundle.chain_metadata.head_hash_hex,
+            event_count: bundle.events.length,
+            time_range: { earliest, latest },
+            producer_runtime: bundle.chain_metadata.producer_runtime,
+            event_type_histogram: histogram,
+            anchor_status: 'unanchored',
+        },
+        verification_status: {
+            ok: bundle.verification_report.ok,
+            first_bad_index: bundle.verification_report.first_bad_index,
+            reason: bundle.verification_report.reason,
+            verified_at: bundle.verification_report.verified_at,
+            verifier_version: bundle.verification_report.verifier_version,
+            verification_method: bundle.verification_report.verification_method,
+        },
+        framework_coverage: [],
+        redaction_policy: {
+            forbidden_fields: bundle.forbidden_fields,
+            redaction_status: options?.redaction_status ?? 'enforced_by_producer',
+            consent_status: options?.consent_status ?? 'consent_not_applicable',
+        },
+        legal_disclaimer: options?.legal_disclaimer ?? DEFAULT_DISCLAIMER,
+    };
+}
+//# sourceMappingURL=proof_bundle.js.map

package/dist/proof_bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof_bundle.js","sourceRoot":"","sources":["../src/proof_bundle.ts"],"names":[],"mappings":"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"}

package/dist/reason_codes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ReasonCodeV1 enum — machine-readable verification findings (ADR-0010).
+ *
+ * Stable string enum for downstream tooling (audit reports, EU AI Act
+ * Article 12 evidence packs, regulator dashboards) to branch on the
+ * *kind* of verification finding instead of regex-matching free-text
+ * strings.
+ *
+ * The enum value set is frozen for v1 alongside
+ * `REASON_CODE_SCHEMA_VERSION`. Adding new values requires a new ADR
+ * amending ADR-0010 + a bump to schema version 2.
+ *
+ * Cross-language byte stability: the Python SDK exposes the same value
+ * set via `reason_codes.py`. A conformance vector pins Py/TS equality
+ * in CI.
+ *
+ * This module ships ONLY the enum primitive + helpers; it does NOT
+ * modify `VerificationResult` or any verifier path's return shape.
+ * Threading is sequenced into a follow-up ADR (anticipated ADR-0015)
+ * so this ADR can ship as additive-only.
+ */
+export declare const REASON_CODE_SCHEMA_VERSION: 1;
+export type ReasonCodeV1 = 'CHAIN_OK' | 'CHAIN_SEQ_MISMATCH' | 'CHAIN_PREV_HASH_MISMATCH' | 'CHAIN_EVENT_HASH_MISMATCH' | 'SIGNATURE_OK' | 'SIGNATURE_INVALID' | 'SIGNATURE_UNKNOWN_KEY' | 'SIGNATURE_EXPIRED_KEY' | 'SIGNATURE_SCHEMA_MISMATCH' | 'SIGNATURE_PAYLOAD_MISMATCH' | 'ANCHOR_OK' | 'ANCHOR_INVALID' | 'ANCHOR_CERT_EXPIRED' | 'ANCHOR_OCSP_FAILED' | 'ANCHOR_MISSING_LTV_ARTIFACTS' | 'PAYLOAD_OK' | 'PAYLOAD_MISSING_REQUIRED_FIELD' | 'PAYLOAD_FIELD_TYPE_MISMATCH' | 'PAYLOAD_FIELD_VALUE_OUT_OF_RANGE' | 'PAYLOAD_FORBIDDEN_FIELD_PRESENT' | 'PAYLOAD_SCHEMA_VERSION_MISMATCH' | 'UNSIGNED_SEGMENT' | 'UNANCHORED_SEGMENT' | 'BUNDLE_MISSING_REQUIRED_FIELD' | 'INTERNAL_ERROR';
+export declare const ALL_REASON_CODES_V1: ReadonlySet<ReasonCodeV1>;
+export declare const REASON_CODE_DESCRIPTIONS: Readonly<Record<ReasonCodeV1, string>>;
+/**
+ * Return `true` if `code` is in `ALL_REASON_CODES_V1`. Use this in
+ * tests to catch typos at the emit site, and in downstream consumers
+ * for forward-compatible fallback ("treat unknown codes as INTERNAL_ERROR").
+ */
+export declare function isKnownReasonCode(code: string): code is ReasonCodeV1;
+/**
+ * Return `true` if `code` matches the documented uppercase regex.
+ * Useful for validating caller-supplied codes in payload `reason_code`
+ * fields where domain-specific codes are also permitted.
+ */
+export declare function reasonCodeMatchesFormat(code: string): boolean;
+//# sourceMappingURL=reason_codes.d.ts.map

package/dist/reason_codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason_codes.d.ts","sourceRoot":"","sources":["../src/reason_codes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,0BAA0B,EAAG,CAAU,CAAC;AAKrD,MAAM,MAAM,YAAY,GAEpB,UAAU,GACV,oBAAoB,GACpB,0BAA0B,GAC1B,2BAA2B,GAE3B,cAAc,GACd,mBAAmB,GACnB,uBAAuB,GACvB,uBAAuB,GACvB,2BAA2B,GAC3B,4BAA4B,GAE5B,WAAW,GACX,gBAAgB,GAChB,qBAAqB,GACrB,oBAAoB,GACpB,8BAA8B,GAE9B,YAAY,GACZ,gCAAgC,GAChC,6BAA6B,GAC7B,kCAAkC,GAClC,iCAAiC,GACjC,iCAAiC,GAEjC,kBAAkB,GAClB,oBAAoB,GACpB,+BAA+B,GAC/B,gBAAgB,CAAC;AAErB,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,YAAY,CA0BxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CA+B3E,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/reason_codes.js

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 2026 The Attestplane Authors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ReasonCodeV1 enum — machine-readable verification findings (ADR-0010).
+ *
+ * Stable string enum for downstream tooling (audit reports, EU AI Act
+ * Article 12 evidence packs, regulator dashboards) to branch on the
+ * *kind* of verification finding instead of regex-matching free-text
+ * strings.
+ *
+ * The enum value set is frozen for v1 alongside
+ * `REASON_CODE_SCHEMA_VERSION`. Adding new values requires a new ADR
+ * amending ADR-0010 + a bump to schema version 2.
+ *
+ * Cross-language byte stability: the Python SDK exposes the same value
+ * set via `reason_codes.py`. A conformance vector pins Py/TS equality
+ * in CI.
+ *
+ * This module ships ONLY the enum primitive + helpers; it does NOT
+ * modify `VerificationResult` or any verifier path's return shape.
+ * Threading is sequenced into a follow-up ADR (anticipated ADR-0015)
+ * so this ADR can ship as additive-only.
+ */
+export const REASON_CODE_SCHEMA_VERSION = 1;
+// Regex from ADR-0010 § 1: uppercase ASCII underscored, 2-64 chars.
+const REASON_CODE_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/;
+export const ALL_REASON_CODES_V1 = new Set([
+    'CHAIN_OK',
+    'CHAIN_SEQ_MISMATCH',
+    'CHAIN_PREV_HASH_MISMATCH',
+    'CHAIN_EVENT_HASH_MISMATCH',
+    'SIGNATURE_OK',
+    'SIGNATURE_INVALID',
+    'SIGNATURE_UNKNOWN_KEY',
+    'SIGNATURE_EXPIRED_KEY',
+    'SIGNATURE_SCHEMA_MISMATCH',
+    'SIGNATURE_PAYLOAD_MISMATCH',
+    'ANCHOR_OK',
+    'ANCHOR_INVALID',
+    'ANCHOR_CERT_EXPIRED',
+    'ANCHOR_OCSP_FAILED',
+    'ANCHOR_MISSING_LTV_ARTIFACTS',
+    'PAYLOAD_OK',
+    'PAYLOAD_MISSING_REQUIRED_FIELD',
+    'PAYLOAD_FIELD_TYPE_MISMATCH',
+    'PAYLOAD_FIELD_VALUE_OUT_OF_RANGE',
+    'PAYLOAD_FORBIDDEN_FIELD_PRESENT',
+    'PAYLOAD_SCHEMA_VERSION_MISMATCH',
+    'UNSIGNED_SEGMENT',
+    'UNANCHORED_SEGMENT',
+    'BUNDLE_MISSING_REQUIRED_FIELD',
+    'INTERNAL_ERROR',
+]);
+export const REASON_CODE_DESCRIPTIONS = {
+    CHAIN_OK: 'Chain integrity verified end-to-end.',
+    CHAIN_SEQ_MISMATCH: 'ChainedEvent.seq does not equal expected position in chain.',
+    CHAIN_PREV_HASH_MISMATCH: "ChainedEvent.prev_hash does not equal previous event's event_hash.",
+    CHAIN_EVENT_HASH_MISMATCH: 'ChainedEvent.event_hash does not equal hash_event(audit_event); canonicalize bytes have drifted.',
+    SIGNATURE_OK: 'Ed25519 signature verified.',
+    SIGNATURE_INVALID: 'Ed25519 verification failed (cryptographic mismatch).',
+    SIGNATURE_UNKNOWN_KEY: 'key_id is not present in the configured trust roots.',
+    SIGNATURE_EXPIRED_KEY: "verification_time falls outside the trust-root entry's validity window.",
+    SIGNATURE_SCHEMA_MISMATCH: 'signature_schema_version is unsupported by this verifier.',
+    SIGNATURE_PAYLOAD_MISMATCH: 'signed_payload bytes do not match the re-canonicalised expected payload.',
+    ANCHOR_OK: 'Anchor record verified including LTV (long-term validation) artifacts.',
+    ANCHOR_INVALID: "Anchor record's signature, hash, or format check failed.",
+    ANCHOR_CERT_EXPIRED: 'TSA certificate chain expired at verification_time.',
+    ANCHOR_OCSP_FAILED: 'OCSP response invalid, revoked, or missing for the TSA certificate.',
+    ANCHOR_MISSING_LTV_ARTIFACTS: 'tsa_cert_chain or ocsp_responses is empty; CAdES-A long-term validation unsupported.',
+    PAYLOAD_OK: 'Payload validates against its declared event schema.',
+    PAYLOAD_MISSING_REQUIRED_FIELD: 'A required payload field is absent.',
+    PAYLOAD_FIELD_TYPE_MISMATCH: 'A payload field is present but has the wrong type.',
+    PAYLOAD_FIELD_VALUE_OUT_OF_RANGE: 'A payload field has a value outside the declared enum/regex/numeric range.',
+    PAYLOAD_FORBIDDEN_FIELD_PRESENT: 'Payload contains a field name forbidden by ADR-0004 § 2 redaction policy.',
+    PAYLOAD_SCHEMA_VERSION_MISMATCH: "Payload's declared <event>_schema_version is unsupported.",
+    UNSIGNED_SEGMENT: 'Bundle contains no signature records covering this chain segment.',
+    UNANCHORED_SEGMENT: 'Bundle contains no anchor records covering this chain segment.',
+    BUNDLE_MISSING_REQUIRED_FIELD: 'A top-level proof-bundle field is absent.',
+    INTERNAL_ERROR: 'Verifier hit an unexpected condition; should not occur in conformant input.',
+};
+/**
+ * Return `true` if `code` is in `ALL_REASON_CODES_V1`. Use this in
+ * tests to catch typos at the emit site, and in downstream consumers
+ * for forward-compatible fallback ("treat unknown codes as INTERNAL_ERROR").
+ */
+export function isKnownReasonCode(code) {
+    return ALL_REASON_CODES_V1.has(code);
+}
+/**
+ * Return `true` if `code` matches the documented uppercase regex.
+ * Useful for validating caller-supplied codes in payload `reason_code`
+ * fields where domain-specific codes are also permitted.
+ */
+export function reasonCodeMatchesFormat(code) {
+    return REASON_CODE_PATTERN.test(code);
+}
+//# sourceMappingURL=reason_codes.js.map

package/dist/reason_codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason_codes.js","sourceRoot":"","sources":["../src/reason_codes.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,sCAAsC;AACtC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAU,CAAC;AAErD,oEAAoE;AACpE,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAkCrD,MAAM,CAAC,MAAM,mBAAmB,GAA8B,IAAI,GAAG,CAAe;IAClF,UAAU;IACV,oBAAoB;IACpB,0BAA0B;IAC1B,2BAA2B;IAC3B,cAAc;IACd,mBAAmB;IACnB,uBAAuB;IACvB,uBAAuB;IACvB,2BAA2B;IAC3B,4BAA4B;IAC5B,WAAW;IACX,gBAAgB;IAChB,qBAAqB;IACrB,oBAAoB;IACpB,8BAA8B;IAC9B,YAAY;IACZ,gCAAgC;IAChC,6BAA6B;IAC7B,kCAAkC;IAClC,iCAAiC;IACjC,iCAAiC;IACjC,kBAAkB;IAClB,oBAAoB;IACpB,+BAA+B;IAC/B,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAA2C;IAC9E,QAAQ,EAAE,sCAAsC;IAChD,kBAAkB,EAAE,6DAA6D;IACjF,wBAAwB,EAAE,oEAAoE;IAC9F,yBAAyB,EACvB,kGAAkG;IACpG,YAAY,EAAE,6BAA6B;IAC3C,iBAAiB,EAAE,uDAAuD;IAC1E,qBAAqB,EAAE,sDAAsD;IAC7E,qBAAqB,EAAE,yEAAyE;IAChG,yBAAyB,EAAE,2DAA2D;IACtF,0BAA0B,EACxB,0EAA0E;IAC5E,SAAS,EAAE,wEAAwE;IACnF,cAAc,EAAE,0DAA0D;IAC1E,mBAAmB,EAAE,qDAAqD;IAC1E,kBAAkB,EAAE,qEAAqE;IACzF,4BAA4B,EAC1B,sFAAsF;IACxF,UAAU,EAAE,sDAAsD;IAClE,8BAA8B,EAAE,qCAAqC;IACrE,2BAA2B,EAAE,oDAAoD;IACjF,gCAAgC,EAC9B,4EAA4E;IAC9E,+BAA+B,EAC7B,2EAA2E;IAC7E,+BAA+B,EAAE,2DAA2D;IAC5F,gBAAgB,EAAE,mEAAmE;IACrF,kBAAkB,EAAE,gEAAgE;IACpF,6BAA6B,EAAE,2CAA2C;IAC1E,cAAc,EAAE,6EAA6E;CAC9F,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAQ,mBAA2C,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}