@connexum/ai-governance 1.0.0-beta.11

package/dist/esm/retention/classification-rules.js.map

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

package/dist/esm/retention/classifier.js

@@ -0,0 +1,243 @@
+/**
+ * DataClassifier -- Stamps DataClassTag on every stored record.
+ *
+ * Usage at every storage write site:
+ *
+ *   const tag = classifier.classify('audit:chain:append', {
+ *     tenantId: 'tenant-abc',
+ *     contractId: 'contract-xyz',
+ *     activePackIds: ['hipaa', 'soc2'],
+ *   });
+ *   // attach tag to the record before writing
+ *
+ * FAIL-CLOSED invariants:
+ *   - Unknown write site  => UnclassifiedWriteError thrown synchronously (AC 19)
+ *   - Empty packBinding   => UnboundDataError thrown synchronously (AC 1b)
+ *
+ * Pack-binding change audit (AC 1d):
+ *   - emitPackBindingChangedEvent() emits retention:pack-binding-changed
+ *   - retentionWindowElapsed() stubs the window check until P4-RET-02 ships
+ *
+ * Error hierarchy:
+ *   RetentionError extends LlmProviderError (unified error hierarchy pattern)
+ *     UnclassifiedWriteError extends RetentionError
+ *     UnboundDataError extends RetentionError
+ *
+ * @connexum/ai-governance
+ */
+import { LlmProviderError } from '../llm-adapters/index.js';
+import { DEFAULT_CLASSIFICATION_RULES, } from './classification-rules.js';
+// ---------------------------------------------------------------------------
+// Error hierarchy
+// ---------------------------------------------------------------------------
+/**
+ * Base class for all retention-engine errors.
+ * Extends LlmProviderError to sit in the unified error hierarchy.
+ */
+export class RetentionError extends LlmProviderError {
+    constructor(opts) {
+        super({
+            message: opts.message,
+            code: opts.code,
+            // Retention errors are not provider-specific. We use sentinel values
+            // so callers can distinguish them via instanceof RetentionError without
+            // inspecting providerId.
+            providerId: 'retention-engine',
+            adapterId: 'retention-engine',
+        });
+        this.name = 'RetentionError';
+    }
+}
+/**
+ * Thrown synchronously when a write site has no matching classification rule.
+ * The write is refused at the storage call site -- there is no silent fallback.
+ *
+ * AC 3, AC 19.
+ */
+export class UnclassifiedWriteError extends RetentionError {
+    writeSite;
+    constructor(writeSite) {
+        super({
+            message: `UnclassifiedWriteError: no classification rule for write site "${writeSite}". ` +
+                'Register a rule in classification-rules.ts or correct the write-site identifier.',
+            code: 'UNCLASSIFIED_WRITE',
+        });
+        this.name = 'UnclassifiedWriteError';
+        this.writeSite = writeSite;
+    }
+}
+/**
+ * Thrown synchronously when the resolved packBinding is empty.
+ * This means the tenant has no active packs -- writes are refused until
+ * at least one compliance pack is activated.
+ *
+ * AC 1b.
+ */
+export class UnboundDataError extends RetentionError {
+    writeSite;
+    tenantId;
+    constructor(writeSite, tenantId) {
+        super({
+            message: `UnboundDataError: empty packBinding for write site "${writeSite}", ` +
+                `tenant "${tenantId}". A tenant with no active compliance packs cannot ` +
+                'produce compliance-bound data. Activate at least one pack before writing.',
+            code: 'UNBOUND_DATA',
+        });
+        this.name = 'UnboundDataError';
+        this.writeSite = writeSite;
+        this.tenantId = tenantId;
+    }
+}
+/**
+ * Emit a pack-binding-changed audit event.
+ *
+ * Callers should forward the returned event to the tamper-evident audit chain.
+ * This function validates that the un-binding attempt is legal -- if the
+ * retention window has not elapsed for any removed pack, the call throws.
+ *
+ * P4-RET-02 (2026-05-12): the window check is now resolver-injected.
+ * The default resolver is `defaultRetentionWindowResolver` which always
+ * returns `false` (refuse un-binding) — backward-compatible with the
+ * pre-2026-05-12 hardcoded stub. Production callers pass a real resolver
+ * via `opts.retentionResolver` to enable legitimate post-window un-binding.
+ *
+ * AC 1d.
+ */
+export function emitPackBindingChangedEvent(before, after, recordId, actor, reason, opts = {}) {
+    // Determine packs being removed.
+    const removed = before.filter((p) => !after.includes(p));
+    const resolver = opts.retentionResolver ?? defaultRetentionWindowResolver;
+    for (const packId of removed) {
+        if (!resolver(recordId, packId)) {
+            throw new RetentionError({
+                message: `Cannot remove pack "${packId}" from record "${recordId}": ` +
+                    `retention window has not elapsed. Un-binding a pack before its ` +
+                    `retention window closes would bypass the retention obligation.`,
+                code: 'RETENTION_WINDOW_NOT_ELAPSED',
+            });
+        }
+    }
+    return {
+        type: 'retention:pack-binding-changed',
+        recordId,
+        before,
+        after,
+        actor,
+        reason,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Default fail-closed resolver. Always returns `false` — un-binding is
+ * refused. This is the safer default and matches the pre-P4-RET-02
+ * stub behaviour, so callers that do NOT pass a resolver get exactly
+ * the conservative behaviour they had before.
+ *
+ * Production callers wire a real resolver via
+ * `createRetentionWindowResolver()` or supply a fully custom resolver.
+ */
+export const defaultRetentionWindowResolver = () => false;
+/**
+ * Backward-compatible alias for the pre-P4-RET-02 stub function.
+ * Kept exported so any external callers continue to compile. New code
+ * should pass a `retentionResolver` to `emitPackBindingChangedEvent`
+ * instead of calling this directly.
+ *
+ * @deprecated use `defaultRetentionWindowResolver` or pass a real
+ *             `retentionResolver` to `emitPackBindingChangedEvent`.
+ */
+export function retentionWindowElapsed(_recordId, _packId) {
+    return defaultRetentionWindowResolver(_recordId, _packId);
+}
+/**
+ * Build a production retention-window resolver from a record lookup +
+ * pack retention table. Returns `true` only when both (a) the record's
+ * createdAt is known AND (b) the pack's retention floor is known AND
+ * (c) `now() - createdAt > retentionDays * 24h`. Any uncertainty
+ * returns `false` (fail-closed).
+ *
+ * Wiring pattern:
+ *   const resolver = createRetentionWindowResolver({
+ *     lookupRecordCreatedAt: id => recordCache.get(id)?.createdAt ?? null,
+ *     packRetentionDays: new Map(
+ *       activePacks.map(p => [p.id, p.retentionPolicy.auditLogRetentionDays]),
+ *     ),
+ *   });
+ *   emitPackBindingChangedEvent(before, after, recordId, actor, reason,
+ *     { retentionResolver: resolver });
+ */
+export function createRetentionWindowResolver(options) {
+    const now = options.now ?? Date.now;
+    return (recordId, packId) => {
+        const createdAt = options.lookupRecordCreatedAt(recordId);
+        if (!createdAt)
+            return false;
+        const retentionDays = options.packRetentionDays.get(packId);
+        if (typeof retentionDays !== 'number' || retentionDays <= 0)
+            return false;
+        const retentionMs = retentionDays * 24 * 60 * 60 * 1000;
+        return now() - createdAt.getTime() > retentionMs;
+    };
+}
+export class DataClassifier {
+    rules;
+    constructor(options = {}) {
+        this.rules = options.rules ?? DEFAULT_CLASSIFICATION_RULES;
+    }
+    /**
+     * Classify a storage write.
+     *
+     * Matches `writeSite` against the rule table. On match, resolves
+     * packBinding by intersecting ctx.activePackIds with the rule's resolver
+     * output. Throws synchronously on any invariant violation.
+     *
+     * @param writeSite  Stable identifier for the storage call site
+     *                   (e.g. 'audit:chain:append').
+     * @param ctx        Tenant + contract context with active pack IDs.
+     * @returns DataClassTag stamped with the resolved classification.
+     * @throws UnclassifiedWriteError if no rule matches.
+     * @throws UnboundDataError if resolved packBinding is empty.
+     */
+    classify(writeSite, ctx) {
+        const fullCtx = { ...ctx };
+        // Find matching rule (first match wins; rules are ordered by specificity).
+        const rule = this.matchRule(writeSite);
+        if (!rule) {
+            throw new UnclassifiedWriteError(writeSite);
+        }
+        // Resolve pack binding.
+        const resolvedPacks = rule.packBindingResolver(fullCtx);
+        // Intersect with caller's active pack IDs (AC 1b).
+        const packBinding = resolvedPacks.filter((p) => fullCtx.activePackIds.includes(p));
+        if (packBinding.length === 0) {
+            throw new UnboundDataError(writeSite, ctx.tenantId);
+        }
+        const sovereigntyZone = rule.sovereigntyResolver(fullCtx);
+        const tag = {
+            tenantId: ctx.tenantId,
+            contractId: ctx.contractId,
+            dataClass: rule.dataClass,
+            packBinding,
+            sovereigntyZone,
+            classifiedAt: new Date().toISOString(),
+        };
+        return tag;
+    }
+    /**
+     * Returns the matching rule for a write site, or null if none matches.
+     */
+    matchRule(writeSite) {
+        for (const rule of this.rules) {
+            if (typeof rule.writeSitePattern === 'string') {
+                if (rule.writeSitePattern === writeSite)
+                    return rule;
+            }
+            else {
+                if (rule.writeSitePattern.test(writeSite))
+                    return rule;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=classifier.js.map

package/dist/esm/retention/classifier.js.map

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

package/dist/esm/retention/data-class.js

@@ -0,0 +1,44 @@
+/**
+ * DataClassTag, DataClass, and SovereigntyZone -- Core types for the
+ * P4-RET-01 data classification foundation.
+ *
+ * Pack binding is the PRIMARY architectural invariant (Thomas directive
+ * 2026-04-22, feedback_pack_binding_primacy.md). Every stored artefact
+ * carries a non-empty `packBinding` that ties it to the compliance pack(s)
+ * governing it for the owning tenant.
+ *
+ * AC 1: DataClassTag shape.
+ * AC 2: DataClass closed enum (11 values).
+ * SovereigntyZone: 8-value union for data-residency enforcement.
+ *
+ * @connexum/ai-governance
+ */
+// ---------------------------------------------------------------------------
+// DataClass enum (AC 2)
+// ---------------------------------------------------------------------------
+/**
+ * Closed enumeration of all data classes the retention engine recognises.
+ * Adding a new class here requires:
+ *   1. A corresponding rule in classification-rules.ts.
+ *   2. A new unit test in tests/retention-classifier.test.ts.
+ *   3. Updated pack-binding invariant docs in docs/.
+ */
+export var DataClass;
+(function (DataClass) {
+    DataClass["AuditEvent"] = "audit-event";
+    DataClass["SessionState"] = "session-state";
+    DataClass["ApprovalQueueItem"] = "approval-queue-item";
+    DataClass["ComplianceReport"] = "compliance-report";
+    DataClass["AgentRegistration"] = "agent-registration";
+    DataClass["PolicySnapshot"] = "policy-snapshot";
+    DataClass["PiiRecord"] = "pii-record";
+    DataClass["PhiRecord"] = "phi-record";
+    DataClass["FinancialRecord"] = "financial-record";
+    DataClass["DiscoveryArtefact"] = "discovery-artefact";
+    DataClass["BackupIndex"] = "backup-index";
+    // Mortgage-industry data classes (MORTGAGE-PACKS-01, 2026-04-22)
+    DataClass["MortgageApplicationRecord"] = "mortgage-application-record";
+    DataClass["HmdaLarEntry"] = "hmda-lar-entry";
+    DataClass["ConsumerReportRecord"] = "consumer-report-record";
+})(DataClass || (DataClass = {}));
+//# sourceMappingURL=data-class.js.map

package/dist/esm/retention/data-class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-class.js","sourceRoot":"","sources":["../../../src/retention/data-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,SAgBX;AAhBD,WAAY,SAAS;IACnB,uCAAuC,CAAA;IACvC,2CAAyC,CAAA;IACzC,sDAA+C,CAAA;IAC/C,mDAA6C,CAAA;IAC7C,qDAA8C,CAAA;IAC9C,+CAA2C,CAAA;IAC3C,qCAAsC,CAAA;IACtC,qCAAsC,CAAA;IACtC,iDAA4C,CAAA;IAC5C,qDAA8C,CAAA;IAC9C,yCAAwC,CAAA;IACxC,iEAAiE;IACjE,sEAAyD,CAAA;IACzD,4CAA4C,CAAA;IAC5C,4DAAoD,CAAA;AACtD,CAAC,EAhBW,SAAS,KAAT,SAAS,QAgBpB"}

package/dist/esm/retention/enforcement-log-store.js

@@ -0,0 +1,145 @@
+/**
+ * RetentionEnforcementLogStore -- F-NEW-RETENTION-ENFORCEMENT-TRACKER
+ *
+ * Persists per-store enforcement run history so the
+ * GET /api/v1/retention/store-enforcement/:tenantId endpoint can return
+ * real timestamps instead of null, upgrading dataMode from
+ * 'policy-matrix-only' to 'full'.
+ *
+ * Architecture note:
+ *   DbRetentionSweep runs globally (not per-tenant) and sweeps tables by
+ *   retentionAt. AggregatorReconciler runs per-tenant. RetentionManager
+ *   is write-time.
+ *
+ *   For the 'db' store we record one log entry per DbRetentionSweep.runOnce()
+ *   invocation, aggregating across all tenants in that run. The storeName is
+ *   always 'db' for these entries, and tenantId is set to the special sentinel
+ *   GLOBAL_DB_SWEEP_TENANT to indicate a global (multi-tenant) sweep.
+ *
+ *   For log-aggregator stores (splunk, datadog, sentinel) the AggregatorReconciler
+ *   calls recordRun() per-tenant after each reconcileTenant() call. storeName
+ *   is 'splunk' | 'datadog' | 'sentinel'.
+ *
+ *   The endpoint for tenantId=X reads rows for that tenant OR the global sweep
+ *   sentinel so it can surface db sweep history even before per-tenant tracking
+ *   is wired.
+ *
+ * In-memory implementation is the default (sidecar mode, tests). The
+ * InMemoryEnforcementLogStore is used when no DATABASE_URL is configured.
+ * A PostgreSQL-backed implementation wrapping PrismaClient can be substituted
+ * by passing an adapter to the store-enforcement endpoint.
+ *
+ * @connexum/ai-governance
+ */
+import * as crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Sentinel tenant ID for global (non-per-tenant) DB sweeps
+// ---------------------------------------------------------------------------
+export const GLOBAL_DB_SWEEP_TENANT = '__global_db_sweep__';
+// ---------------------------------------------------------------------------
+// In-memory implementation
+// ---------------------------------------------------------------------------
+export class InMemoryEnforcementLogStore {
+    entries = [];
+    async recordRun(input) {
+        const entry = {
+            id: crypto.randomUUID(),
+            tenantId: input.tenantId,
+            storeName: input.storeName,
+            startedAt: input.startedAt,
+            completedAt: input.completedAt,
+            status: input.status,
+            recordsScanned: input.recordsScanned,
+            recordsPurged: input.recordsPurged,
+            failureReason: input.failureReason ?? null,
+        };
+        this.entries.push(entry);
+        return entry;
+    }
+    async latestCompletedRunsPerStore(tenantId) {
+        const result = new Map();
+        // Completed entries for this tenant OR the global db-sweep sentinel.
+        const relevant = this.entries.filter((e) => e.status === 'completed' &&
+            (e.tenantId === tenantId || e.tenantId === GLOBAL_DB_SWEEP_TENANT));
+        // Per-store: find the entry with the latest completedAt.
+        for (const entry of relevant) {
+            const existing = result.get(entry.storeName);
+            if (!existing) {
+                result.set(entry.storeName, entry);
+            }
+            else {
+                const existingAt = existing.completedAt?.getTime() ?? 0;
+                const entryAt = entry.completedAt?.getTime() ?? 0;
+                if (entryAt > existingAt) {
+                    result.set(entry.storeName, entry);
+                }
+            }
+        }
+        return result;
+    }
+    async hasAnyCompletedRun(tenantId) {
+        return this.entries.some((e) => e.status === 'completed' &&
+            (e.tenantId === tenantId || e.tenantId === GLOBAL_DB_SWEEP_TENANT));
+    }
+    async recentFailedRuns(tenantId, sinceHours) {
+        const cutoffMs = Date.now() - sinceHours * 3600 * 1000;
+        return this.entries
+            .filter((e) => e.status === 'failed' &&
+            (e.tenantId === tenantId || e.tenantId === GLOBAL_DB_SWEEP_TENANT) &&
+            e.startedAt.getTime() >= cutoffMs)
+            .sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime());
+    }
+    /** Test helper: return all stored entries. */
+    allEntries() {
+        return this.entries;
+    }
+    /** Test helper: clear all stored entries. */
+    clear() {
+        this.entries.length = 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// trackEnforcementRun -- convenience wrapper used by DbRetentionSweep and
+// AggregatorReconciler to record a run without try/catch boilerplate at the
+// call site.
+// ---------------------------------------------------------------------------
+/**
+ * Wraps an enforcement run function, records start + completion/failure to
+ * the log store, and re-throws on failure (so the caller's error path is
+ * preserved).
+ *
+ * @param logStore   The EnforcementLogStore to record to.
+ * @param tenantId   Tenant this run belongs to (use GLOBAL_DB_SWEEP_TENANT for global sweeps).
+ * @param storeName  Which store this run operates on.
+ * @param runFn      The actual enforcement function. Must return { recordsScanned, recordsPurged }.
+ */
+export async function trackEnforcementRun(logStore, tenantId, storeName, runFn) {
+    const startedAt = new Date();
+    try {
+        const result = await runFn();
+        await logStore.recordRun({
+            tenantId,
+            storeName,
+            startedAt,
+            completedAt: new Date(),
+            status: 'completed',
+            recordsScanned: result.recordsScanned,
+            recordsPurged: result.recordsPurged,
+        });
+        return result;
+    }
+    catch (err) {
+        await logStore.recordRun({
+            tenantId,
+            storeName,
+            startedAt,
+            completedAt: new Date(),
+            status: 'failed',
+            recordsScanned: 0,
+            recordsPurged: 0,
+            failureReason: String(err),
+        });
+        throw err;
+    }
+}
+//# sourceMappingURL=enforcement-log-store.js.map

package/dist/esm/retention/enforcement-log-store.js.map

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

package/dist/esm/retention/index.js

@@ -0,0 +1,31 @@
+/**
+ * src/retention -- Barrel export for the P4-RET retention engine.
+ *
+ * Implements:
+ *   P4-RET-01 (data classification + pack-binding enforcement)
+ *   P4-RET-02 (PolicyMatrix)
+ *   P4-RET-03 (LegalHold)
+ *   P4-RET-04 (multi-store enforcement: filesystem, DB, S3, log aggregators)
+ *   P4-RET-05 (deletion audit + dashboard -- dashboard in next cycle)
+ *
+ * @connexum/ai-governance
+ */
+// --- P4-RET-01: Data classification ---
+export { DataClass, } from './data-class.js';
+export { DEFAULT_CLASSIFICATION_RULES, } from './classification-rules.js';
+export { DataClassifier, RetentionError, UnclassifiedWriteError, UnboundDataError, emitPackBindingChangedEvent, retentionWindowElapsed, defaultRetentionWindowResolver, createRetentionWindowResolver, } from './classifier.js';
+export { LegalHoldStore, makeNoOpAuditEmitter, } from './legal-hold-store.js';
+export { LegalHoldError, LegalHoldScopeEmptyError, LegalHoldNotFoundError, LegalHoldConcurrencyError, } from './legal-hold-errors.js';
+// --- P4-RET-02: PolicyMatrix ---
+export { PolicyMatrix, } from './policy-matrix.js';
+export { MissingRetentionPolicyError, ConflictingContractTermsError, InvalidPackRetentionError, } from './policy-matrix-errors.js';
+// --- P4-RET-01: Ingress DataClassifier (classifyAndTag) ---
+export { classifyAndTag, getClassifier, __resetClassifierForTest, PhiWithoutHipaaError, } from './ingest-classifier.js';
+// --- F-NEW-RETENTION-ENFORCEMENT-TRACKER: enforcement run history ---
+export { InMemoryEnforcementLogStore, trackEnforcementRun, GLOBAL_DB_SWEEP_TENANT, } from './enforcement-log-store.js';
+export { NoOpRetentionAdapter, noOpRetentionAdapter } from './log-aggregators/noop.js';
+export { SplunkRetentionAdapter } from './log-aggregators/splunk.js';
+export { DatadogRetentionAdapter } from './log-aggregators/datadog.js';
+export { SentinelRetentionAdapter } from './log-aggregators/sentinel.js';
+export { buildRetentionSchedule } from './backup-retention-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/retention/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/retention/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yCAAyC;AACzC,OAAO,EACL,SAAS,GAGV,MAAM,cAAc,CAAC;AAEtB,OAAO,EAGL,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,8BAA8B,EAC9B,6BAA6B,GAK9B,MAAM,cAAc,CAAC;AAWtB,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAW5B,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,kCAAkC;AAClC,OAAO,EACL,YAAY,GAMb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,6DAA6D;AAC7D,OAAO,EACL,cAAc,EACd,aAAa,EACb,wBAAwB,EACxB,oBAAoB,GAIrB,MAAM,qBAAqB,CAAC;AAE7B,uEAAuE;AACvE,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,sBAAsB,GAMvB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAItE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/esm/retention/ingest-classifier.js

@@ -0,0 +1,123 @@
+/**
+ * IngestClassifier -- P4-RET-01
+ *
+ * Wires DataClassifier at the audit-event ingress point.
+ *
+ * classifyAndTag() is the single entry point for all audit events entering
+ * the retention engine. It:
+ *   1. Resolves the DataClassTag for the event using DataClassifier.classify().
+ *   2. Attaches dataClass[] to the event metadata.
+ *   3. Enforces the PHI-without-HIPAA block: if the resolved dataClass is
+ *      PhiRecord and 'hipaa' is not in activePackIds, the call throws
+ *      PhiWithoutHipaaError (fail-closed -- no PHI enters the system without
+ *      an active HIPAA binding).
+ *   4. Returns the enriched event with dataClass stamped.
+ *
+ * PT-RET-5 (Unicode lookalike evasion):
+ *   The classifier matches write-site strings against the rule table using
+ *   exact-string and RegExp matching only. Write-site strings are
+ *   normalised to NFC Unicode before matching so Unicode lookalike attacks
+ *   (e.g. using Cyrillic 'а' U+0430 to impersonate ASCII 'a' U+0061) are
+ *   detected by the rule-miss guard and throw UnclassifiedWriteError.
+ *
+ * @connexum/ai-governance P4-RET-01
+ */
+import { DataClassifier, UnboundDataError, UnclassifiedWriteError, RetentionError } from './classifier.js';
+import { DataClass } from './data-class.js';
+// ---------------------------------------------------------------------------
+// PHI-without-HIPAA error
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a PHI record arrives without an active HIPAA binding.
+ *
+ * Fail-closed: PHI must not enter the system without HIPAA governance.
+ * The calling layer must activate the hipaa compliance pack for the tenant
+ * before storing any protected health information.
+ *
+ * PT-RET-5 / P4-RET-01 AC 6.
+ */
+export class PhiWithoutHipaaError extends RetentionError {
+    tenantId;
+    constructor(tenantId) {
+        super({
+            message: `PhiWithoutHipaaError: PHI record detected for tenant "${tenantId}" ` +
+                'but the hipaa compliance pack is not active. ' +
+                'Activate the hipaa pack for this tenant before storing protected health information. ' +
+                '(P4-RET-01 AC 6, PT-RET-5)',
+            code: 'PHI_WITHOUT_HIPAA',
+        });
+        this.name = 'PhiWithoutHipaaError';
+        this.tenantId = tenantId;
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton classifier instance
+// ---------------------------------------------------------------------------
+let _classifier = null;
+/**
+ * Return (or create) the shared DataClassifier instance.
+ * Custom rules can be injected via `options.rules` in tests.
+ */
+export function getClassifier(options) {
+    if (options?.rules) {
+        // Non-singleton path for tests: always create a fresh instance.
+        return new DataClassifier({ rules: options.rules });
+    }
+    if (!_classifier) {
+        _classifier = new DataClassifier();
+    }
+    return _classifier;
+}
+/**
+ * Reset the shared DataClassifier instance. For tests only.
+ * @internal
+ */
+export function __resetClassifierForTest() {
+    _classifier = null;
+}
+// ---------------------------------------------------------------------------
+// Main API
+// ---------------------------------------------------------------------------
+/**
+ * Classify an incoming audit event and stamp a DataClassTag onto it.
+ *
+ * Wraps DataClassifier.classify() with:
+ *   - NFC Unicode normalisation of writeSite (PT-RET-5 lookalike guard)
+ *   - PHI-without-HIPAA enforcement (PhiWithoutHipaaError)
+ *   - dataClass[] attachment to the result
+ *
+ * Throws:
+ *   - UnclassifiedWriteError: write site has no rule (fail-closed)
+ *   - UnboundDataError: resolved packBinding is empty
+ *   - PhiWithoutHipaaError: PHI record without active HIPAA pack
+ *
+ * @param event  The audit event to enrich (not mutated).
+ * @param ctx    Classification context.
+ * @param opts   Optional: inject custom classifier rules for tests.
+ */
+export function classifyAndTag(event, ctx, opts) {
+    // PT-RET-5: normalise writeSite to NFC Unicode to defeat lookalike substitutions.
+    // A Cyrillic 'а' (U+0430) in the write-site string will not match any
+    // ASCII rule and will hit the UnclassifiedWriteError guard.
+    const normalisedWriteSite = ctx.writeSite.normalize('NFC');
+    const classifier = getClassifier(opts);
+    // May throw UnclassifiedWriteError or UnboundDataError.
+    const tag = classifier.classify(normalisedWriteSite, {
+        tenantId: ctx.tenantId,
+        contractId: ctx.contractId,
+        activePackIds: ctx.activePackIds,
+        sovereigntyHint: ctx.sovereigntyHint,
+    });
+    // PHI-without-HIPAA block (P4-RET-01 AC 6, PT-RET-5).
+    if (tag.dataClass === DataClass.PhiRecord && !ctx.activePackIds.includes('hipaa')) {
+        throw new PhiWithoutHipaaError(ctx.tenantId);
+    }
+    return {
+        event,
+        tag,
+        dataClass: [tag.dataClass],
+    };
+}
+// Re-export error types for convenience at the ingress layer.
+export { UnclassifiedWriteError, UnboundDataError };
+//# sourceMappingURL=ingest-classifier.js.map

package/dist/esm/retention/ingest-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-classifier.js","sourceRoot":"","sources":["../../../src/retention/ingest-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAE,SAAS,EAA2C,MAAM,cAAc,CAAC;AAGlF,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IAC7C,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CAAC;YACJ,OAAO,EACL,yDAAyD,QAAQ,IAAI;gBACrE,+CAA+C;gBAC/C,uFAAuF;gBACvF,4BAA4B;YAC9B,IAAI,EAAE,mBAAmB;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAiED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,IAAI,WAAW,GAA0B,IAAI,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0C;IACtE,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,gEAAgE;QAChE,OAAO,IAAI,cAAc,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,IAAI,cAAc,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAQ,EACR,GAAwB,EACxB,IAAuC;IAEvC,kFAAkF;IAClF,sEAAsE;IACtE,4DAA4D;IAC5D,MAAM,mBAAmB,GAAG,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE3D,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAEvC,wDAAwD;IACxD,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,mBAAmB,EAAE;QACnD,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC,CAAC;IAEH,sDAAsD;IACtD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG;QACH,SAAS,EAAE,CAAC,GAAG,CAAC,SAAmB,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC"}