@withstudiocms/auth-kit/dist/config.d.ts

Utilities for managing authentication

import { Brand, Context, Layer } from '@withstudiocms/effect';
import { ScryptConfigOptions } from '@withstudiocms/effect/scrypt';
import type { SessionConfig, UserTools } from './types.js';
/**
 * Configuration options for the password module.
 *
 * @property CMS_ENCRYPTION_KEY - The encryption key used for securing CMS passwords.
 */
export type PasswordModConfig = {
    CMS_ENCRYPTION_KEY: string;
};
/**
 * The finalized configuration object for the password module.
 *
 * @property CMS_ENCRYPTION_KEY - The encryption key used by the CMS for securing sensitive data.
 * @property scrypt - Configuration options for the scrypt password hashing algorithm.
 * @remarks
 * This type is branded as 'PasswordModConfigFinal' to provide nominal typing and prevent accidental misuse.
 */
export type PasswordModConfigFinal = {
    scrypt: ScryptConfigOptions;
} & Brand.Brand<'PasswordModConfigFinal'>;
/**
 * A nominal type for the finalized password module configuration object.
 *
 * This constant uses the `Brand.nominal` utility to create a strongly-typed
 * identifier for the `PasswordModConfigFinal` type, ensuring type safety and preventing
 * accidental misuse of configuration objects.
 *
 * @see PasswordModConfigFinal
 * @see Brand.nominal
 */
export declare const PasswordModConfigFinal: Brand.Brand.Constructor<PasswordModConfigFinal>;
/**
 * Represents the raw configuration object for the Auth Kit.
 *
 * @property CMS_ENCRYPTION_KEY - The encryption key used by the CMS for securing sensitive data.
 * @property session - The required session configuration settings.
 * @property userTools - The user tools configuration.
 */
export type RawAuthKitConfig = {
    CMS_ENCRYPTION_KEY: string;
    session: Required<SessionConfig>;
    userTools: UserTools;
};
/**
 * Configuration options for the AuthKit module.
 *
 * @property CMS_ENCRYPTION_KEY - The encryption key used for securing CMS data.
 * @property scrypt - Configuration options for the scrypt password hashing algorithm.
 * @property session - Required session configuration options.
 * @property userTools - Tools and utilities related to user management.
 * @remarks
 * This type is branded as 'AuthKitConfig' to provide nominal typing.
 */
export type AuthKitConfig = {
    CMS_ENCRYPTION_KEY: string;
    scrypt: ScryptConfigOptions;
    session: Required<SessionConfig>;
    userTools: UserTools;
} & Brand.Brand<'AuthKitConfig'>;
/**
 * A nominal type for the AuthKit configuration object.
 *
 * This constant uses the `Brand.nominal` utility to create a strongly-typed
 * identifier for the `AuthKitConfig` type, ensuring type safety and preventing
 * accidental misuse of configuration objects.
 *
 * @see AuthKitConfig
 * @see Brand.nominal
 */
export declare const AuthKitConfig: Brand.Brand.Constructor<AuthKitConfig>;
/**
 * Generates and validates the final password module configuration using the provided encryption key and optional scrypt parameters.
 *
 * @param config - An object containing the `CMS_ENCRYPTION_KEY` as a base64-encoded string.
 * @returns The finalized password module configuration object.
 *
 * @throws {Error} If the `CMS_ENCRYPTION_KEY` is empty, not valid base64, or does not decode to exactly 16 bytes.
 *
 * @remarks
 * - The `CMS_ENCRYPTION_KEY` must be a base64-encoded string representing 16 bytes (128 bits) for AES-128 encryption.
 * - Scrypt parameters (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`) can be overridden via environment variables. They are clamped to safe ranges.
 * - The function normalizes and validates the encryption key, then constructs the scrypt configuration for password hashing.
 */
export declare function makePasswordModConfig({ CMS_ENCRYPTION_KEY, }: PasswordModConfig): PasswordModConfigFinal;
declare const PasswordModOptions_base: Context.TagClass<PasswordModOptions, "PasswordModOptions", PasswordModConfigFinal>;
/**
 * Represents the options for the Password Module, extending the Context.Tag utility.
 *
 * @template PasswordModOptions - The type of the options for the Password Module.
 * @template PasswordModConfigFinal - The finalized configuration type for the Password Module.
 *
 * @example
 * // Create a live layer with the provided configuration
 * const layer = PasswordModOptions.Live({ CMS_ENCRYPTION_KEY: 'your-key' });
 *
 * @method
 * @static
 * @param {PasswordModConfig} config - The configuration object containing the CMS encryption key.
 * @returns {Layer<PasswordModOptions, PasswordModConfigFinal>} A Layer instance with the provided configuration.
 */
export declare class PasswordModOptions extends PasswordModOptions_base {
    static Live: ({ CMS_ENCRYPTION_KEY }: PasswordModConfig) => Layer.Layer<PasswordModOptions, never, never>;
}
declare const AuthKitOptions_base: Context.TagClass<AuthKitOptions, "AuthKitOptions", AuthKitConfig>;
/**
 * Provides configuration options for the AuthKit module.
 *
 * @remarks
 * This class extends a tagged context for dependency injection and configuration management.
 *
 * @example
 * ```typescript
 * const options = AuthKitOptions.Live({
 *   CMS_ENCRYPTION_KEY: 'secret-key',
 *   session: { ... },
 *   userTools: { ... }
 * });
 * ```
 */
export declare class AuthKitOptions extends AuthKitOptions_base {
    /**
     * Creates a live instance of `AuthKitOptions` using the provided raw configuration.
     *
     * @param CMS_ENCRYPTION_KEY - The encryption key used for cryptographic operations.
     * @param session - session configuration overrides.
     * @param userTools - Tools or utilities related to user management.
     * @returns A Layer that provides the configured `AuthKitOptions`.
     *
     * @remarks
     * - Scrypt parameters (`N`, `r`, `p`) are read from environment variables (`SCRYPT_N`, `SCRYPT_R`, `SCRYPT_P`),
     *   with sensible defaults and minimum values enforced for security.
     * - The session configuration merges defaults with any provided overrides.
     * - The returned Layer can be used for dependency injection in the application.
     */
    static Live: ({ CMS_ENCRYPTION_KEY, session: _session, userTools }: RawAuthKitConfig) => Layer.Layer<AuthKitOptions, never, never>;
}
export {};