/**
 * Element Policies
 *
 * Handles element-based access control for the Gatekeeper.
 * Allows ANY DollhouseMCP element to define policies in its metadata
 * that override or restrict the default operation policies.
 *
 * Policy Resolution Order:
 * 1. Active element deny list (highest priority - blocks operation)
 * 2. Active element confirm list (requires confirmation)
 * 3. Active element allow list (auto-approves)
 * 4. Operation default permission (fallback)
 */
import { PermissionLevel, type ElementGatekeeperPolicy, type GatekeeperDecision } from '../GatekeeperTypes.js';
/**
 * Metadata structure for elements with Gatekeeper policies.
 * The 'gatekeeper' field is optional and contains policy definitions.
 */
export interface ElementMetadataWithPolicy {
    name: string;
    description?: string;
    gatekeeper?: ElementGatekeeperPolicy;
    [key: string]: unknown;
}
/**
 * Active element for policy evaluation.
 * Represents an element currently active in the session.
 */
export interface ActiveElement {
    type: string;
    name: string;
    metadata: ElementMetadataWithPolicy;
}
export interface GatekeeperPolicyDiagnostics {
    valid: false;
    enforceable: false;
    message: string;
}
/**
 * Result of element policy resolution.
 * Contains the effective permission level and policy source.
 */
export interface ElementPolicyResult {
    /** Effective permission level after element policy application */
    permissionLevel: PermissionLevel;
    /** Which element's policy determined this result */
    sourceElement?: string;
    /** The specific policy field that matched (allow/confirm/deny) */
    matchedPolicy?: 'allow' | 'confirm' | 'deny' | 'scope_restriction';
    /** Whether the operation was blocked by scope restrictions */
    scopeBlocked?: boolean;
    /**
     * Elements that wanted to auto-approve this operation but were overridden
     * by a higher-priority confirm or deny policy from another element.
     * Issue #674: allow cannot override confirm.
     */
    conflictingElements?: Array<{
        name: string;
        wantedLevel: PermissionLevel;
    }>;
}
/**
 * Resolve the effective permission level for an operation
 * considering all active elements and their policies.
 *
 * @param operation - The operation to check
 * @param activeElements - Currently active elements with their metadata
 * @param targetElementType - Optional element type being operated on
 * @returns The resolved policy result
 */
export declare function resolveElementPolicy(operation: string, activeElements: ActiveElement[], targetElementType?: string): ElementPolicyResult;
/**
 * Create a Gatekeeper decision from element policy resolution.
 *
 * @param operation - The operation that was checked
 * @param result - The element policy resolution result
 * @param targetElementType - Optional element type being operated on
 * @returns A GatekeeperDecision object
 */
export declare function createDecisionFromPolicy(operation: string, result: ElementPolicyResult, targetElementType?: string): GatekeeperDecision;
/**
 * Parse and validate a Gatekeeper policy from element metadata.
 *
 * @param metadata - The element metadata to parse
 * @returns The parsed policy, or undefined if no policy is defined
 * @throws Error if the policy is malformed
 */
export declare function parseElementPolicy(metadata: unknown): ElementGatekeeperPolicy | undefined;
/**
 * Validate authored gatekeeper input before save.
 *
 * Authoring-time validation is stricter than load-time sanitization: it should
 * reject misplaced policy blocks instead of silently saving an element that
 * later appears active but has non-enforceable external restrictions.
 */
export declare function getGatekeeperAuthoringErrors(record: Record<string, unknown> | undefined): string[];
/**
 * Analyze externalRestrictions patterns for common mistakes and suspicious syntax.
 *
 * Returns non-fatal warnings to help LLMs and users write effective patterns.
 * Does NOT throw — validation errors are handled by {@link validatePatternStrings}.
 *
 * Checks performed (Issue #1664):
 * - Missing tool prefix (pattern doesn't start with ToolName:)
 * - Overly broad patterns (bare `*` or `ToolName:*`)
 * - Regex syntax that won't work in glob matching
 * - Leading/trailing whitespace
 *
 * @param patterns - Array of pattern strings to analyze
 * @param fieldName - Field name for warning messages
 * @returns Array of warning messages (empty if no issues found)
 */
export declare function analyzePatternSyntax(patterns: string[], fieldName: string): string[];
/**
 * Check if an operation is a gatekeeper infrastructure operation that should
 * skip element policy evaluation in the primary enforcement path.
 * Exported for use by MCPAQLHandler. Issue #758.
 */
export declare function isGatekeeperInfraOperation(operation: string): boolean;
/**
 * Check if any active elements deny confirm_operation (nuclear sandbox).
 * Returns the denying element name if found, undefined otherwise.
 */
export declare function findConfirmDenyingElement(activeElements: Array<{
    name: string;
    type: string;
    metadata: Record<string, unknown>;
}>): {
    name: string;
    type: string;
} | undefined;
/**
 * Check if any active elements have confirm_operation in their confirm list (advisory).
 * Returns the element names that request additional scrutiny.
 */
export declare function findConfirmAdvisoryElements(activeElements: Array<{
    name: string;
    type: string;
    metadata: Record<string, unknown>;
}>): Array<{
    name: string;
    type: string;
}>;
export declare function sanitizeGatekeeperPolicy(rawPolicy: unknown, elementName: string, elementType: string, diagnosticsTarget?: Record<string, unknown>): ElementGatekeeperPolicy | undefined;
export declare function attachGatekeeperDiagnostics(target: unknown, message: string): void;
export declare function clearGatekeeperDiagnostics(target: unknown): void;
export declare function getGatekeeperDiagnostics(target: unknown): GatekeeperPolicyDiagnostics | undefined;
//# sourceMappingURL=ElementPolicies.d.ts.map