/**
 * Runtime policy context for opt-in policy enforcement.
 *
 * Provides a context object that can be used to check if a user/tenant
 * has specific roles, permissions, and attributes at runtime.
 *
 * @module policy/context
 *
 * @example
 * ```typescript
 * import { createPolicyContext } from '@contractspec/lib.contracts-spec';
 *
 * // Create context from user's roles and permissions
 * const ctx = createPolicyContext({
 *   id: 'user-123',
 *   tenantId: 'tenant-456',
 *   roles: ['admin', 'editor'],
 *   permissions: ['read:articles', 'write:articles'],
 *   attributes: { department: 'engineering' },
 * });
 *
 * // Check roles and permissions
 * if (ctx.hasRole('admin')) {
 *   // User has admin role
 * }
 *
 * // Audit access attempts
 * ctx.auditAccess('article.update', 'allowed');
 * ```
 */
/**
 * Error thrown when a policy violation occurs.
 */
export declare class PolicyViolationError extends Error {
    readonly violationType: PolicyViolationType;
    readonly details: PolicyViolationDetails;
    constructor(type: PolicyViolationType, details: PolicyViolationDetails);
}
export type PolicyViolationType = 'missing_role' | 'missing_permission' | 'missing_attribute' | 'rate_limit_exceeded' | 'consent_required' | 'access_denied';
export interface PolicyViolationDetails {
    operation?: string;
    requiredRole?: string;
    requiredPermission?: string;
    requiredAttribute?: {
        key: string;
        expected: unknown;
    };
    rateLimitKey?: string;
    consentIds?: string[];
    reason?: string;
}
export interface RateLimitResult {
    allowed: boolean;
    remaining: number;
    resetAt?: Date;
    retryAfterMs?: number;
}
export interface RateLimitState {
    key: string;
    count: number;
    windowStart: number;
    windowMs: number;
    limit: number;
}
export interface AuditEntry {
    timestamp: Date;
    operation: string;
    result: 'allowed' | 'denied';
    reason?: string;
    userId?: string;
    tenantId?: string;
    attributes?: Record<string, unknown>;
}
export type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
/**
 * User information for policy evaluation.
 */
export interface PolicyUser {
    /** Unique user identifier. */
    id: string;
    /** Optional tenant/organization ID for multi-tenant contexts. */
    tenantId?: string;
    /** Roles assigned to the user. */
    roles: string[];
    /** Permissions granted to the user. */
    permissions: string[];
    /** Additional attributes for ABAC evaluation. */
    attributes: Record<string, unknown>;
}
/**
 * Runtime context for checking policy access.
 *
 * Created from user information (roles, permissions, attributes).
 * Provides methods to check and require policy compliance at runtime.
 */
export interface PolicyContext {
    /** The user for this context. */
    readonly user: PolicyUser;
    /** Set of user roles. */
    readonly roles: ReadonlySet<string>;
    /** Set of user permissions. */
    readonly permissions: ReadonlySet<string>;
    /**
     * Check if user has a specific role.
     * @param role - Role to check
     * @returns True if user has the role
     */
    hasRole(role: string): boolean;
    /**
     * Check if user has any of the specified roles.
     * @param roles - Roles to check
     * @returns True if user has at least one role
     */
    hasAnyRole(roles: string[]): boolean;
    /**
     * Check if user has all of the specified roles.
     * @param roles - Roles to check
     * @returns True if user has all roles
     */
    hasAllRoles(roles: string[]): boolean;
    /**
     * Require a role, throwing if not present.
     * @param role - Role to require
     * @throws {PolicyViolationError} If role is missing
     */
    requireRole(role: string): void;
    /**
     * Check if user has a specific permission.
     * @param permission - Permission to check
     * @returns True if user has the permission
     */
    hasPermission(permission: string): boolean;
    /**
     * Check if user has any of the specified permissions.
     * @param permissions - Permissions to check
     * @returns True if user has at least one permission
     */
    hasAnyPermission(permissions: string[]): boolean;
    /**
     * Check if user has all of the specified permissions.
     * @param permissions - Permissions to check
     * @returns True if user has all permissions
     */
    hasAllPermissions(permissions: string[]): boolean;
    /**
     * Require a permission, throwing if not present.
     * @param permission - Permission to require
     * @throws {PolicyViolationError} If permission is missing
     */
    requirePermission(permission: string): void;
    /**
     * Get a user attribute value.
     * @param key - Attribute key
     * @returns Attribute value or undefined
     */
    getAttribute<T = unknown>(key: string): T | undefined;
    /**
     * Check if an attribute matches an expected value.
     * @param key - Attribute key
     * @param expected - Expected value
     * @returns True if attribute equals expected value
     */
    checkAttribute(key: string, expected: unknown): boolean;
    /**
     * Check if an attribute is one of the allowed values.
     * @param key - Attribute key
     * @param allowedValues - Array of allowed values
     * @returns True if attribute is in allowed values
     */
    checkAttributeOneOf(key: string, allowedValues: unknown[]): boolean;
    /**
     * Check rate limit for a key.
     * @param key - Rate limit key (e.g., operation name)
     * @returns Rate limit result
     */
    checkRateLimit(key: string): RateLimitResult;
    /**
     * Consume rate limit for a key (increment counter).
     * @param key - Rate limit key
     * @param cost - Cost of the operation (default: 1)
     * @returns Rate limit result after consumption
     */
    consumeRateLimit(key: string, cost?: number): RateLimitResult;
    /**
     * Record an access attempt for audit purposes.
     * @param operation - Operation being accessed
     * @param result - Whether access was allowed or denied
     * @param reason - Optional reason for the decision
     */
    auditAccess(operation: string, result: 'allowed' | 'denied', reason?: string): void;
}
export interface PolicyContextOptions {
    /** Rate limit configurations by key. */
    rateLimits?: Record<string, {
        limit: number;
        windowMs: number;
    }>;
    /** Handler for audit entries. */
    auditHandler?: AuditHandler;
}
/**
 * Creates a policy context from user information.
 *
 * @param user - User information for policy evaluation
 * @param options - Additional context options
 * @returns PolicyContext for checking/requiring policy compliance
 *
 * @example
 * ```typescript
 * const ctx = createPolicyContext({
 *   id: 'user-123',
 *   roles: ['editor'],
 *   permissions: ['read:articles'],
 *   attributes: { department: 'marketing' },
 * });
 *
 * ctx.requireRole('editor');
 * ctx.requirePermission('read:articles');
 * ```
 */
export declare function createPolicyContext(user: PolicyUser, options?: PolicyContextOptions): PolicyContext;
/**
 * Creates an empty policy context (no roles/permissions).
 * Useful for anonymous users or testing.
 */
export declare function createAnonymousPolicyContext(options?: PolicyContextOptions): PolicyContext;
/**
 * Creates a bypass policy context with all roles/permissions.
 * Useful for admin users or internal services.
 *
 * @param allRoles - All roles to grant
 * @param allPermissions - All permissions to grant
 */
export declare function createBypassPolicyContext(allRoles: string[], allPermissions: string[], options?: PolicyContextOptions): PolicyContext;
