/**
 * Permission Chain Types
 *
 * This module defines the types for the Chain of Responsibility pattern
 * used to handle IAM permission requests. Each handler processes specific
 * resource types and can delegate to the next handler in the chain.
 *
 * @module declarative-api/permission-chain.types
 */
import type { IResourceEntity } from './resource.types';
import type { ResourceType } from './core.types';
/**
 * Permission level for access requests.
 *
 * Defines the level of access being requested:
 * - read: Read-only access (Get, Query, Scan, etc.)
 * - write: Write-only access (Put, Update, Delete, etc.)
 * - full: Full read/write access
 * - custom: Custom actions specified in the request
 *
 * Validates: Requirements 5.1
 */
export type PermissionLevel = 'read' | 'write' | 'full' | 'custom';
/**
 * All valid permission levels as a readonly array.
 */
export declare const PERMISSION_LEVELS: readonly PermissionLevel[];
/**
 * Type guard to check if a value is a valid PermissionLevel.
 *
 * @param value - The value to check
 * @returns True if the value is a valid PermissionLevel
 */
export declare function isValidPermissionLevel(value: unknown): value is PermissionLevel;
/**
 * Permission request for the chain of responsibility.
 *
 * Contains all information needed to process a permission request,
 * including the level of access and optional custom actions.
 *
 * @example
 * ```typescript
 * const request: PermissionRequest = {
 *   permissionLevel: 'read',
 *   dryRun: false,
 * };
 *
 * const customRequest: PermissionRequest = {
 *   permissionLevel: 'custom',
 *   customActions: ['dynamodb:GetItem', 'dynamodb:Query'],
 *   dryRun: true,
 * };
 * ```
 *
 * Validates: Requirements 5.1
 */
export interface PermissionRequest {
    /**
     * The level of permission being requested.
     */
    readonly permissionLevel: PermissionLevel;
    /**
     * Custom IAM actions when permissionLevel is 'custom'.
     * Ignored for other permission levels.
     */
    readonly customActions?: readonly string[];
    /**
     * Whether this is a dry-run request.
     * When true, permissions are not actually granted but the
     * audit log is still created for preview purposes.
     * @default false
     */
    readonly dryRun?: boolean;
}
/**
 * Audit log entry for permission operations.
 *
 * Records all permission grant operations for auditing and debugging.
 * Created for both actual grants and dry-run operations.
 *
 * @example
 * ```typescript
 * const entry: AuditLogEntry = {
 *   timestamp: new Date(),
 *   resourceId: 'users-table',
 *   resourceType: 'dynamodb:table',
 *   roleArn: 'arn:aws:iam::123456789012:role/LambdaRole',
 *   actions: ['dynamodb:GetItem', 'dynamodb:Query'],
 *   permissionLevel: 'read',
 *   dryRun: false,
 *   handlerId: 'table-permission-handler',
 * };
 * ```
 *
 * Validates: Requirements 5.5
 */
export interface AuditLogEntry {
    /**
     * Timestamp when the permission was processed.
     */
    readonly timestamp: Date;
    /**
     * ID of the resource being granted access to.
     */
    readonly resourceId: string;
    /**
     * Type of the resource being granted access to.
     */
    readonly resourceType: ResourceType;
    /**
     * ARN of the IAM role being granted permissions.
     */
    readonly roleArn: string;
    /**
     * IAM actions that were granted (or would be granted in dry-run).
     */
    readonly actions: readonly string[];
    /**
     * The permission level that was requested.
     */
    readonly permissionLevel: PermissionLevel;
    /**
     * Whether this was a dry-run operation.
     */
    readonly dryRun: boolean;
    /**
     * ID of the handler that processed this request.
     */
    readonly handlerId: string;
}
/**
 * Result of a permission grant operation.
 *
 * Contains information about whether the permission was granted,
 * what actions were granted, and the audit log entry.
 *
 * @example
 * ```typescript
 * const result: PermissionResult = {
 *   granted: true,
 *   handled: true,
 *   actions: ['dynamodb:GetItem', 'dynamodb:Query'],
 *   resource: tableEntity,
 *   auditLog: auditEntry,
 * };
 * ```
 *
 * Validates: Requirements 5.1
 */
export interface PermissionResult {
    /**
     * Whether the permission was successfully granted.
     * False if the request was not handled or failed.
     */
    readonly granted: boolean;
    /**
     * Whether the request was handled by a handler.
     * False if no handler in the chain could process the request.
     */
    readonly handled: boolean;
    /**
     * IAM actions that were granted (or would be granted in dry-run).
     */
    readonly actions: readonly string[];
    /**
     * The resource that was granted access to.
     */
    readonly resource: IResourceEntity;
    /**
     * Audit log entry for this operation.
     */
    readonly auditLog: AuditLogEntry;
    /**
     * Error message if the grant failed.
     */
    readonly error?: string;
}
/**
 * Permission handler interface for the Chain of Responsibility pattern.
 *
 * Each handler processes permission requests for specific resource types.
 * If a handler cannot process a request, it delegates to the next handler.
 *
 * Implements: Chain of Responsibility Pattern
 *
 * @example
 * ```typescript
 * class TablePermissionHandler implements IPermissionHandler {
 *   readonly priority = 10;
 *   readonly handlerId = 'table-permission-handler';
 *
 *   canHandle(resource: IResourceEntity): boolean {
 *     return resource.type === 'dynamodb:table';
 *   }
 *
 *   handle(resource, role, request): PermissionResult {
 *     if (!this.canHandle(resource)) {
 *       return this.next?.handle(resource, role, request) ?? unhandledResult;
 *     }
 *     // Grant permissions...
 *   }
 *
 *   setNext(handler: IPermissionHandler): IPermissionHandler {
 *     this.next = handler;
 *     return handler;
 *   }
 * }
 * ```
 *
 * Validates: Requirements 5.1, 5.2, 5.3, 5.4
 */
export interface IPermissionHandler {
    /**
     * Handler priority (lower = earlier in chain).
     * Handlers are sorted by priority when building the chain.
     */
    readonly priority: number;
    /**
     * Unique identifier for this handler.
     * Used in audit logs to track which handler processed a request.
     */
    readonly handlerId: string;
    /**
     * Check if this handler can process the given resource.
     *
     * @param resource - The resource to check
     * @returns True if this handler can process the resource
     */
    canHandle(resource: IResourceEntity): boolean;
    /**
     * Handle a permission request.
     *
     * If this handler cannot process the request, it should delegate
     * to the next handler in the chain.
     *
     * @param resource - The resource to grant access to
     * @param role - The IAM role to grant permissions to (CDK IRole)
     * @param request - The permission request
     * @returns The result of the permission operation
     */
    handle(resource: IResourceEntity, role: unknown, request: PermissionRequest): PermissionResult;
    /**
     * Set the next handler in the chain.
     *
     * @param handler - The next handler
     * @returns The next handler (for chaining)
     */
    setNext(handler: IPermissionHandler): IPermissionHandler;
    /**
     * Get the next handler in the chain.
     *
     * @returns The next handler, or undefined if this is the last handler
     */
    getNext(): IPermissionHandler | undefined;
}
/**
 * Permission chain interface for managing the chain of handlers.
 *
 * Provides methods to add handlers, process requests, and manage
 * the chain lifecycle.
 *
 * @example
 * ```typescript
 * const chain = new PermissionChain();
 * chain.addHandler(new TablePermissionHandler());
 * chain.addHandler(new QueuePermissionHandler());
 *
 * const result = chain.handle(resource, role, request);
 * const logs = chain.getAuditLogs();
 * ```
 *
 * Validates: Requirements 5.1, 5.2, 5.3, 5.4, 5.5, 5.6
 */
export interface IPermissionChain {
    /**
     * Add a handler to the chain.
     * Handlers are automatically sorted by priority.
     *
     * @param handler - The handler to add
     * @returns This chain for method chaining
     */
    addHandler(handler: IPermissionHandler): this;
    /**
     * Remove a handler from the chain by ID.
     *
     * @param handlerId - The ID of the handler to remove
     * @returns True if the handler was removed
     */
    removeHandler(handlerId: string): boolean;
    /**
     * Handle a permission request.
     *
     * @param resource - The resource to grant access to
     * @param role - The IAM role to grant permissions to
     * @param request - The permission request
     * @returns The result of the permission operation
     */
    handle(resource: IResourceEntity, role: unknown, request: PermissionRequest): PermissionResult;
    /**
     * Get all handlers in the chain.
     *
     * @returns Array of handlers in priority order
     */
    getHandlers(): readonly IPermissionHandler[];
    /**
     * Get all audit log entries.
     *
     * @returns Array of audit log entries
     */
    getAuditLogs(): readonly AuditLogEntry[];
    /**
     * Clear all audit log entries.
     */
    clearAuditLogs(): void;
    /**
     * Check if the chain has any handlers.
     *
     * @returns True if the chain has at least one handler
     */
    hasHandlers(): boolean;
}
/**
 * Factory for creating permission handlers.
 *
 * Provides a centralized way to create and configure handlers.
 */
export interface IPermissionHandlerFactory {
    /**
     * Create a handler for a specific resource type.
     *
     * @param resourceType - The resource type to create a handler for
     * @returns The created handler
     */
    createForResourceType(resourceType: ResourceType): IPermissionHandler;
    /**
     * Create a chain with all default handlers.
     *
     * @returns A permission chain with all default handlers
     */
    createDefaultChain(): IPermissionChain;
}
