/**
 * ApprovalGateEnforcer -- Mandatory approval gates with per-class policy.
 *
 * Categorises actions into six explicit approval classes (destructive,
 * irreversible, financial, data-export, network-egress, secret-rotation),
 * applies per-class disposition policy (requires-approval /
 * auto-approve-low-risk / always-deny), and blocks synchronously until a
 * human approves, rejects, or the configured timeout elapses.
 *
 * RELATIONSHIP TO PR #24 (feat/p3-t1-autonomy-spectrum):
 *   PR #24 ships AutonomySpectrumEnforcer (Level 0-4). At Level 4 certain
 *   action classes are routed to an approval queue via `guardAction()` which
 *   returns `{ decision: 'approval-required', approvalRequestId }`. The
 *   Level 4 gate intentionally does NOT own the queue lifecycle -- it only
 *   names the classes that need gating.
 *
 *   THIS MODULE owns the gate lifecycle:
 *     - Explicit class definitions with rationale (action-classes.ts)
 *     - Per-class disposition config (ClassPolicyMap)
 *     - Synchronous blocking via Promise + polling (no busy-spin)
 *     - Audit chain writes on every decision
 *     - Replay protection in the store (PT-APPROVAL-3)
 *     - Empty packBinding[] guard (PT-APPROVAL-1)
 *     - Config validation at construction (PT-APPROVAL-2)
 *     - Authorised-approver list enforcement (PT-APPROVAL-4)
 *
 * HOOK POSITION:
 *   The gate should fire AFTER blast-radius enforcement (PR #42) but BEFORE
 *   action-isolation (PR #29). Rationale: blast-radius has already confirmed
 *   the action is within scope; the gate then checks whether it needs human
 *   sign-off before it executes. Action-isolation runs post-approval to
 *   sandbox the approved execution. As of main HEAD, PRs #42 and #29 are
 *   not yet merged, so this ordering is documented here but has no direct
 *   code coupling to either module.
 *
 * TIMEOUT SEMANTICS:
 *   On timeout, the safe default is DENY. Operators may override per-class
 *   via `ActionClassPolicy.timeoutMs`. There is no "allow on timeout" option.
 *
 * COMPLIANCE BINDINGS:
 *   HIPAA 164.308(a)(1): Security management process
 *   HIPAA 164.308(a)(3): Workforce authorisation and supervision
 *   HIPAA 164.312(a)(1): Access controls
 *   SOC 2 CC6.1: Logical access restrictions
 *   GDPR Art. 22: Automated decision-making
 *   PCI DSS Req 7: Restrict access by business need
 *   NIST 800-53 AC-3: Access enforcement
 *   ISO 27001 A.9.4.1: Information access restriction
 *
 * @connexum/ai-governance P3-T2
 */
import { ActionClass, ActionClassPolicy, ClassPolicyMap, ConfigValidationError } from './action-classes';
import { ApprovalQueueStore, PendingApproval } from './approval-queue-store';
export { ActionClass, ConfigValidationError };
export type { ActionClassPolicy, ClassPolicyMap };
export type { PendingApproval };
/** Context describing the action that triggered the gate. */
export interface ActionContext {
    /** The action class governing this action. */
    actionClass: ActionClass;
    /** Human-readable description of what the action does. */
    description: string;
    /** Agent ID or context identifier initiating the action. */
    initiator: string;
    /**
     * Compliance pack IDs governing this action.
     * Must be non-empty (PT-APPROVAL-1).
     */
    packBinding: string[];
    /**
     * Optional tenant ID for multi-tenant audit entries.
     * Used in audit log entries but not in enforcement logic.
     */
    tenantId?: string;
}
/** Result returned by `enforce()`. */
export interface EnforcementResult {
    /** Whether the action is permitted to proceed. */
    allowed: boolean;
    /**
     * How the gate reached its decision:
     *   approved             -- A human approved in time.
     *   rejected             -- A human or policy denied the action.
     *   timed-out            -- No decision before the class timeout; default deny.
     *   auto-approved        -- Class disposition is auto-approve-low-risk.
     *   always-denied        -- Class disposition is always-deny.
     *   unauthorized-approver -- The approver is not in allowedApprovers.
     */
    outcome: 'approved' | 'rejected' | 'timed-out' | 'auto-approved' | 'always-denied' | 'unauthorized-approver';
    /** The approvalId assigned, when a queue entry was created. */
    approvalId?: string;
    /** The approver identity, when a human decision was made. */
    approverId?: string;
    /** The human-supplied reason for the decision. */
    reason?: string;
    /** ISO timestamp of the gate decision. */
    decidedAt: string;
}
export interface ApprovalGateEnforcerConfig {
    /**
     * Per-class policy map. Defaults to `buildDefaultClassPolicies()`
     * (all classes require-approval) when omitted.
     *
     * PT-APPROVAL-2: validated at construction; throws ConfigValidationError
     * on invalid timeout, unknown disposition, or missing class.
     */
    classPolicies?: Partial<ClassPolicyMap>;
    /**
     * Enforcer-level default timeout in ms when a class policy does not
     * specify one. Defaults to 600_000 (10 minutes).
     */
    defaultTimeoutMs?: number;
    /**
     * Polling interval in ms used by the synchronous-blocking `enforce()`
     * call to check for a decision. Defaults to 200 ms.
     *
     * Lower values reduce latency but increase CPU usage. In tests, use
     * values as low as 10 ms for responsiveness.
     */
    pollIntervalMs?: number;
    /**
     * Optional ApprovalQueueStore implementation.
     * Defaults to InMemoryApprovalQueueStore.
     */
    store?: ApprovalQueueStore;
    /**
     * Optional audit log directory. When set, every gate decision is
     * appended to `<auditDir>/approval-gate-audit.jsonl` in addition to
     * whatever event-bus is wired.
     */
    auditDir?: string;
}
export declare class ApprovalGateEnforcer {
    private readonly cfg;
    /**
     * PT-APPROVAL-2: constructor validates the class policy map.
     * Throws ConfigValidationError immediately on invalid configuration.
     */
    constructor(config?: ApprovalGateEnforcerConfig);
    /**
     * Enforce the approval gate for a given action.
     *
     * Behaviour by disposition:
     *   auto-approve-low-risk  -- Returns immediately with allowed=true.
     *   always-deny            -- Returns immediately with allowed=false.
     *   requires-approval      -- Blocks (polls) until approved/rejected/timeout.
     *
     * PT-APPROVAL-1: empty packBinding throws UnboundDataError before any
     * queue insertion.
     *
     * @param actionContext  Describes the action and its governance context.
     * @returns EnforcementResult promise that resolves when a decision is made.
     */
    enforce(actionContext: ActionContext): Promise<EnforcementResult>;
    /**
     * Submit an approval decision for a pending gate.
     *
     * PT-APPROVAL-3: If the approvalId has already been decided, this call
     * is a silent no-op (the store's replay protection handles it).
     *
     * PT-APPROVAL-4: If the class policy specifies `allowedApprovers` and
     * `approverId` is not in that list, the approval is rejected and an
     * APPROVAL_GATE_UNAUTHORIZED_APPROVER audit entry is written.
     *
     * @param approvalId  The ID returned by `enforce()`.
     * @param approverId  Identity of the human approver.
     * @param reason      Optional human-readable reason.
     */
    submitApproval(approvalId: string, approverId: string, reason?: string): void;
    /**
     * Submit a rejection decision for a pending gate.
     *
     * PT-APPROVAL-3: If the approvalId has already been decided, this call
     * is a silent no-op.
     *
     * @param approvalId  The ID returned by `enforce()`.
     * @param approverId  Identity of the rejecting human.
     * @param reason      Optional human-readable reason.
     */
    submitRejection(approvalId: string, approverId: string, reason?: string): void;
    /**
     * Return all currently pending approvals.
     * Optionally filter by action class or initiator.
     * Used by the dashboard / UI to display the approval queue.
     */
    getPendingApprovals(filter?: {
        actionClass?: ActionClass;
        initiator?: string;
    }): PendingApproval[];
    /**
     * Return a snapshot of all approvals (pending and decided).
     * Useful for audit queries.
     */
    getAllApprovals(): PendingApproval[];
    /**
     * Retrieve a single approval by ID.
     */
    getApproval(approvalId: string): PendingApproval | null;
    /**
     * Poll the store until the approval is no longer 'pending' or timeout elapses.
     *
     * Uses setInterval-based polling (no busy-spin per AIAG-013).
     * On timeout, calls `store.timeout()` to mark the record, then resolves.
     */
    private waitForDecision;
    /**
     * PT-APPROVAL-4: Returns true if the approverId is permitted to approve
     * for the given action class. Always returns true when no allowedApprovers
     * constraint is configured for that class.
     */
    private isAuthorizedApprover;
    /**
     * Append an audit entry to the JSONL file when auditDir is configured.
     * Errors are logged to stderr but never thrown -- the gate must not fail
     * because the audit writer has a transient I/O error.
     */
    private writeAudit;
}
/**
 * Generate a unique approval ID in the same format used by the enforcer.
 * Exposed for testing and integration code that needs to pre-generate IDs.
 */
export declare function generateApprovalId(): string;
//# sourceMappingURL=approval-gate-enforcer.d.ts.map