/**
 * Signed URL Generator Utility
 *
 * Provides secure URL generation with:
 * - HMAC-based signatures for URL integrity
 * - Expiration time enforcement
 * - Optional IP address restrictions
 * - Optional permission restrictions (read/write/delete)
 * - URL verification
 *
 * Use Cases:
 * - Temporary download links
 * - Pre-signed upload URLs
 * - Secure file sharing
 * - Time-limited access control
 */
import type { StorageSignedUrlOptions, StorageVerificationResult, StorageHashAlgorithm, StorageSignedUrlPermission } from '@plyaz/types/storage';
/**
 * Signed URL Generator Class
 * Provides static methods for generating and verifying signed URLs
 */
export declare class SignedUrlGenerator {
    /**
     * Generate a signed URL with expiration and optional restrictions
     *
     * The signature is generated using HMAC-SHA256 with the following payload:
     * - File path
     * - Expiration timestamp
     * - IP address (if restricted)
     * - Permissions
     * - Metadata (if provided)
     *
     * @param baseUrl - Base URL (e.g., "https://storage.example.com")
     * @param filePath - File path or key (e.g., "/files/document.pdf")
     * @param secret - Secret key for HMAC signing
     * @param options - Signing options (expiration, IP, permissions)
     * @returns Signed URL with query parameters
     *
     * @example
     * ```typescript
     * const url = SignedUrlGenerator.generateSignedUrl(
     *   'https://cdn.example.com',
     *   '/files/document.pdf',
     *   'my-secret-key',
     *   {
     *     expiresIn: 3600, // 1 hour
     *     ipAddress: '192.168.1.1',
     *     permissions: ['read'],
     *   }
     * );
     * // https://cdn.example.com/files/document.pdf?expires=1706745600&signature=abc123...&ip=192.168.1.1
     * ```
     */
    static generateSignedUrl(baseUrl: string, filePath: string, secret: string, options: StorageSignedUrlOptions): string;
    /**
     * Build signature payload from components
     */
    private static buildSignaturePayload;
    /**
     * Build signed URL with all parameters
     */
    private static buildSignedUrl;
    /**
     * Verify a signed URL
     *
     * Checks:
     * 1. URL hasn't expired
     * 2. IP address matches (if restricted)
     * 3. Signature is valid (HMAC matches)
     *
     * @param signedUrl - The signed URL to verify
     * @param secret - Secret key used for signing
     * @param requestIp - IP address of the request (for IP restriction check)
     * @param algorithm - Hash algorithm used for signing (default: 'sha256')
     * @returns Verification result with valid flag and error message
     *
     * @example
     * ```typescript
     * const result = SignedUrlGenerator.verifySignedUrl(
     *   'https://cdn.example.com/files/document.pdf?expires=1706745600&signature=abc123...',
     *   'my-secret-key',
     *   '192.168.1.1',
     *   'sha256'
     * );
     *
     * if (result.valid) {
     *   console.log('URL is valid, expires at:', result.expiresAt);
     *   console.log('Permissions:', result.permissions);
     * } else {
     *   console.error('URL is invalid:', result.error);
     * }
     * ```
     */
    static verifySignedUrl(signedUrl: string, secret: string, requestIp?: string, algorithm?: StorageHashAlgorithm): StorageVerificationResult;
    /**
     * Extract parameters from signed URL
     */
    private static extractUrlParameters;
    /**
     * Check if URL has expired
     */
    private static checkExpiration;
    /**
     * Check IP address restriction
     */
    private static checkIpRestriction;
    /**
     * Verify signature matches expected value
     */
    private static verifySignature;
    /**
     * Generate a pre-signed upload URL
     * Allows clients to upload directly to storage without going through the server
     *
     * @param baseUrl - Base URL for uploads
     * @param uploadPath - Path where file will be uploaded
     * @param secret - Secret key for signing
     * @param options - Upload options (expiration, max file size)
     * @returns Signed upload URL
     */
    static generateUploadUrl(baseUrl: string, uploadPath: string, secret: string, options: StorageSignedUrlOptions & {
        maxFileSize?: number;
    }): string;
    /**
     * Generate a temporary download URL with expiration
     * Common use case for file sharing
     *
     * @param baseUrl - Base URL for downloads
     * @param filePath - Path to file
     * @param secret - Secret key for signing
     * @param expiresIn - Expiration time in seconds (default: 3600 = 1 hour)
     * @returns Signed download URL
     */
    static generateDownloadUrl(baseUrl: string, filePath: string, secret: string, expiresIn?: number): string;
    /**
     * Parse signed URL and extract information without verification
     * Useful for debugging or logging
     *
     * @param signedUrl - Signed URL to parse
     * @returns Parsed URL information
     */
    static parseSignedUrl(signedUrl: string): {
        filePath: string;
        expiresAt: number | null;
        ipAddress: string | null;
        permissions: StorageSignedUrlPermission[];
        isExpired: boolean;
        metadata: Record<string, string>;
    };
    /**
     * Extract metadata from URL search params
     */
    private static extractMetadataFromUrl;
    /**
     * Check if URL is expired
     */
    private static isUrlExpired;
    /**
     * Timing-safe string comparison to prevent timing attacks
     *
     * @param a - First string
     * @param b - Second string
     * @returns true if strings are equal
     */
    private static timingSafeEqual;
}
/**
 * Generate a signed download URL (convenience function)
 *
 * @param baseUrl - Base URL
 * @param filePath - File path
 * @param secret - Secret key
 * @param expiresIn - Expiration in seconds (default: 3600)
 * @returns Signed URL
 */
export declare function generateSignedDownloadUrl(baseUrl: string, filePath: string, secret: string, expiresIn?: number): string;
/**
 * Generate a signed upload URL (convenience function)
 *
 * @param baseUrl - Base URL
 * @param uploadPath - Upload path
 * @param secret - Secret key
 * @param options - Upload options
 * @returns Signed URL
 */
export declare function generateSignedUploadUrl(baseUrl: string, uploadPath: string, secret: string, options: StorageSignedUrlOptions & {
    maxFileSize?: number;
}): string;
/**
 * Verify a signed URL (convenience function)
 *
 * @param signedUrl - Signed URL
 * @param secret - Secret key
 * @param requestIp - Request IP address
 * @param algorithm - Hash algorithm (default: 'sha256')
 * @returns Verification result
 */
export declare function verifySignedUrl(signedUrl: string, secret: string, requestIp?: string, algorithm?: StorageHashAlgorithm): StorageVerificationResult;