@kya-os/mcp 1.10.1 → 1.11.0

package/dist/audit/service.js

@@ -0,0 +1,222 @@
+import { canonicalizeJson } from '../utils/canonical-json.js';
+import { assertAuditCapabilities } from './assurance.js';
+import { AuditProtocolError, AUDIT_ERROR_CODES } from './errors.js';
+import { collectAuditEvidenceRefs, digestAuditEvent } from './integrity.js';
+import { parseAuditProducerEvent } from './schemas.js';
+/** Producer-side service: creates frozen events and applies declared delivery semantics. */
+export class AuditTrailService {
+    configuration;
+    idCounter = 0n;
+    sourceState;
+    sourceConstructionTail = Promise.resolve();
+    get auditProfile() {
+        return this.configuration.capabilities?.profile ?? 'AAP-0';
+    }
+    get capabilities() {
+        return this.configuration.capabilities;
+    }
+    constructor(configuration) {
+        if (configuration.delivery === 'buffered' &&
+            configuration.outbox?.capabilities.durability !== 'durable') {
+            throw new AuditProtocolError(AUDIT_ERROR_CODES.INVALID_CONFIGURATION, 'Buffered audit delivery requires a durable outbox provider');
+        }
+        if (configuration.capabilities !== undefined) {
+            if (configuration.capabilities.delivery !== configuration.delivery) {
+                throw new AuditProtocolError(AUDIT_ERROR_CODES.INVALID_CONFIGURATION, 'Advertised audit delivery does not match the trail delivery mode');
+            }
+            assertAuditCapabilities(configuration.capabilities);
+            if (configuration.capabilities.sourceHighWater &&
+                configuration.sourceState.capabilities.durability !== 'durable') {
+                throw new AuditProtocolError(AUDIT_ERROR_CODES.INVALID_CONFIGURATION, 'Advertised source high-water support requires durable source state');
+            }
+        }
+        this.configuration = Object.freeze({ ...configuration });
+        this.sourceState = configuration.sourceState;
+    }
+    /**
+     * A direct-mode retry is idempotent only when it rebuilds the identical frozen
+     * event: callers retrying with a stable `eventId` must also pin `occurredAt`,
+     * otherwise the recorder correctly rejects the divergent content as an
+     * event-identity conflict. Buffered redelivery is always byte-stable.
+     */
+    async record(input, options = {}) {
+        const eventId = input.eventId ?? this.nextEventId();
+        const encryptedEvidence = options.encryptedEvidence ?? [];
+        const buffered = this.configuration.delivery === 'buffered';
+        const { event, submission } = await this.withSourceConstruction(async () => {
+            const builtEvent = await this.buildAndLinkEvent(input, eventId);
+            this.assertEvidenceIsReferenced(builtEvent, encryptedEvidence);
+            const frozenSubmission = Object.freeze({
+                ledgerId: this.configuration.ledgerId,
+                // Buffered submissions are never epoch-pinned: a durable outbox item may
+                // be redelivered after an epoch rollover, where logical-ledger
+                // idempotency (not epoch pinning) carries the retry guarantee.
+                ...(buffered || this.configuration.expectedLedgerEpochId === undefined
+                    ? {}
+                    : { expectedLedgerEpochId: this.configuration.expectedLedgerEpochId }),
+                producerEvent: builtEvent,
+                encryptedEvidence: Object.freeze([...encryptedEvidence]),
+            });
+            if (buffered) {
+                // Enqueued inside the source-construction lock so items commit to the
+                // outbox in claimed source-sequence order for FIFO providers.
+                await this.configuration.outbox.enqueue(Object.freeze({
+                    eventId: builtEvent.eventId,
+                    submission: frozenSubmission,
+                    enqueuedAt: this.configuration.clock.now(),
+                    attempts: 0,
+                }));
+            }
+            return { event: builtEvent, submission: frozenSubmission };
+        });
+        if (buffered)
+            return { status: 'pending', event };
+        let entry;
+        try {
+            entry = await this.submitAndValidate(submission);
+        }
+        catch (error) {
+            this.configuration.onDeliveryFailure?.(error, event);
+            if (this.configuration.delivery === 'required')
+                throw error;
+            return { status: 'failed', event, error };
+        }
+        try {
+            await this.sourceState.markReceipted(this.configuration.sourceId, event.source.sourceSequence, entry.entryDigest);
+        }
+        catch (error) {
+            // The recorder commit is authoritative and must not be reported as
+            // failed: doing so encourages a caller to emit a new event identity.
+            this.configuration.onSourceStateFailure?.(error, event);
+        }
+        return { status: 'recorded', event, entry };
+    }
+    async flush(limit) {
+        if (this.configuration.delivery !== 'buffered')
+            return { delivered: 0, failed: 0 };
+        let delivered = 0;
+        let failed = 0;
+        const blockedSources = new Set();
+        for await (const item of this.configuration.outbox.pending(limit)) {
+            const sourceId = item.submission.producerEvent.source.sourceId;
+            if (blockedSources.has(sourceId))
+                continue;
+            try {
+                const entry = await this.submitAndValidate(item.submission);
+                try {
+                    await this.sourceState.markReceipted(sourceId, item.submission.producerEvent.source.sourceSequence, entry.entryDigest);
+                }
+                catch (error) {
+                    this.configuration.onSourceStateFailure?.(error, item.submission.producerEvent);
+                }
+                await this.configuration.outbox.markDelivered(item.eventId);
+                delivered += 1;
+            }
+            catch (error) {
+                await this.configuration.outbox.markFailed(item.eventId, error);
+                this.configuration.onDeliveryFailure?.(error, item.submission.producerEvent);
+                blockedSources.add(sourceId);
+                failed += 1;
+            }
+        }
+        return { delivered, failed };
+    }
+    async getSourceState() {
+        return this.sourceState.getState(this.configuration.sourceId);
+    }
+    /** Emits the producer's declared high-water mark as an ordinary chained event. */
+    async recordSourceHighWater(input = {}) {
+        const state = await this.getSourceState();
+        return this.record({
+            ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
+            eventType: 'audit.source_high_water',
+            action: { category: 'audit.source_high_water' },
+            outcome: 'succeeded',
+            evidence: [],
+            details: {
+                family: 'administration',
+                phase: 'source_high_water',
+                sourceSequence: state.highestEmitted,
+            },
+        });
+    }
+    async withSourceConstruction(operation) {
+        const previous = this.sourceConstructionTail;
+        let release;
+        this.sourceConstructionTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async buildAndLinkEvent(input, eventId) {
+        const claim = await this.sourceState.claimEvent(this.configuration.sourceId, eventId);
+        const event = this.buildEvent(input, eventId, claim);
+        const eventDigest = await digestAuditEvent(this.configuration.hasher, event);
+        await this.sourceState.markEmitted(this.configuration.sourceId, eventId, claim.sequence, eventDigest);
+        return event;
+    }
+    buildEvent(input, eventId, sourceClaim) {
+        return parseAuditProducerEvent({
+            ...input,
+            schema: 'https://schema.kya-os.org/v1/protocol/audit/event/v1.0.0',
+            eventId,
+            eventVersion: '1.0.0',
+            binding: this.configuration.binding,
+            occurredAt: input.occurredAt ?? this.configuration.clock.now(),
+            tenantRef: this.configuration.tenantRef,
+            source: {
+                producer: this.configuration.producer,
+                sourceId: this.configuration.sourceId,
+                sourceSequence: sourceClaim.sequence,
+                ...(sourceClaim.previousSourceEventDigest === undefined
+                    ? {}
+                    : { previousSourceEventDigest: sourceClaim.previousSourceEventDigest }),
+            },
+            privacy: input.privacy ?? this.configuration.privacy,
+        });
+    }
+    nextEventId() {
+        if (this.configuration.eventIdFactory !== undefined) {
+            return this.configuration.eventIdFactory();
+        }
+        this.idCounter += 1n;
+        return `audit_${this.configuration.clock.now()}_${this.idCounter}`;
+    }
+    assertEvidenceIsReferenced(event, encryptedEvidence) {
+        const refs = new Map(collectAuditEvidenceRefs(event).map((ref) => [ref.objectId, ref]));
+        const submittedIds = new Set();
+        for (const item of encryptedEvidence) {
+            const referenced = refs.get(item.ref.objectId);
+            if (submittedIds.has(item.ref.objectId) || referenced === undefined ||
+                canonicalizeJson(referenced) !== canonicalizeJson(item.ref)) {
+                throw new AuditProtocolError(AUDIT_ERROR_CODES.EVIDENCE_FAILURE, 'Encrypted evidence must exactly match one unique reference in the frozen event', { objectId: item.ref.objectId });
+            }
+            submittedIds.add(item.ref.objectId);
+        }
+    }
+    async submitAndValidate(submission) {
+        const entry = await this.configuration.recorder.submit(submission);
+        const eventDigest = await digestAuditEvent(this.configuration.hasher, submission.producerEvent);
+        // The binding is content-scoped: an entry from an earlier retained epoch is a
+        // legitimate logical-ledger duplicate. Epoch placement of new appends is the
+        // recorder's envelope guarantee, and epoch claims are recorder-signed and
+        // independently verifiable against checkpoints and mirrors.
+        if (entry.core.ledgerId !== submission.ledgerId ||
+            entry.eventDigest !== eventDigest ||
+            entry.core.eventDigest !== eventDigest ||
+            canonicalizeJson(entry.core.event) !== canonicalizeJson(submission.producerEvent)) {
+            throw new AuditProtocolError(AUDIT_ERROR_CODES.JOURNAL_FAILURE, 'Recorder response does not bind the submitted frozen producer event');
+        }
+        return entry;
+    }
+}
+export function createAuditTrail(configuration) {
+    return new AuditTrailService(configuration);
+}
+//# sourceMappingURL=service.js.map

package/dist/audit/service.js.map

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

package/dist/audit/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './provider-contracts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audit/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/audit/testing/index.js

@@ -0,0 +1,2 @@
+export * from './provider-contracts.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/audit/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/audit/testing/provider-contracts.d.ts

@@ -0,0 +1,51 @@
+import type { AuditHasher } from '../crypto.js';
+import type { AuditAnchorProvider } from '../providers/anchor.js';
+import type { AuditEvidenceProvider } from '../providers/evidence.js';
+import type { AuditJournalProvider } from '../providers/journal.js';
+import type { AuditCheckpointObserverProvider } from '../providers/observer.js';
+import type { AuditOutboxProvider } from '../providers/outbox.js';
+import type { SignedAuditCheckpointV1 } from '../types.js';
+export interface AuditProviderContractCheck {
+    name: string;
+    passed: boolean;
+    error?: unknown;
+}
+export interface AuditProviderContractReport {
+    providerKind: 'journal' | 'evidence' | 'observer' | 'anchor' | 'outbox';
+    passed: boolean;
+    checks: AuditProviderContractCheck[];
+}
+export declare function assertAuditProviderContract(value: AuditProviderContractReport): void;
+/** Framework-neutral executable contract for authoritative journal adapters. */
+export declare function evaluateAuditJournalProviderContract(createProvider: () => AuditJournalProvider | Promise<AuditJournalProvider>): Promise<AuditProviderContractReport>;
+/** Executable contract for encrypted evidence/retention adapters. */
+export declare function evaluateAuditEvidenceProviderContract(input: {
+    createProvider(): AuditEvidenceProvider | Promise<AuditEvidenceProvider>;
+    hasher: AuditHasher;
+}): Promise<AuditProviderContractReport>;
+export interface AuditCheckpointProviderContractFixtures {
+    first: SignedAuditCheckpointV1;
+    next: SignedAuditCheckpointV1;
+    conflict: SignedAuditCheckpointV1;
+    rollback: SignedAuditCheckpointV1;
+    /**
+     * A larger checkpoint that does NOT directly link `first` but consistently
+     * extends its tree; when provided, the observer must accept it as catch-up
+     * after a missed publication.
+     */
+    gapped?: SignedAuditCheckpointV1;
+}
+/** Executable monotonicity/split-view contract for independent observers. */
+export declare function evaluateAuditObserverProviderContract(input: {
+    createProvider(): AuditCheckpointObserverProvider | Promise<AuditCheckpointObserverProvider>;
+    fixtures: AuditCheckpointProviderContractFixtures;
+}): Promise<AuditProviderContractReport>;
+/** Executable role-separation and binding contract for supporting anchors. */
+export declare function evaluateAuditAnchorProviderContract(input: {
+    createProvider(): AuditAnchorProvider | Promise<AuditAnchorProvider>;
+    checkpoint: SignedAuditCheckpointV1;
+    otherCheckpoint: SignedAuditCheckpointV1;
+}): Promise<AuditProviderContractReport>;
+/** Executable FIFO, retry-accounting, and acknowledgement contract for outboxes. */
+export declare function evaluateAuditOutboxProviderContract(createProvider: () => AuditOutboxProvider | Promise<AuditOutboxProvider>): Promise<AuditProviderContractReport>;
+//# sourceMappingURL=provider-contracts.d.ts.map

package/dist/audit/testing/provider-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-contracts.d.ts","sourceRoot":"","sources":["../../../src/audit/testing/provider-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAmB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,KAAK,EAIV,uBAAuB,EAExB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACxE,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,0BAA0B,EAAE,CAAC;CACtC;AAkCD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,2BAA2B,GAAG,IAAI,CAQpF;AAsED,gFAAgF;AAChF,wBAAsB,oCAAoC,CACxD,cAAc,EAAE,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,GACzE,OAAO,CAAC,2BAA2B,CAAC,CA6HtC;AAmBD,qEAAqE;AACrE,wBAAsB,qCAAqC,CAAC,KAAK,EAAE;IACjE,cAAc,IAAI,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACzE,MAAM,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAmEvC;AAED,MAAM,WAAW,uCAAuC;IACtD,KAAK,EAAE,uBAAuB,CAAC;IAC/B,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,QAAQ,EAAE,uBAAuB,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,6EAA6E;AAC7E,wBAAsB,qCAAqC,CAAC,KAAK,EAAE;IACjE,cAAc,IAAI,+BAA+B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAC7F,QAAQ,EAAE,uCAAuC,CAAC;CACnD,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAkDvC;AAED,8EAA8E;AAC9E,wBAAsB,mCAAmC,CAAC,KAAK,EAAE;IAC/D,cAAc,IAAI,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrE,UAAU,EAAE,uBAAuB,CAAC;IACpC,eAAe,EAAE,uBAAuB,CAAC;CAC1C,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAevC;AAED,oFAAoF;AACpF,wBAAsB,mCAAmC,CACvD,cAAc,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,GACvE,OAAO,CAAC,2BAA2B,CAAC,CA0EtC"}