/**
 * API Key Scope Authorization Utilities
 * Provides utilities for checking API key scopes in resolvers
 * @module @memberjunction/server
 */
import { AuthorizationResult } from '@memberjunction/api-keys';
import { UserInfo } from '@memberjunction/core';
/**
 * Application names used by the API Key authorization system
 */
export type ApplicationName = 'MJAPI' | 'MCPServer' | 'A2AServer' | string;
/**
 * Options for scope authorization
 */
export interface ScopeAuthOptions {
    /** The application making the request (default: 'MJAPI') */
    applicationName?: ApplicationName;
    /** Resource being accessed (e.g., entity name, action name) */
    resource?: string;
    /** Whether to throw an error on denied access (default: true) */
    throwOnDenied?: boolean;
}
/**
 * Result of scope authorization check
 */
export interface ScopeAuthResult {
    /** Whether access is allowed */
    Allowed: boolean;
    /** Human-readable reason for the decision */
    Reason?: string;
    /** Whether scope checking was performed (false if no API key or enforcement disabled) */
    Checked: boolean;
    /** All rules evaluated during the check */
    EvaluatedRules?: AuthorizationResult['EvaluatedRules'];
}
/**
 * Check if an API key has the required scope for an operation.
 *
 * This function implements the three-tier permission model:
 * 1. User Permissions - What the user can do (already checked by authentication)
 * 2. Application Ceiling - Maximum scope the application allows
 * 3. API Key Scopes - Specific scopes granted to this key
 *
 * @param apiKeyId - The API key ID from context.userPayload.apiKeyId
 * @param scopePath - The scope path required (e.g., 'view:run', 'agent:execute')
 * @param contextUser - The authenticated user from context.userPayload.userRecord
 * @param options - Additional options for scope checking
 * @returns ScopeAuthResult with authorization details
 * @throws AuthorizationError if access is denied and throwOnDenied is true
 *
 * @example
 * ```typescript
 * // In a resolver
 * async runView(@Ctx() ctx: AppContext): Promise<ViewResult> {
 *   await CheckAPIKeyScope(
 *     ctx.userPayload.apiKeyId,
 *     'view:run',
 *     ctx.userPayload.userRecord,
 *     { resource: 'User' }
 *   );
 *   // ... proceed with operation
 * }
 * ```
 */
export declare function CheckAPIKeyScope(apiKeyId: string | undefined, scopePath: string, contextUser: UserInfo, options?: ScopeAuthOptions): Promise<ScopeAuthResult>;
/**
 * Check if an API key has the required scope and log usage.
 *
 * Same as CheckAPIKeyScope but also logs the authorization attempt.
 * Use this for operations where you want detailed audit trails.
 *
 * @param apiKeyId - The API key ID from context.userPayload.apiKeyId
 * @param scopePath - The scope path required
 * @param contextUser - The authenticated user
 * @param usageDetails - Details about the request for logging
 * @param options - Additional options for scope checking
 * @returns ScopeAuthResult with authorization details and optional log ID
 */
export declare function CheckAPIKeyScopeAndLog(apiKeyId: string | undefined, scopePath: string, contextUser: UserInfo, usageDetails: {
    endpoint: string;
    method: string;
    operationName?: string;
    ipAddress?: string;
    userAgent?: string;
    statusCode?: number;
    responseTimeMs?: number;
}, options?: ScopeAuthOptions): Promise<ScopeAuthResult & {
    LogId?: string;
}>;
/**
 * Decorator-style function for common scope checks.
 * Returns a function that can be used in resolvers.
 *
 * @param scopePath - The scope path required
 * @param options - Additional options
 * @returns A function that performs the scope check
 *
 * @example
 * ```typescript
 * const requireViewRun = RequireScope('view:run');
 *
 * // In resolver
 * async runView(@Ctx() ctx: AppContext): Promise<ViewResult> {
 *   await requireViewRun(ctx);
 *   // ... proceed
 * }
 * ```
 */
export declare function RequireScope(scopePath: string, options?: Omit<ScopeAuthOptions, 'resource'>): (ctx: {
    userPayload: {
        apiKeyId?: string;
        userRecord: UserInfo;
    };
}, resource?: string) => Promise<void>;
export declare const RequireViewRun: (ctx: {
    userPayload: {
        apiKeyId?: string;
        userRecord: UserInfo;
    };
}, resource?: string) => Promise<void>;
export declare const RequireQueryRun: (ctx: {
    userPayload: {
        apiKeyId?: string;
        userRecord: UserInfo;
    };
}, resource?: string) => Promise<void>;
export declare const RequireAgentExecute: (ctx: {
    userPayload: {
        apiKeyId?: string;
        userRecord: UserInfo;
    };
}, resource?: string) => Promise<void>;
//# sourceMappingURL=APIKeyScopeAuth.d.ts.map