/**
 * Refresh Token Service with Rotation Support
 *
 * Implements secure refresh token handling with rotation to prevent token theft:
 * - Generates secure 32-byte refresh tokens (base64url encoded)
 * - Stores token hashes (SHA-256) - never stores plaintext
 * - Tracks token families for rotation and theft detection
 * - Automatically revokes entire family on reuse detection (theft indicator)
 * - Redis-backed storage for distributed deployment support
 *
 * Security Features:
 * - Token rotation: each use generates a new token
 * - Family tracking: detects token reuse attacks
 * - Device fingerprinting: binds tokens to devices
 * - Configurable TTL: 24 hours default per CAR spec
 *
 * @packageDocumentation
 */
import { VorionError } from '../common/errors.js';
import { SecurityAuditLogger } from '../audit/security-logger.js';
/**
 * Refresh token error base class
 */
export declare class RefreshTokenError extends VorionError {
    code: string;
    statusCode: number;
    constructor(message: string, details?: Record<string, unknown>);
}
/**
 * Token reuse detected - potential theft
 */
export declare class TokenReuseError extends RefreshTokenError {
    code: string;
    constructor(familyId: string);
}
/**
 * Token expired error
 */
export declare class RefreshTokenExpiredError extends RefreshTokenError {
    code: string;
    constructor();
}
/**
 * Token revoked error
 */
export declare class RefreshTokenRevokedError extends RefreshTokenError {
    code: string;
    constructor(reason: string);
}
/**
 * Invalid token error
 */
export declare class RefreshTokenInvalidError extends RefreshTokenError {
    code: string;
    constructor();
}
/**
 * Refresh token stored data structure
 */
export interface RefreshTokenData {
    /** SHA-256 hash of the token */
    tokenHash: string;
    /** User ID this token belongs to */
    userId: string;
    /** Tenant ID for multi-tenant isolation */
    tenantId: string;
    /** Device fingerprint for binding */
    deviceFingerprint: string;
    /** Token family ID for rotation tracking */
    familyId: string;
    /** Rotation count within the family */
    rotationCount: number;
    /** When the token was created */
    createdAt: string;
    /** When the token expires */
    expiresAt: string;
    /** Whether the token has been used (rotated) */
    used: boolean;
    /** When the token was used */
    usedAt?: string;
    /** IP address at token creation */
    ipAddress?: string;
    /** User agent string */
    userAgent?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Refresh token payload returned to client
 */
export interface RefreshTokenPayload {
    /** User ID */
    userId: string;
    /** Tenant ID */
    tenantId: string;
    /** Device fingerprint */
    deviceFingerprint: string;
    /** Token family ID */
    familyId: string;
    /** Rotation count */
    rotationCount: number;
    /** Expiration timestamp */
    expiresAt: Date;
}
/**
 * Token family data structure
 */
export interface TokenFamily {
    /** Family ID */
    familyId: string;
    /** User ID */
    userId: string;
    /** Tenant ID */
    tenantId: string;
    /** Device fingerprint */
    deviceFingerprint: string;
    /** When the family was created */
    createdAt: string;
    /** Current rotation count */
    rotationCount: number;
    /** Whether the family has been revoked */
    revoked: boolean;
    /** Revocation reason */
    revokedReason?: string;
    /** When the family was revoked */
    revokedAt?: string;
}
/**
 * Create token input
 */
export interface CreateRefreshTokenInput {
    /** User ID */
    userId: string;
    /** Tenant ID */
    tenantId: string;
    /** Device fingerprint */
    deviceFingerprint: string;
    /** IP address */
    ipAddress?: string;
    /** User agent */
    userAgent?: string;
    /** Custom TTL in seconds */
    ttlSeconds?: number;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Token rotation result
 */
export interface TokenRotationResult {
    /** New refresh token */
    newToken: string;
    /** New access token */
    accessToken: string;
    /** Expiration time */
    expiresAt: Date;
}
/**
 * Access token generator function type
 */
export type AccessTokenGenerator = (userId: string, tenantId: string, metadata?: Record<string, unknown>) => Promise<string>;
/**
 * Refresh token service configuration
 */
export interface RefreshTokenServiceConfig {
    /** Refresh token TTL in seconds */
    refreshTokenTTL: number;
    /** Access token TTL in seconds */
    accessTokenTTL: number;
    /** Key prefix for Redis storage */
    keyPrefix: string;
    /** Maximum rotation count before forcing re-authentication */
    maxRotationCount: number;
    /** Custom access token generator */
    accessTokenGenerator?: AccessTokenGenerator;
}
/**
 * Refresh Token Service with rotation support
 *
 * Implements secure refresh token handling with rotation to detect token theft.
 * When a token is used (rotated), a new token is issued. If an old token is
 * reused (indicating theft), the entire token family is revoked.
 *
 * @example
 * ```typescript
 * const refreshTokenService = new RefreshTokenService({
 *   refreshTokenTTL: 86400, // 24 hours
 *   accessTokenGenerator: async (userId, tenantId) => {
 *     return generateAccessToken(userId, tenantId);
 *   },
 * });
 *
 * // Create initial token
 * const { token, payload } = await refreshTokenService.createToken({
 *   userId: 'user-123',
 *   tenantId: 'tenant-456',
 *   deviceFingerprint: 'device-fp-789',
 * });
 *
 * // Rotate token on use
 * const { newToken, accessToken } = await refreshTokenService.rotateToken(token);
 *
 * // Validate token
 * const payload = await refreshTokenService.validateToken(token);
 * ```
 */
export declare class RefreshTokenService {
    private config;
    private redis;
    private securityLogger;
    private accessTokenGenerator;
    constructor(config?: Partial<RefreshTokenServiceConfig>, securityLogger?: SecurityAuditLogger);
    /**
     * Get Redis client, initializing if needed
     */
    private getRedis;
    /**
     * Default access token generator (placeholder)
     * In production, this should be replaced with actual JWT generation
     */
    private defaultAccessTokenGenerator;
    /**
     * Generate Redis key for a token hash
     */
    private tokenKey;
    /**
     * Generate Redis key for a token family
     */
    private familyKey;
    /**
     * Generate Redis key for user's token families index
     */
    private userFamiliesKey;
    /**
     * Create a new refresh token
     */
    createToken(input: CreateRefreshTokenInput): Promise<{
        token: string;
        payload: RefreshTokenPayload;
    }>;
    /**
     * Validate a refresh token without rotating it
     */
    validateToken(token: string): Promise<RefreshTokenPayload | null>;
    /**
     * Rotate a refresh token
     *
     * This is the main method for using a refresh token. It:
     * 1. Validates the token
     * 2. Checks for reuse (theft detection)
     * 3. Issues a new refresh token
     * 4. Issues a new access token
     * 5. Invalidates the old refresh token
     */
    rotateToken(oldToken: string, ipAddress?: string, userAgent?: string): Promise<TokenRotationResult>;
    /**
     * Revoke a token family
     */
    revokeFamily(familyId: string, reason: string, revokedBy?: string): Promise<boolean>;
    /**
     * Internal method to revoke a token family
     */
    private revokeFamilyInternal;
    /**
     * Revoke all token families for a user
     */
    revokeAllForUser(userId: string, tenantId: string, reason: string, revokedBy?: string): Promise<number>;
    /**
     * Get a token family by ID
     */
    getFamily(familyId: string): Promise<TokenFamily | null>;
    /**
     * Get all active token families for a user
     */
    getFamiliesForUser(userId: string): Promise<TokenFamily[]>;
    /**
     * Check if Redis is healthy
     */
    checkHealth(): Promise<{
        healthy: boolean;
        latencyMs?: number;
        error?: string;
    }>;
    /**
     * Get service statistics
     */
    getStats(): {
        refreshTokenTTL: number;
        accessTokenTTL: number;
        maxRotationCount: number;
    };
}
/**
 * Get the singleton refresh token service
 */
export declare function getRefreshTokenService(config?: Partial<RefreshTokenServiceConfig>): RefreshTokenService;
/**
 * Create a new refresh token service instance (for testing)
 */
export declare function createRefreshTokenService(config?: Partial<RefreshTokenServiceConfig>, securityLogger?: SecurityAuditLogger): RefreshTokenService;
/**
 * Reset the singleton (for testing)
 */
export declare function resetRefreshTokenService(): void;
//# sourceMappingURL=refresh-token.d.ts.map