@dollhousemcp/mcp-server/dist/security/tokenManager.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Secure GitHub token management and validation
 */
import { RateLimiter } from '../utils/RateLimiter.js';
import { IFileOperationsService } from '../services/FileOperationsService.js';
export interface TokenScopes {
    required: string[];
    optional?: string[];
}
export interface TokenValidationResult {
    isValid: boolean;
    scopes?: string[];
    rateLimit?: {
        remaining: number;
        resetTime: Date;
    };
    rateLimitExceeded?: boolean;
    retryAfterMs?: number;
    error?: string;
}
/**
 * Secure GitHub token manager with validation and protection
 */
export declare class TokenManager {
    private static tokenLoggedOnce;
    /** Reset static flags for test isolation. */
    static resetStaticState(): void;
    private static readonly GITHUB_TOKEN_PATTERNS;
    private static readonly TOKEN_DIR;
    private static readonly TOKEN_FILE;
    private static readonly ALGORITHM;
    private static readonly KEY_LENGTH;
    private static readonly IV_LENGTH;
    private static readonly TAG_LENGTH;
    private static readonly SALT_LENGTH;
    private static readonly ITERATIONS;
    private tokenValidationLimiter;
    private fileOperations;
    constructor(fileOperations: IFileOperationsService);
    /**
     * Get or create the token validation rate limiter
     * Prevents brute force token validation attacks
     */
    private getTokenValidationLimiter;
    /**
     * Create a rate limiter specifically for token validation
     * Conservative limits to prevent abuse while allowing legitimate usage
     */
    createTokenValidationLimiter(): RateLimiter;
    /**
     * Reset the token validation rate limiter
     * Useful for testing or manual intervention
     */
    resetTokenValidationLimiter(): void;
    /**
     * Validate GitHub token format
     */
    validateTokenFormat(token: string): boolean;
    /**
     * Get GitHub token from environment with validation
     *
     * Supports backward compatibility with old variable names:
     * - GITHUB_TOKEN (canonical)
     * - TEST_GITHUB_TOKEN (deprecated)
     * - GITHUB_TEST_TOKEN (deprecated)
     */
    getGitHubToken(): string | null;
    /**
     * Redact token for safe logging
     */
    redactToken(token: string): string;
    /**
     * Get token type from format
     */
    getTokenType(token: string): string;
    /**
     * Get safe token prefix for logging
     */
    getTokenPrefix(token: string): string;
    /**
     * Validate token scopes via GitHub API
     */
    validateTokenScopes(token: string, requiredScopes: TokenScopes): Promise<TokenValidationResult>;
    /**
     * Create safe error message without token exposure
     */
    createSafeErrorMessage(error: string, token?: string): string;
    /**
     * Get minimum required scopes for different operations
     *
     * NOTE: The 'marketplace' scope identifier is kept for backward compatibility
     * with existing token validations. This is an internal scope name and does not
     * affect user-facing functionality. (PR #280)
     */
    getRequiredScopes(operation: 'read' | 'write' | 'marketplace' | 'collection' | 'gist'): TokenScopes;
    /**
     * Check if token has sufficient permissions for operation
     *
     * NOTE: The 'marketplace' operation type is kept for backward compatibility.
     * This is called internally when accessing collection features. (PR #280)
     */
    ensureTokenPermissions(operation: 'read' | 'write' | 'marketplace' | 'collection' | 'gist'): Promise<TokenValidationResult>;
    /**
     * Derive encryption key from a passphrase
     */
    private deriveKey;
    /**
     * Get passphrase for token encryption.
     *
     * Priority: DOLLHOUSE_TOKEN_SECRET env var → machine-derived passphrase (fallback).
     * The machine-derived passphrase uses homedir + USER which is predictable (#1735).
     * Set DOLLHOUSE_TOKEN_SECRET for stronger protection.
     */
    private getPassphrase;
    /**
     * Machine-derived passphrase — fallback when DOLLHOUSE_TOKEN_SECRET is not
     * set, and migration path for tokens encrypted before that env var existed.
     * Not deprecated; still the default for installations that haven't opted in
     * to an explicit secret.
     */
    private getMachinePassphrase;
    /**
     * Attempt decryption with the primary passphrase, then fall back to the
     * machine-derived passphrase for backward compatibility (#1735).
     */
    private decryptWithFallback;
    private decryptToken;
    /**
     * Store GitHub token securely to file
     */
    storeGitHubToken(token: string): Promise<void>;
    /**
     * Retrieve GitHub token from secure storage
     */
    retrieveGitHubToken(): Promise<string | null>;
    /**
     * Remove stored GitHub token
     */
    removeStoredToken(): Promise<void>;
    /**
     * Get GitHub token from environment or secure storage
     * Updated to check secure storage if environment variable not set
     */
    getGitHubTokenAsync(): Promise<string | null>;
}
//# sourceMappingURL=tokenManager.d.ts.map