/**
 * Xlock auth challenge module for Agent SDK.
 *
 * Provides requestAuth(), respondToChallenge(), and onChallenge()
 * functions that work with an Agent instance and the XBind gateway.
 *
 * These functions are also re-exported as thin methods on the Agent class.
 */
import type { Result, AuthRequest, AuthResult, IncomingAuthChallenge, AuthChallengeErrorCode } from '@private.me/shared';
import type { Agent } from './agent.js';
/** Options for the gateway connection used by auth functions. */
export interface AuthGatewayOptions {
    /** Gateway base URL (e.g. 'https://api.xail.io'). */
    readonly gatewayUrl: string;
    /** Bearer token for status polling (HMAC-SHA256 of sender DID). */
    readonly accessToken: string;
}
/**
 * Create an auth challenge and poll until the user responds.
 *
 * Sends a challenge via the XBind gateway, then polls the status
 * endpoint until the challenge is approved, denied, or expires.
 *
 * @param agent - The Agent requesting authorization.
 * @param request - Auth request details (recipient DID, action, metadata).
 * @param gateway - Gateway connection options.
 * @returns Auth result (approved/denied) or error.
 */
export declare function requestAuth(agent: Agent, request: AuthRequest, gateway: AuthGatewayOptions): Promise<Result<AuthResult, AuthChallengeErrorCode>>;
/**
 * Respond to an incoming auth challenge (approve or deny).
 *
 * Sends a signed response envelope to the gateway.
 *
 * @param agent - The Agent responding to the challenge.
 * @param challengeId - The challenge ID to respond to.
 * @param approved - Whether the user approved the challenge.
 * @param gateway - Gateway connection options.
 * @returns Success or error.
 */
export declare function respondToChallenge(agent: Agent, challengeId: string, approved: boolean, gateway: AuthGatewayOptions): Promise<Result<void, AuthChallengeErrorCode>>;
/**
 * Register a callback for incoming auth challenges via WebSocket.
 *
 * The callback fires when an `auth:challenge` message arrives
 * over the gateway WebSocket connection.
 *
 * @param ws - The WebSocket connection to the gateway.
 * @param callback - Handler for incoming challenges.
 * @returns Cleanup function to unregister the listener.
 */
export declare function onChallenge(ws: {
    addEventListener: (type: string, handler: (event: {
        data: string;
    }) => void) => void;
    removeEventListener: (type: string, handler: (event: {
        data: string;
    }) => void) => void;
}, callback: (challenge: IncomingAuthChallenge) => void): () => void;
/**
 * Generate a registration QR code URI for TOTP migration.
 *
 * Creates a `xlock://register` URI that replaces `otpauth://` for
 * asymmetric DID-based registration.
 *
 * @param options - Registration options.
 * @returns The registration URI string.
 */
export declare function generateRegistrationQR(options: {
    readonly appName: string;
    readonly appDid: string;
    readonly registryUrl: string;
    readonly callbackUrl: string;
    readonly appIcon?: string;
}): string;
