/**
 * Secure Secret Value
 *
 * Provides a type-safe way to handle secrets that prevents accidental hardcoding.
 * Secrets must be explicitly created from environment variables or marked as explicit.
 *
 * @example
 * ```typescript
 * // ✅ Recommended: Load from environment variable
 * const secret = SecretValue.fromEnv('JWT_SECRET');
 *
 * // ✅ For testing only: Mark as explicit
 * const testSecret = SecretValue.fromValue('test-secret', { allowHardcoded: true });
 *
 * // ❌ This will fail at runtime:
 * const badSecret = SecretValue.fromValue('hardcoded'); // throws error
 * ```
 */
declare const SecretBrand: unique symbol;
/**
 * A branded type representing a secret value.
 * Cannot be created directly - must use factory methods.
 */
export type SecretString = string & {
    readonly [SecretBrand]: 'SecretValue';
};
/**
 * Options for creating a secret from a direct value
 */
export interface FromValueOptions {
    /**
     * Explicitly allow hardcoded values.
     * Only set to true for testing purposes.
     */
    allowHardcoded?: boolean;
    /**
     * Description of why hardcoded is allowed (for audit purposes)
     */
    reason?: string;
}
/**
 * Secure wrapper for secret values
 */
export declare class SecretValue {
    private readonly value;
    private readonly source;
    private constructor();
    /**
     * Create a secret from an environment variable.
     * This is the recommended way to handle secrets.
     *
     * @param envVarName - Name of the environment variable
     * @param options - Optional configuration
     * @throws Error if the environment variable is not set
     *
     * @example
     * ```typescript
     * const jwtSecret = SecretValue.fromEnv('JWT_SECRET');
     * const dbPassword = SecretValue.fromEnv('DATABASE_PASSWORD');
     * ```
     */
    static fromEnv(envVarName: string, options?: {
        required?: boolean;
    }): SecretValue;
    /**
     * Create a secret from a direct value.
     *
     * **WARNING**: This should only be used for testing.
     * For production, always use `fromEnv()`.
     *
     * @param value - The secret value
     * @param options - Must set allowHardcoded: true to use this method
     * @throws Error if allowHardcoded is not explicitly set to true
     *
     * @example
     * ```typescript
     * // For testing only
     * const testSecret = SecretValue.fromValue('test-secret-for-unit-tests', {
     *   allowHardcoded: true,
     *   reason: 'Unit test fixture'
     * });
     * ```
     */
    static fromValue(value: string, options?: FromValueOptions): SecretValue;
    /**
     * Create a secret from an environment variable or return undefined.
     * Useful for optional secrets.
     *
     * @param envVarName - Name of the environment variable
     *
     * @example
     * ```typescript
     * const optionalSecret = SecretValue.fromEnvOptional('OPTIONAL_API_KEY');
     * if (optionalSecret) {
     *   // Use the secret
     * }
     * ```
     */
    static fromEnvOptional(envVarName: string): SecretValue | undefined;
    /**
     * Get the unwrapped secret value.
     *
     * @returns The raw secret string
     */
    unwrap(): SecretString;
    /**
     * Get the secret value as a plain string.
     * Alias for unwrap() for compatibility.
     */
    getValue(): string;
    /**
     * Check if this secret was loaded from environment
     */
    isFromEnvironment(): boolean;
    /**
     * Prevent accidental logging of secret values
     */
    toString(): string;
    /**
     * Prevent accidental JSON serialization of secret values
     */
    toJSON(): string;
}
/**
 * Type guard to check if a value is a SecretValue
 */
export declare function isSecretValue(value: unknown): value is SecretValue;
/**
 * Helper to unwrap a secret if it's a SecretValue, or use as-is if string.
 * Useful for backward compatibility.
 *
 * @deprecated Prefer using SecretValue directly
 */
export declare function unwrapSecret(secret: SecretValue | string): string;
export {};
//# sourceMappingURL=secure-secret.d.ts.map