/**
 * RagSourceAllowlist -- Per-agent, per-org RAG retrieval source allowlisting.
 *
 * When an agent performs retrieval (vector search, document lookup, web fetch
 * for grounding, MCP resource access), the source must be on the agent's
 * configured allowlist. Off-allowlist retrieval is rejected BEFORE the actual
 * retrieval call is made (pre-retrieval gate, not post-fetch).
 *
 * Entry kinds:
 *   - vector-store:         literal ID match (e.g. "vs_org_a_pubmed_2026")
 *   - document-collection:  literal ID match (e.g. "dc_legal_casebook_2025")
 *   - url-prefix:           URL prefix match with scheme-aware canonicalisation
 *   - mcp-resource:         MCP URI prefix match with path canonicalisation
 *
 * Strict-mode packs (fail-closed when no allowlist is configured):
 *   - hipaa     HIPAA §164.312(a)(1): access control to PHI sources
 *   - gdpr      GDPR Art. 5(1)(b): purpose limitation, storage limitation
 *   - pci-dss   PCI DSS Req 7: restrict access to system components
 *   - hmda      HMDA Reg C 12 CFR §1003: GMI data source integrity
 *   - dora      DORA Art. 9: ICT risk management, third-party data access
 *
 * Non-strict packs default to lenient mode: first retrieval per cycle emits
 * one audit warning and allows; subsequent retrievals in the same cycle do not
 * re-emit (spam prevention).
 *
 * Audit events:
 *   - RAG_SOURCE_REJECTED  severity WARNING, sourceHash (SHA-256, not raw URL)
 *   - RAG_SOURCE_ALLOWED   severity INFO
 *   - RAG_UNALLOWLISTED_WARN severity WARNING (lenient-mode first-call)
 *
 * Pack-binding is mandatory on every entry (UnboundDataError if missing).
 *
 * Integration:
 *   - LlamaIndex: call guardPreRetrieval() inside the documentRetrieval() hook
 *     before LlamaIndex executes the vector-store or document-store fetch.
 *   - Haystack:   call guardPreRetrieval() in the nodeStart() hook when
 *     nodeType is 'Retriever' or 'DocumentStore'.
 *   - Other adapters: any adapter exposing a retrieval surface should call
 *     guardPreRetrieval() before dispatching to the underlying retrieval API.
 *   - The PreRetrievalHook interface in src/governance/index.ts declares the
 *     integration contract for adapters that want to self-register.
 *
 * Pen-test gates:
 *   PT-RAG-ALLOWLIST-1: URL-encoding bypass -- encoded host confusables are
 *     normalised and rejected.
 *   PT-RAG-ALLOWLIST-2: vector-store ID confusable -- "vs_x_evil" is not
 *     accepted when allowlist has "vs_x"; exact match required.
 *   PT-RAG-ALLOWLIST-3: MCP URI traversal -- "../" segments are canonicalised
 *     away and traversal is blocked.
 *
 * BUILD_PLAN reference: line 246 "Retrieval source allowlisting per agent".
 *
 * @connexum/ai-governance
 */
/**
 * Packs that force fail-closed behaviour when no allowlist is configured.
 * If an agent is bound to any of these packs and has no allowlist entries,
 * every retrieval throws RagSourceAllowlistRequiredError.
 *
 * hipaa  -- HIPAA §164.312(a)(1): PHI access controls; unconfigured source
 *           access violates minimum-necessary principle.
 * gdpr   -- GDPR Art. 5(1)(b) purpose limitation; Art. 25 data minimisation.
 * pci-dss -- PCI DSS Req 7: restrict access to system components to business
 *           need-to-know; cardholder data sources must be explicit.
 * hmda   -- HMDA Reg C §1003: GMI data (race, sex, ethnicity) must only flow
 *           from verified HMDA collection forms, not arbitrary sources.
 * dora   -- DORA Art. 9: ICT third-party risk; unknown data sources are an
 *           unacknowledged ICT risk requiring explicit registration.
 */
export declare const STRICT_MODE_PACKS: ReadonlySet<string>;
/**
 * Thrown when a retrieval source is not on the agent's allowlist.
 */
export declare class RagSourceNotAllowlistedError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly sourceHash: string;
    readonly kind: RagSourceKind;
    constructor(opts: {
        orgId: string;
        agentId: string;
        sourceHash: string;
        kind: RagSourceKind;
    });
}
/**
 * Thrown when a strict-mode pack is bound to an agent that has no allowlist
 * configured. Fail-closed: every retrieval is rejected.
 */
export declare class RagSourceAllowlistRequiredError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly strictPacks: string[];
    constructor(opts: {
        orgId: string;
        agentId: string;
        strictPacks: string[];
    });
}
/**
 * Thrown when configure() receives an entry with an empty packBinding.
 * Per feedback_pack_binding_primacy.md: every entry MUST carry packBinding.
 */
export declare class UnboundDataError extends Error {
    readonly entryPattern: string;
    constructor(pattern: string);
}
/** The four supported retrieval source kinds. */
export type RagSourceKind = 'vector-store' | 'document-collection' | 'url-prefix' | 'mcp-resource';
/**
 * A single allowlist entry.
 *
 * - vector-store:        pattern is a literal vector-store ID. Exact match.
 * - document-collection: pattern is a literal document-collection ID. Exact match.
 * - url-prefix:          pattern is a URL prefix (scheme + host + optional path).
 *                        Case-insensitive on scheme+host, case-sensitive on path.
 *                        URLs with embedded credentials are always rejected.
 * - mcp-resource:        pattern is a canonical MCP URI prefix (lowercase scheme,
 *                        lowercase host, no trailing slash before path).
 */
export interface RagSourceAllowlistEntry {
    pattern: string;
    kind: RagSourceKind;
    /**
     * Pack binding: MUST be non-empty. Throws UnboundDataError if empty.
     * Used for audit traceability and retention policy derivation.
     */
    packBinding: string[];
}
/** Request shape passed to guardPreRetrieval(). */
export interface RagRetrievalRequest {
    /** The raw source string (URL, ID, or URI). Never logged; only its hash is. */
    source: string;
    kind: RagSourceKind;
}
export interface RagSourceRejectedAuditEvent {
    type: 'RAG_SOURCE_REJECTED';
    severity: 'WARNING';
    orgId: string;
    agentId: string;
    /** SHA-256 of the source string. Raw URL is never logged. */
    sourceHash: string;
    kind: RagSourceKind;
    reason: 'not-allowlisted' | 'strict-mode-no-allowlist';
    /** SHA-256 of the previous audit event (chain linkage). */
    prevSha: string;
    timestamp: string;
}
export interface RagSourceAllowedAuditEvent {
    type: 'RAG_SOURCE_ALLOWED';
    severity: 'INFO';
    orgId: string;
    agentId: string;
    sourceHash: string;
    kind: RagSourceKind;
    matchedPattern: string;
    timestamp: string;
}
export interface RagUnallowlistedWarnAuditEvent {
    type: 'RAG_UNALLOWLISTED_WARN';
    severity: 'WARNING';
    orgId: string;
    agentId: string;
    sourceHash: string;
    kind: RagSourceKind;
    timestamp: string;
}
export type RagAuditEvent = RagSourceRejectedAuditEvent | RagSourceAllowedAuditEvent | RagUnallowlistedWarnAuditEvent;
/**
 * Per-agent, per-org RAG retrieval source allowlist.
 *
 * Usage:
 *   const allowlist = new RagSourceAllowlist(auditSink);
 *
 *   // Operator configuration at agent-startup time:
 *   allowlist.configure('org-acme', 'agent-rag-01', [
 *     { pattern: 'vs_acme_pubmed_2026', kind: 'vector-store', packBinding: ['hipaa'] },
 *     { pattern: 'https://drugs.fda.gov/', kind: 'url-prefix', packBinding: ['hipaa'] },
 *   ]);
 *
 *   // Pre-retrieval gate (call BEFORE dispatching to the retrieval API):
 *   allowlist.guardPreRetrieval('org-acme', 'agent-rag-01', {
 *     source: 'vs_acme_pubmed_2026',
 *     kind:   'vector-store',
 *   }); // returns { allowed: true, matchedEntry }
 *
 *   // Throws RagSourceNotAllowlistedError if source is not on the list.
 *   // Throws RagSourceAllowlistRequiredError if strict pack is bound + no list.
 */
export declare class RagSourceAllowlist {
    /** Key: orgId::agentId -> entries */
    private readonly lists;
    /** Key: orgId::agentId -> pack bindings active for strict-mode checks */
    private readonly agentPackBindings;
    /**
     * Per-cycle lenient-warn tracking.
     * Key: orgId::agentId -> Set of cycle IDs that have already emitted the
     * single per-cycle warning. Prevents spam in lenient mode.
     */
    private readonly lenientWarnEmitted;
    /** SHA-256 of the last emitted audit event (chain linkage). */
    private prevSha;
    private readonly auditSink;
    constructor(auditSink?: (event: RagAuditEvent) => void);
    /**
     * Register the allowlist for an agent.
     *
     * Throws UnboundDataError if any entry has an empty packBinding (mandatory
     * per feedback_pack_binding_primacy.md).
     *
     * @param orgId   Operator/tenant identifier.
     * @param agentId Agent identifier.
     * @param entries Allowlist entries for this agent.
     * @param activePackIds Optional list of active compliance pack IDs for strict-mode determination.
     */
    configure(orgId: string, agentId: string, entries: RagSourceAllowlistEntry[], activePackIds?: string[]): void;
    /**
     * Pre-retrieval gate. Must be called BEFORE dispatching to the retrieval API.
     *
     * Returns { allowed: true, matchedEntry } on success.
     * Throws RagSourceNotAllowlistedError when the source is not allowlisted.
     * Throws RagSourceAllowlistRequiredError when a strict pack is bound and
     * no allowlist is configured.
     *
     * @param orgId   Operator/tenant identifier.
     * @param agentId Agent identifier.
     * @param request Retrieval request with source and kind.
     * @param cycleId Optional cycle identifier used for lenient-mode spam prevention.
     */
    guardPreRetrieval(orgId: string, agentId: string, request: RagRetrievalRequest, cycleId?: string): {
        allowed: true;
        matchedEntry: RagSourceAllowlistEntry;
    };
    /**
     * Read-only view of allowlist entries for an agent.
     * Returns an empty array if no allowlist is configured.
     */
    getEntries(orgId: string, agentId: string): ReadonlyArray<RagSourceAllowlistEntry>;
    /**
     * Remove all allowlist entries for an agent.
     * Called at agent shutdown for clean teardown.
     */
    clearAgent(orgId: string, agentId: string): void;
    /**
     * Find the first matching allowlist entry for the request.
     * Returns null if no entry matches.
     */
    private findMatch;
    /**
     * URL prefix matching with canonicalisation.
     *
     * - Reject URLs with embedded credentials immediately (no allowlist match).
     * - Canonicalise both the request URL and the allowlist pattern before comparing.
     * - Case-insensitive on scheme+host, case-sensitive on path.
     */
    private matchUrlPrefix;
    /**
     * MCP URI prefix matching with canonicalisation and traversal prevention.
     * (PT-RAG-ALLOWLIST-3)
     */
    private matchMcpPrefix;
    /**
     * Compute SHA-256 of a string. Used to hash source URLs for audit logs
     * so that sensitive URL parameters are never written to the audit trail.
     */
    private sha256;
    /**
     * Emit a RAG_SOURCE_REJECTED audit event with prev-SHA chain linkage.
     * The source is stored as its SHA-256 hash, never as the raw URL.
     */
    private emitRejection;
}
//# sourceMappingURL=rag-source-allowlist.d.ts.map