/**
 * PostToolAuditEnricher -- Policy-gated, field-aware enrichment of post-tool
 * audit events.
 *
 * Problem:
 *   The existing PostToolUse audit chain captures metadata (tool name, agent,
 *   cycle, duration) but NOT the params an agent passed in nor the results
 *   returned. This blinds forensics: auditors can see WHICH tool was called
 *   but not WHAT was passed or returned.
 *
 * Solution:
 *   Default-deny. No params/results are logged unless an operator explicitly
 *   configures an enrichment rule for a (orgId, agentId, packId, toolName)
 *   tuple. Rules specify per-field redaction modes so sensitive fields are
 *   hashed, tokenized, or redacted before they enter the audit chain.
 *
 * Redaction modes:
 *   redact    -- field replaced with '<REDACTED>'. Credentials, raw tokens.
 *   hash      -- field replaced with 'sha256:<16-hex-chars>'. PHI/PII.
 *               Same value => same hash. Operators can verify presence without
 *               seeing raw value.
 *   tokenize  -- field replaced with 'tok_<8-hex>_<seq>'. Per-org reversible.
 *               Operators retain the de-tokenization map. Auditors may request
 *               resolution via operator cooperation.
 *   log       -- explicit pass-through. Field logged unredacted.
 *
 * Default-deny semantic:
 *   If `enabledForTools` for the agent's bound packs does NOT list toolName,
 *   enricher falls back to existing metadata-only TOOL_INVOCATION_COMPLETED
 *   event. Operators must opt in tool-by-tool. Avoids accidental leakage from
 *   an unreviewed tool schema.
 *
 * FieldPath syntax:
 *   Dot notation: 'metadata.userId' resolves obj.metadata.userId.
 *   Array wildcard: 'attachments[*].content' applies to each element.
 *   Exact match only -- no fuzzy/partial matching (see PT-AUDIT-ENRICH-1).
 *
 * Tokenization (v0):
 *   Tokens stored in-memory Map per org. Same value -> same token within org.
 *   Cross-org lookup is rejected (PT-AUDIT-ENRICH-3).
 *   V1 plan: persist token map to operator-side tokenization vault (out of scope
 *   for this PR).
 *
 * Integration order (relative to PR #14 ToolRateLimiter):
 *   1. PreToolUse: ToolRateLimiter.hook() -- rate check (throws if exceeded)
 *   2. Tool executes
 *   3. PostToolUse: ToolRateLimiter implicitly recorded (counter already
 *      incremented in step 1); enrichAndEmit() fires AFTER the tool result
 *      is available. The rate-limit counter is updated before the audit event
 *      is emitted (no double-count risk).
 *
 * Pen-test gates:
 *   PT-AUDIT-ENRICH-1: redaction-bypass via field aliasing. Defence is exact
 *     fieldPath match only. Known limitation documented. Audit chain records
 *     unmatched field names so operators can spot alias attacks.
 *   PT-AUDIT-ENRICH-2: hash-collision lookup. SHA-256 full digest; 64-bit
 *     prefix is the logged representation. Pre-image resistance is computationally
 *     infeasible for SHA-256 (2^256 space). Full hash stored internally for
 *     deduplication; only 16-char prefix emitted in audit event.
 *   PT-AUDIT-ENRICH-3: tokenization cross-org leakage. Token map is keyed
 *     per orgId. Cross-org token lookup produces a NEW token (not org-A's value).
 *
 * Compliance references:
 *   HIPAA 164.312(b): Audit Controls -- tamper-evident activity logging
 *   GDPR Art. 5(2): Accountability -- demonstrable compliance records
 *   PCI DSS Req 10.2: Audit log events per security-related action
 *   DORA Art. 9: ICT risk -- tool-invocation traceability
 *   SOC 2 CC7.2: monitoring of system components
 *
 * BUILD_PLAN reference: line 237 "Post-tool-invocation audit enriched with
 * full parameter + result logging (currently metadata-only)".
 *
 * @connexum/ai-governance
 */
export declare const ENRICHMENT_STRICT_MODE_PACKS: ReadonlySet<string>;
export type FieldRedactionMode = 'redact' | 'hash' | 'tokenize' | 'log';
export interface FieldRedactionRule {
    /**
     * Dot-notation path to the field, e.g. 'path', 'metadata.userId'.
     * Array wildcard: 'attachments[*].content' applies to each element.
     * Exact match only -- no fuzzy/partial matching (PT-AUDIT-ENRICH-1).
     */
    fieldPath: string;
    /** How to handle this field in the audit event. */
    mode: FieldRedactionMode;
}
export interface ToolEnrichmentRule {
    /** Compliance pack that owns this rule. */
    packId: string;
    /** Name of the tool this rule applies to. */
    toolName: string;
    /** Redaction rules for tool invocation params. */
    paramRules: FieldRedactionRule[];
    /** Redaction rules for tool result fields. */
    resultRules: FieldRedactionRule[];
}
/**
 * TOOL_INVOCATION_COMPLETED -- metadata-only fallback event.
 * Emitted when no enrichment rule is registered for the tool (default-deny).
 * This mirrors the existing audit emission before this feature existed.
 */
export interface ToolInvocationCompletedEvent {
    type: 'TOOL_INVOCATION_COMPLETED';
    severity: 'NOTICE' | 'WARNING';
    orgId: string;
    agentId: string;
    cycleId: string;
    toolName: string;
    success: boolean;
    durationMs: number;
    packBinding: string[];
    timestampNs: string;
    prevSha: string;
}
/**
 * TOOL_INVOCATION_ENRICHED -- full params + results with field-level redaction.
 * Emitted when an enrichment rule is registered for the tool.
 */
export interface ToolInvocationEnrichedEvent {
    type: 'TOOL_INVOCATION_ENRICHED';
    severity: 'NOTICE' | 'WARNING';
    orgId: string;
    agentId: string;
    cycleId: string;
    toolName: string;
    success: boolean;
    durationMs: number;
    packBinding: string[];
    /**
     * Redacted/hashed/tokenized params. Fields not covered by paramRules are
     * logged as-is (operator chose to include them by registering an enrichment
     * rule for this tool -- any uncovered field is their responsibility).
     */
    enrichedParams: Record<string, unknown>;
    /**
     * Redacted/hashed/tokenized result fields.
     */
    enrichedResult: Record<string, unknown>;
    /**
     * Field paths that were present in params/result but had NO matching rule.
     * Logged so operators can spot alias attacks (PT-AUDIT-ENRICH-1).
     */
    unmatchedParamFields: string[];
    unmatchedResultFields: string[];
    timestampNs: string;
    prevSha: string;
}
/**
 * ENRICHMENT_POLICY_VIOLATION -- emitted when a strict-pack agent invokes a
 * tool that has an enrichment rule registered BUT the rule is missing required
 * coverage (e.g., no rule for a strict-pack-sensitive tool).
 *
 * Severity ERROR.
 */
export interface EnrichmentPolicyViolationEvent {
    type: 'ENRICHMENT_POLICY_VIOLATION';
    severity: 'ERROR';
    orgId: string;
    agentId: string;
    cycleId: string;
    toolName: string;
    violatingPackId: string;
    reason: string;
    packBinding: string[];
    timestampNs: string;
    prevSha: string;
}
export type PostToolAuditEvent = ToolInvocationCompletedEvent | ToolInvocationEnrichedEvent | EnrichmentPolicyViolationEvent;
export declare class EnrichmentUnboundError extends Error {
    readonly context: string;
    constructor(context: string);
}
export declare class PostToolAuditEnricher {
    /**
     * rule registry key: `${orgId}::${agentId}::${toolName}`
     * Value: first registered rule wins. Multiple configure() calls for the same
     * key overwrite (last-write wins; operators should configure once at startup).
     */
    private readonly rules;
    /** Per-org token stores for tokenization. */
    private readonly tokenStores;
    /** SHA chain: tracks the SHA-256 of the previous event. */
    private prevSha;
    /** Audit sink: receives all emitted events. */
    private readonly auditSink;
    constructor(auditSink?: (event: PostToolAuditEvent) => void);
    /**
     * Register an enrichment policy for a specific (org, agent, tool) tuple.
     *
     * Operator-side call. Should be invoked once at agent startup for each tool
     * that should have enriched audit logging. Tools NOT registered here fall
     * back to metadata-only TOOL_INVOCATION_COMPLETED (default-deny).
     *
     * @param orgId      Tenant/org identifier.
     * @param agentId    Agent identifier.
     * @param packId     Compliance pack that owns this rule.
     * @param toolName   Tool name (e.g., 'filesystem.read', 'http.fetch').
     * @param paramRules Field redaction rules for invocation params.
     * @param resultRules Field redaction rules for tool result.
     */
    configure(orgId: string, agentId: string, packId: string, toolName: string, paramRules: FieldRedactionRule[], resultRules: FieldRedactionRule[]): void;
    /**
     * Returns whether enrichment is enabled for a given (org, agent, tool) tuple.
     */
    getEnrichmentStatus(orgId: string, agentId: string, toolName: string): boolean;
    /**
     * Apply field-redaction rules and emit an audit event.
     *
     * If no rule is registered for the tool -> emits TOOL_INVOCATION_COMPLETED
     * (metadata-only, default-deny).
     *
     * If a rule is registered -> emits TOOL_INVOCATION_ENRICHED with redacted
     * params + result fields.
     *
     * Severity:
     *   NOTICE  -- success=true
     *   WARNING -- success=false (tool-side error)
     *
     * Strict-pack policy violation:
     *   If the agent is bound to a strict pack (HIPAA, GDPR, PCI DSS, HMDA, DORA)
     *   and the tool is NOT configured for enrichment, an
     *   ENRICHMENT_POLICY_VIOLATION event (ERROR) is emitted BEFORE falling back
     *   to the metadata-only event.
     *
     * @param orgId       Tenant/org identifier.
     * @param agentId     Agent identifier.
     * @param cycleId     Current governance cycle identifier.
     * @param toolName    Tool name.
     * @param params      Raw tool invocation params.
     * @param result      Raw tool result (may be error object).
     * @param durationMs  Tool execution duration in milliseconds.
     * @param packBinding Active compliance pack IDs for this agent.
     */
    enrichAndEmit(orgId: string, agentId: string, cycleId: string, toolName: string, params: Record<string, unknown>, result: unknown, durationMs: number, packBinding: string[]): void;
    /**
     * Apply a set of FieldRedactionRules to a flat-or-nested object.
     *
     * Returns:
     *   enriched   -- copy of obj with rule-matching fields redacted/hashed/tokenized.
     *   unmatched  -- leaf field paths present in obj that had no matching rule.
     *                 Logged so operators can detect alias attacks (PT-AUDIT-ENRICH-1).
     */
    private applyRules;
    /**
     * Recursively visit all leaf paths in obj.
     * For each leaf: if a matching rule exists, apply redaction mode.
     * Otherwise, push path to unmatched list (PT-AUDIT-ENRICH-1 alias detection).
     *
     * Supports:
     *   - Dot notation: 'metadata.userId'
     *   - Array wildcard: 'attachments[*].content' via '[*]' segment
     */
    private visitLeaves;
    /**
     * Return all candidate path strings to check in ruleMap for a given prefix.
     * Handles both exact paths and array-wildcard normalization.
     */
    private candidatePaths;
    /**
     * Apply a single redaction mode to a raw string value.
     *
     * redact   -> '<REDACTED>'
     * hash     -> 'sha256:<16-hex>' (first 16 hex chars of SHA-256)
     * tokenize -> 'tok_<8-hex>_<seq>' (per-org reversible token)
     * log      -> raw value (explicit pass-through)
     */
    private applyMode;
    private ruleKey;
    private getOrCreateTokenStore;
    private normalizeResult;
    private deepClone;
    /**
     * Emit an audit event and advance the SHA-256 chain.
     * Chain ensures replay or modification is detectable.
     */
    private emitAndChain;
    /**
     * Return current time as nanoseconds (string).
     */
    private nowNs;
    /**
     * Expose current prevSha for chain verification in tests.
     */
    getCurrentChainHash(): string;
}
//# sourceMappingURL=post-tool-audit-enrichment.d.ts.map