/**
 * Authorization Utilities
 *
 * Provides role-based access control (RBAC) utilities for API endpoints.
 * Includes comprehensive audit logging for access denial events.
 *
 * @packageDocumentation
 */
import type { FastifyRequest, FastifyReply } from 'fastify';
import { AuthorizationResult as CanonicalAuthorizationResult, AuthorizationConstraints, GovernanceDenialReason, authorizationResultSchema, authorizationConstraintsSchema, governanceDenialReasonSchema } from '@vorionsys/contracts/canonical/governance';
export { CanonicalAuthorizationResult, AuthorizationConstraints, GovernanceDenialReason, authorizationResultSchema, authorizationConstraintsSchema, governanceDenialReasonSchema, };
/**
 * User payload extracted from JWT token
 */
export interface AuthUser {
    sub?: string;
    tenantId?: string;
    roles?: string[];
    groups?: string[];
    [key: string]: unknown;
}
/**
 * Authorization check result
 *
 * @deprecated Use `CanonicalAuthorizationResult` from `@vorionsys/contracts` for new code.
 *             This interface is maintained for backwards compatibility and is a subset
 *             of the canonical type. The canonical type includes additional fields for
 *             denial reasons, permissions, constraints, and remediations.
 */
export interface AuthorizationResult {
    allowed: boolean;
    reason?: string;
    matchedRoles?: string[];
}
/**
 * Policy endpoint role definitions
 */
export declare const POLICY_ROLES: {
    /** Roles that can read policies */
    readonly READ: readonly ["admin", "tenant:admin", "policy:admin", "policy_reader", "policy_writer"];
    /** Roles that can create and update policies */
    readonly WRITE: readonly ["admin", "tenant:admin", "policy:admin", "policy_writer"];
    /** Roles that can delete policies */
    readonly DELETE: readonly ["admin", "tenant:admin", "policy:admin"];
};
/**
 * Check if user has any of the required roles
 *
 * @param userRoles - Array of roles the user has
 * @param requiredRoles - Array of roles that would grant access
 * @returns Authorization result with matched roles if allowed
 */
export declare function hasAnyRole(userRoles: string[] | undefined, requiredRoles: readonly string[]): AuthorizationResult;
/**
 * Check if user has all of the required roles
 *
 * @param userRoles - Array of roles the user has
 * @param requiredRoles - Array of roles that are all required
 * @returns Authorization result
 */
export declare function hasAllRoles(userRoles: string[] | undefined, requiredRoles: readonly string[]): AuthorizationResult;
/**
 * Extract user information from Fastify request
 *
 * @param request - Fastify request object (with JWT user property)
 * @returns AuthUser extracted from JWT payload
 */
export declare function getAuthUser(request: FastifyRequest): AuthUser;
/**
 * Authorization error response structure
 */
export interface AuthorizationError {
    code: 'FORBIDDEN';
    message: string;
    requiredRoles?: readonly string[];
}
/**
 * Create a standard 403 Forbidden response
 *
 * @param reason - Reason for denial
 * @param requiredRoles - Optional list of required roles to include in response
 * @returns Formatted error response
 */
export declare function createForbiddenResponse(reason: string, requiredRoles?: readonly string[]): {
    error: AuthorizationError;
};
/**
 * Higher-order function to create an authorization guard for route handlers
 *
 * @param requiredRoles - Roles that grant access to this endpoint
 * @param options - Additional options for the guard
 * @returns A preHandler hook function for Fastify
 *
 * @example
 * ```typescript
 * api.get('/policies', {
 *   preHandler: requireRoles(POLICY_ROLES.READ),
 * }, async (request, reply) => {
 *   // Handler code
 * });
 * ```
 */
export declare function requireRoles(requiredRoles: readonly string[], options?: {
    /** Log authorization failures */
    logFailures?: boolean;
    /** Custom message for authorization failures */
    customMessage?: string;
    /** Record access denial in audit log (default: true) */
    auditDenials?: boolean;
}): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
/**
 * Inline authorization check for use within route handlers
 * Returns true if authorized, sends 403 response and returns false if not
 *
 * @param request - Fastify request object
 * @param reply - Fastify reply object
 * @param requiredRoles - Roles that grant access
 * @param options - Additional options
 * @returns true if authorized, false if not (response already sent)
 *
 * @example
 * ```typescript
 * api.delete('/policies/:id', async (request, reply) => {
 *   if (!await checkAuthorization(request, reply, POLICY_ROLES.DELETE)) {
 *     return; // Response already sent
 *   }
 *   // Handler code
 * });
 * ```
 */
export declare function checkAuthorization(request: FastifyRequest, reply: FastifyReply, requiredRoles: readonly string[], options?: {
    logFailures?: boolean;
    customMessage?: string;
    /** Record access denial in audit log (default: true) */
    auditDenials?: boolean;
}): Promise<boolean>;
//# sourceMappingURL=authorization.d.ts.map