Authentication & Hashing

/**
 * Define hash configuration with multiple drivers
 * @param config - Hash configuration object
 * @returns Validated hash configuration
 */
function defineConfig(config: HashConfig): HashConfig;

/**
 * Hash configuration interface
 */
interface HashConfig {
  /** Default hash driver to use */
  default: string;
  /** Available hash driver configurations */
  list: Record<string, HashDriverConfig>;
}

/**
 * Available hash drivers with their factory functions
 */
const drivers: {
  /** Argon2 hashing driver */
  argon: ArgonDriverFactory;
  /** bcrypt hashing driver */
  bcrypt: BcryptDriverFactory;
  /** scrypt hashing driver */
  scrypt: ScryptDriverFactory;
};

import { defineConfig, drivers } from "@adonisjs/core/hash";

export default defineConfig({
  default: "argon",
  list: {
    argon: drivers.argon({
      variant: "id",
      memory: 65536,
      iterations: 3,
      parallelism: 4,
    }),
    bcrypt: drivers.bcrypt({
      rounds: 12,
    }),
    scrypt: drivers.scrypt({
      cost: 16384,
      blockSize: 8,
      parallelization: 1,
      keyLength: 64,
    }),
  },
});

/**
 * Hash manager for performing hashing operations
 */
class HashManager {
  /**
   * Use specific hash driver
   * @param driver - Driver name (optional, uses default if not provided)
   * @returns Hash driver instance
   */
  use(driver?: string): HashContract;

  /**
   * Hash value using default driver
   * @param value - Value to hash
   * @returns Hashed value
   */
  hash(value: string): Promise<string>;

  /**
   * Verify value against hash using default driver
   * @param hashedValue - Previously hashed value
   * @param plainValue - Plain value to verify
   * @returns True if values match
   */
  verify(hashedValue: string, plainValue: string): Promise<boolean>;

  /**
   * Check if hash needs rehashing (due to config changes)
   * @param hashedValue - Previously hashed value
   * @returns True if rehashing is needed
   */
  needsReHash(hashedValue: string): boolean;

  /**
   * Get hash info/metadata
   * @param hashedValue - Hashed value to inspect
   * @returns Hash metadata
   */
  ids(hashedValue: string): HashInfo;
}

/**
 * Hash driver contract interface
 */
interface HashContract {
  /**
   * Hash a plain value
   * @param value - Plain text value to hash
   * @returns Promise resolving to hashed value
   */
  hash(value: string): Promise<string>;

  /**
   * Verify plain value against hash
   * @param hashedValue - Previously hashed value
   * @param plainValue - Plain value to verify
   * @returns Promise resolving to boolean indicating match
   */
  verify(hashedValue: string, plainValue: string): Promise<boolean>;

  /**
   * Check if hash needs rehashing
   * @param hashedValue - Previously hashed value
   * @returns Boolean indicating if rehashing is needed
   */
  needsReHash(hashedValue: string): boolean;

  /**
   * Get hash algorithm info
   * @param hashedValue - Hashed value to inspect
   * @returns Hash algorithm information
   */
  ids(hashedValue: string): HashInfo;
}

/**
 * Argon2 driver factory function
 * @param config - Argon2 configuration options
 * @returns Argon2 driver factory
 */
interface ArgonDriverFactory {
  (config: ArgonConfig): {
    driver: "argon2";
    config: ArgonConfig;
  };
}

/**
 * Argon2 algorithm configuration
 */
interface ArgonConfig {
  /** Argon2 variant: 'i', 'd', or 'id' */
  variant: "i" | "d" | "id";
  /** Memory usage in KB */
  memory: number;
  /** Number of iterations */
  iterations: number;
  /** Degree of parallelism */
  parallelism: number;
  /** Salt length (optional) */
  saltLength?: number;
  /** Hash length (optional) */
  hashLength?: number;
}

/**
 * bcrypt driver factory function
 * @param config - bcrypt configuration options
 * @returns bcrypt driver factory
 */
interface BcryptDriverFactory {
  (config: BcryptConfig): {
    driver: "bcrypt";
    config: BcryptConfig;
  };
}

/**
 * bcrypt algorithm configuration
 */
interface BcryptConfig {
  /** Number of salt rounds (4-31) */
  rounds: number;
}

/**
 * scrypt driver factory function
 * @param config - scrypt configuration options
 * @returns scrypt driver factory
 */
interface ScryptDriverFactory {
  (config: ScryptConfig): {
    driver: "scrypt";
    config: ScryptConfig;
  };
}

/**
 * scrypt algorithm configuration
 */
interface ScryptConfig {
  /** CPU/memory cost parameter */
  cost: number;
  /** Block size parameter */
  blockSize: number;
  /** Parallelization parameter */
  parallelization: number;
  /** Derived key length */
  keyLength: number;
  /** Salt length (optional) */
  saltLength?: number;
}

/**
 * PHC string formatter for standardized hash formats
 */
class PhcFormatter {
  /**
   * Serialize hash parameters to PHC format
   * @param id - Algorithm identifier
   * @param params - Algorithm parameters
   * @param salt - Salt bytes
   * @param hash - Hash bytes
   * @returns PHC formatted string
   */
  static serialize(
    id: string,
    params: Record<string, any>,
    salt: Buffer,
    hash: Buffer
  ): string;

  /**
   * Deserialize PHC formatted string
   * @param phcString - PHC formatted hash string
   * @returns Parsed hash components
   */
  static deserialize(phcString: string): PhcNode;

  /**
   * Verify PHC string format
   * @param phcString - String to verify
   * @returns True if valid PHC format
   */
  static verify(phcString: string): boolean;
}

import { HashManager } from "@adonisjs/core/hash";

// Basic hashing
const hashManager = new HashManager();

// Hash password
const hashedPassword = await hashManager.hash("user-password");

// Verify password
const isValid = await hashManager.verify(hashedPassword, "user-password");

// Use specific driver
const argonHash = await hashManager.use("argon").hash("password");
const bcryptHash = await hashManager.use("bcrypt").hash("password");

// Check if rehashing needed (after config changes)
if (hashManager.needsReHash(hashedPassword)) {
  const newHash = await hashManager.hash("user-password");
  // Update stored hash
}

// Get hash information
const hashInfo = hashManager.ids(hashedPassword);
console.log(hashInfo.name); // 'argon2id'
console.log(hashInfo.params); // { m: 65536, t: 3, p: 4 }

/**
 * Generate random string for salts or tokens
 * @param length - String length
 * @returns Random string
 */
function generateRandomString(length: number): string;

/**
 * Constant-time string comparison
 * @param a - First string
 * @param b - Second string
 * @returns True if strings are equal
 */
function safeEqual(a: string, b: string): boolean;

/**
 * Generate cryptographically secure random bytes
 * @param size - Number of bytes
 * @returns Buffer with random bytes
 */
function randomBytes(size: number): Buffer;

type HashDriverConfig = 
  | { driver: "argon2"; config: ArgonConfig }
  | { driver: "bcrypt"; config: BcryptConfig }
  | { driver: "scrypt"; config: ScryptConfig };

interface HashInfo {
  /** Hash algorithm name */
  name: string;
  /** Algorithm parameters */
  params: Record<string, any>;
  /** Salt used */
  salt?: Buffer;
  /** Hash value */
  hash?: Buffer;
}

interface PhcNode {
  /** Algorithm identifier */
  id: string;
  /** Algorithm parameters */
  params: Record<string, any>;
  /** Salt bytes */
  salt: Buffer;
  /** Hash bytes */
  hash: Buffer;
}

interface ManagerDriverFactory<T> {
  (config: T): {
    driver: string;
    config: T;
  };
}