@avi770/testteam 3.0.0 → 3.2.0

package/dist/core/compliance/auditor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * ComplianceAuditor (#18 — "The Inspector") — implementation.
+ *
+ * Continuous/composite operational layer that REUSES engine-agent output (agents
+ * #65/#66/#67/#84) as control evidence. It never re-scans and never changes the
+ * system (read-only, assess+evidence+flag only).
+ *
+ * Key design decisions (all 16 improvements):
+ *  #1  — event-driven; maps controls to existing findings, no re-scan.
+ *  #2  — every control links to live evidence + last-verified stamp.
+ *  #4  — continuous monitoring: re-evaluates on each `evaluate()` call.
+ *  #7  — tamper-evident vault: SHA-256 hash chain; detects any post-hoc change.
+ *  #8  — audit-ready export per framework.
+ *  #9  — gap analysis + remediation hints.
+ *  #10 — drift alerts fire ONLY on passing→failing TRANSITIONS (prior-state compare).
+ *  #16 — honesty guardrail: never "compliant" without positive proof; never rounds up;
+ *         "not legal advice" disclaimer on every evidence pack.
+ *
+ * DISCLAIMER: Produces engineering compliance evidence. NOT legal advice.
+ */
+import type { Finding } from '../types.js';
+import type { AuditEvidencePack, ComplianceControl, ComplianceFramework, ComplianceGap, CompliancePosture, ControlEvaluation, DriftAlert, EvidenceVaultEntry, FrameworkSummary, PatternCompileError } from './types.js';
+/**
+ * The real engine agents this auditor composes as control evidence. These ids are
+ * registered engine agents (bridge/agent-registry); an integration test asserts they
+ * still exist, so an engine renumber breaks the build. The auditor ingests their
+ * Finding[] output by agentId (ComplianceControl.provedByAgentIds) — it never re-scans.
+ */
+export declare const COMPOSED_ENGINE_AGENTS: {
+    readonly gdprComplianceTester: 65;
+    readonly soc2ControlValidator: 66;
+    readonly wcagAuditor: 67;
+    readonly governanceSecurity: 84;
+};
+/** The default control catalogue shipped with the module. */
+export declare const DEFAULT_CONTROLS: readonly ComplianceControl[];
+/** Append-only, hash-chained evidence vault. Tampering with any past entry
+ *  makes `verifyChain()` return false. */
+export declare class EvidenceVault {
+    private readonly entries;
+    private readonly clock;
+    constructor(options?: {
+        readonly clock?: () => string;
+    });
+    /** Append a new entry and return the sealed record. */
+    append(controlId: string, payload: Finding): EvidenceVaultEntry;
+    get all(): readonly EvidenceVaultEntry[];
+    /**
+     * Verifies the entire hash chain is intact.
+     * Returns true when no entry has been modified since it was appended.
+     * Returns false if ANY entry's hash no longer matches (tampering detected).
+     */
+    verifyChain(): boolean;
+    /** Hash of the latest entry (transitively commits to the whole chain), or GENESIS if empty. */
+    get headHash(): string;
+    /**
+     * Detect tampering INCLUDING tail-truncation/reordering by comparing against a previously
+     * captured anchor {length, headHash}. verifyChain() alone cannot detect deletion of the
+     * newest entries (a shorter chain still verifies); an external anchor can.
+     */
+    verifyAgainstAnchor(anchor: {
+        readonly length: number;
+        readonly headHash: string;
+    }): boolean;
+}
+export interface AuditorOptions {
+    /** Override the built-in control catalogue (e.g. to inject test fixtures). */
+    readonly controls?: readonly ComplianceControl[];
+    /** Injectable clock — ISO string. */
+    readonly clock?: () => string;
+}
+/**
+ * Call `evaluate()` on every new batch of engine findings. The returned
+ * posture reflects the current moment. Drift alerts fire ONLY on
+ * passing→failing transitions (prior-state compare, improvement #10).
+ * History lives in the vault; caller persists it across invocations for a
+ * full audit trail.
+ *
+ * Controls with malformed regex patterns are surfaced as `patternErrors`
+ * and evaluated as `no-evidence` (fail-closed, never silently pass).
+ */
+export declare class ComplianceAuditor {
+    private readonly compiled;
+    readonly vault: EvidenceVault;
+    private readonly clock;
+    /**
+     * Prior evaluation statuses — used for passing→failing drift detection.
+     * Keyed by controlId. Populated after the first `evaluate()` call.
+     */
+    private lastEvaluations;
+    /** Pattern-compile errors discovered at construction time. */
+    readonly patternErrors: readonly PatternCompileError[];
+    constructor(options?: AuditorOptions);
+    /**
+     * Ingest a fresh batch of engine-agent findings and return the current
+     * compliance posture. Event-driven: called whenever agent findings change
+     * (improvement #1/#4).
+     *
+     * Honesty rule (improvement #16): a control is NEVER reported "passing"
+     * unless at least one relevant finding from the correct engine agent is
+     * present AND it MATCHES provedByFindingPattern AND no breach pattern
+     * matches. Absence of positive proof = no-evidence.
+     *
+     * Drift alerts (improvement #10): fired ONLY when a control transitions
+     * from 'passing' to 'failing' — not on the first-ever breach evaluation.
+     */
+    evaluate(batch: Readonly<Record<number, readonly Finding[]>>): CompliancePosture;
+    /**
+     * Generate an audit-ready evidence pack for a single target framework
+     * (improvement #8). Only controls relevant to that framework are included.
+     * Never reports a framework as fully compliant when gaps remain (improvement #16).
+     */
+    auditPack(framework: ComplianceFramework, posture: CompliancePosture): AuditEvidencePack;
+    private evaluateControl;
+}
+export declare function buildDriftAlert(control: ComplianceControl, breachFinding: Finding, now: string): DriftAlert;
+export declare function buildGaps(controls: readonly ComplianceControl[], evaluations: readonly ControlEvaluation[]): ComplianceGap[];
+export declare function buildFrameworkSummary(controls: readonly ComplianceControl[], evaluations: readonly ControlEvaluation[]): Readonly<Partial<Record<ComplianceFramework, FrameworkSummary>>>;
+//# sourceMappingURL=auditor.d.ts.map

package/dist/core/compliance/auditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../../../core/compliance/auditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EAEjB,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAEhB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;CAKzB,CAAC;AAsGX,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,EAAE,SAAS,iBAAiB,EAmH/C,CAAC;AAwBX;0CAC0C;AAC1C,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAIvD,uDAAuD;IACvD,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACf,kBAAkB;IAUrB,IAAI,GAAG,IAAI,SAAS,kBAAkB,EAAE,CAEvC;IAED;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAiBtB,+FAA+F;IAC/F,IAAI,QAAQ,IAAI,MAAM,CAIrB;IAED;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;CAO7F;AAMD,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqD;IAC9E,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAiD;IAExE,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;gBAE3C,OAAO,CAAC,EAAE,cAAc;IAqBpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC,GAAG,iBAAiB;IAkEhF;;;;OAIG;IACH,SAAS,CACP,SAAS,EAAE,mBAAmB,EAC9B,OAAO,EAAE,iBAAiB,GACzB,iBAAiB;IA2CpB,OAAO,CAAC,eAAe;CAwFxB;AAMD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,EAAE,OAAO,EACtB,GAAG,EAAE,MAAM,GACV,UAAU,CAYZ;AAED,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,aAAa,EAAE,CAmCjB;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAwBlE"}