@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/references/configuration/environment-variables.md

@@ -1,7 +1,15 @@
 # Environment Variables Reference
 
-Complete reference of all environment variables used by IGNIS framework.
+Complete reference of all environment variables used by the IGNIS framework, grouped by category with defaults and required/optional status.
 
+**Files:**
+
+- [`packages/core-server/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/common/environments.ts) - `EnvironmentKeys`
+- [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `applicationEnvironment`, `Environment`
+- [`packages/core-server/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution priority
+- [`packages/core-server/src/base/applications/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/base.ts) - `registerSecrets()`, `hydrateSecrets()`
+- [`packages/helpers/src/modules/secrets/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/secrets/common/constants.ts) - `SecretProviders`, `VaultAuthMethods`
+- [`packages/helpers/src/modules/secrets/hashicorp/hashicorp.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/secrets/hashicorp/hashicorp.helper.ts) - HashiCorp Vault helper
 
 ## Overview
 
@@ -35,38 +43,38 @@ Create a `.env` file in your project root:
 ```bash
 # .env
 
-# =====================
+# ----------------------
 # APPLICATION
-# =====================
+# ----------------------
 APP_ENV_APPLICATION_NAME=my-app
 APP_ENV_APPLICATION_TIMEZONE=UTC
 
-# =====================
+# ----------------------
 # SERVER
-# =====================
+# ----------------------
 APP_ENV_SERVER_HOST=0.0.0.0
 APP_ENV_SERVER_PORT=3000
 APP_ENV_SERVER_BASE_PATH=/api
 
-# =====================
+# ----------------------
 # DATABASE (PostgreSQL)
-# =====================
+# ----------------------
 APP_ENV_POSTGRES_HOST=localhost
 APP_ENV_POSTGRES_PORT=5432
 APP_ENV_POSTGRES_USERNAME=postgres
 APP_ENV_POSTGRES_PASSWORD=your_password_here
 APP_ENV_POSTGRES_DATABASE=my_database
 
-# =====================
+# ----------------------
 # AUTHENTICATION
-# =====================
+# ----------------------
 APP_ENV_APPLICATION_SECRET=generate-a-strong-random-secret
 APP_ENV_JWT_SECRET=generate-another-strong-random-secret
 APP_ENV_JWT_EXPIRES_IN=86400
 
-# =====================
+# ----------------------
 # LOGGING
-# =====================
+# ----------------------
 APP_ENV_LOGGER_FOLDER_PATH=./logs
 ```
 
@@ -116,7 +124,7 @@ APP_ENV_SERVER_BASE_PATH=/v1/api
 
 ### Priority Order
 
-The server host/port resolution uses this priority (`packages/core/src/base/applications/abstract.ts`):
+The server host/port resolution uses this priority (`packages/core-server/src/base/applications/abstract.ts`):
 1. Explicit config passed to the application constructor
 2. `HOST`/`PORT` variables (for cloud platforms)
 3. `APP_ENV_SERVER_HOST`/`APP_ENV_SERVER_PORT` variables
@@ -189,7 +197,9 @@ export class PostgresDataSource extends BaseDataSource {
 
 ### Security Requirements
 
-The `AuthenticateComponent` receives its secrets programmatically via the `jwtOptions` binding (`jwtSecret`, `getTokenExpiresFn`), not by reading these environment variables directly. These `EnvironmentKeys` constants are the conventional way for your application to supply those values. The component throws at startup if `jwtSecret` is missing or left at the placeholder value - so wiring it from an unset environment variable will fail the boot.
+- **Not read directly.** The `AuthenticateComponent` receives its secrets programmatically via the `jwtOptions` binding (`jwtSecret`, `getTokenExpiresFn`) - it never reads these environment variables itself.
+- **`EnvironmentKeys` is the convention, not a requirement.** These constants are the conventional way for your application to supply those values into the binding.
+- **A missing or placeholder secret fails the boot.** The component throws at startup if `jwtSecret` is missing or left at the placeholder value. Wiring it from an unset environment variable fails the same way.
 
 ### Generate Strong Secrets
 
@@ -221,9 +231,12 @@ APP_ENV_JWT_EXPIRES_IN=86400
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `APP_ENV_LOGGER_FOLDER_PATH` | No | `./` | Directory for log files |
+| `APP_ENV_LOGGER_FOLDER_PATH` | No | _(unset)_ | Directory for log files; file logging is OFF when unset |
 | `APP_ENV_LOGGER_FORMAT` | No | `text` | Log output format |
+| `APP_ENV_LOGGER_LEVEL` | No | `debug` | Logger-level floor; transports without their own level inherit it |
 | `APP_ENV_LOGGER_INSPECT_DEPTH` | No | `5` | How deep a `%s` argument is inspected. Node hard-codes depth `0` for `%s`, which prints `[Object]` one level in; IGNIS widens it. Non-negative integers only - an absent, invalid or negative value falls back to `5` |
+| `APP_ENV_LOGGER_DO_REDACT` | No | `true` | Secret redaction in logged values. ONLY the literal `false` disables it (reveals raw credentials in log lines); anything else keeps redaction ON. Never disable in production |
+| `APP_ENV_LOGGER_COLOR` | No | _(unset)_ | ANSI color on console log lines. Unset means auto: ON in a development `NODE_ENV`, OFF in `production`, `staging`, `uat` and any unrecognized name. `NO_COLOR` also turns it off |
 | `APP_ENV_LOGGER_FILE_FREQUENCY` | No | `1h` | Log file rotation frequency |
 | `APP_ENV_LOGGER_FILE_MAX_SIZE` | No | `100m` | Max size per log file |
 | `APP_ENV_LOGGER_FILE_MAX_FILES` | No | `5d` | Log file retention |
@@ -316,9 +329,14 @@ APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `APP_ENV_APPLICATION_DS_MIGRATION` | No | - | DataSource name for migrations |
-| `APP_ENV_APPLICATION_DS_AUTHORIZE` | No | - | DataSource name for auth |
-| `APP_ENV_APPLICATION_DS_OAUTH2` | No | - | DataSource name for OAuth2 |
+| `APP_ENV_DS_MIGRATION` | No | `postgres` | DataSource name for migrations. Read at boot and printed in the startup banner |
+| `APP_ENV_DS_AUTHORIZE` | No | `postgres` | DataSource name for authorization. Read at boot and printed in the startup banner |
+| `APP_ENV_AUTO_PROVISION_COLLECTION` | No | `false` | Lets a search datasource create a missing collection on first use. `true` or `1` enables it; the `autoProvision` constructor option overrides it |
+
+> [!WARNING] These two name the datasource, they do not select it
+> `APP_ENV_DS_MIGRATION` and `APP_ENV_DS_AUTHORIZE` reach the startup banner and nothing else - the framework does not resolve a datasource from either. Wire your own lookup if you need one.
+
+`Environments` (`packages/core-server/src/common/environments.ts`) also declares `APP_ENV_APPLICATION_DS_MIGRATION`, `APP_ENV_APPLICATION_DS_AUTHORIZE` and `APP_ENV_APPLICATION_DS_OAUTH2`. Those are name constants with no reader anywhere in the framework - setting them changes nothing.
 
 
 ## Debug Variables
@@ -328,8 +346,11 @@ APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
 | `DEBUG` | No | - | Enable debug mode |
 | `NODE_ENV` | No | `development` | Environment mode. One of `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` |
 | `ALLOW_EMPTY_ENV_VALUE` | No | `false` | Allow empty env values |
+| `RUN_MODE` | No | - | Printed in the startup banner. The framework never branches on it - read it yourself to split a migrate run from a serve run |
 
-The gate is fail-closed: an environment IGNIS does not recognise is treated as production, so error responses are sanitized. `local`, `debug`, `development`, `dev` and `sit` are the development environments - only they expose internal error detail. `alpha`, `beta`, `staging` and `production` stay sanitized.
+- **Fail-closed by default.** An environment IGNIS does not recognize is treated as production, so error responses are sanitized.
+- **Development environments expose error detail.** `local`, `debug`, `development`, `dev`, and `sit` are the development set - only these show internal error detail.
+- **Everything else stays sanitized.** `alpha`, `beta`, `staging`, and `production` never expose internal detail, matching production behavior.
 
 ### Example
 
@@ -343,6 +364,29 @@ NODE_ENV=production
 ```
 
 
+## Secrets & Vault
+
+- **A `.env` file is one option, not a requirement.** IGNIS can load these variables from a vault (HashiCorp Vault, an encrypted `.env.vault`, or plain `process.env`). It **hydrates** them into the same `APP_ENV_*` keys at boot.
+- **Hydration is transparent to your code.** Code that reads `process.env.APP_ENV_*` keeps working unchanged - the values arrive from the vault instead of a file.
+- **Hydration runs before datasources are configured** (after `preConfigure()`, before `registerDataSources()`), so a hydrated `APP_ENV_DS_PASSWORD` is available exactly where a file-based one would be.
+- **Vault values take precedence over `process.env`** when the provider is live - a hydrated key overwrites whatever was already in `process.env`.
+
+```typescript
+// Store the key in the vault already named APP_ENV_... and it merges as-is.
+override registerSecrets() {
+  return {
+    provider: SecretProviders.HASHICORP_VAULT,
+    config: { endpoint, auth: { method: VaultAuthMethods.APP_ROLE, roleId, secretId } },
+    hydrate: [{ path: 'secret/data/myapp/config' }],
+  };
+}
+```
+
+> [!NOTE] Failure policy
+> If the vault is unreachable, development environments (`local`, `debug`, `development`, `dev`, `sit`) fall back to `process.env`. Every other environment fails the boot rather than starting with missing secrets.
+
+See the [Secrets & Vault guide](/guides/core-concepts/secrets-vault) for setup and the [Secrets & Vault reference](/references/base/secrets) for the full API.
+
 ## Environment-Specific Files
 
 Create environment-specific `.env` files:
@@ -378,7 +422,7 @@ MY_APP_POSTGRES_HOST=localhost
 
 ## Validation
 
-On startup, IGNIS iterates every `APP_ENV_*` (prefixed) variable that is set and throws if any has an empty value (`validateEnvs` in `packages/core/src/base/applications/abstract.ts`). It does not check for variables that are absent entirely - component-level validation (e.g., the authentication component's `jwtSecret` check) covers required values.
+On startup, IGNIS iterates every `APP_ENV_*` (prefixed) variable that is set and throws if any has an empty value (`validateEnvs` in `packages/core-server/src/base/applications/abstract.ts`). It does not check for variables that are absent entirely - component-level validation (e.g., the authentication component's `jwtSecret` check) covers required values.
 
 ### Disable Validation
 
@@ -400,9 +444,9 @@ ALLOW_EMPTY_ENV_VALUE=true
 ## Complete .env.example
 
 ```bash
-# ===========================================
+# ----------------------
 # IGNIS ENVIRONMENT VARIABLES
-# ===========================================
+# ----------------------
 # Copy this file to .env and fill in values
 
 # APPLICATION
@@ -444,3 +488,11 @@ APP_ENV_LOGGER_FOLDER_PATH=./logs
 # APP_ENV_MAIL_CLIENT_SECRET=
 # APP_ENV_MAIL_REFRESH_TOKEN=
 ```
+
+## See also
+
+- [Configuration Reference](./index.md) - `EnvironmentKeys` constants and the `applicationEnvironment` helper
+- [Secrets & Vault Guide](/guides/core-concepts/secrets-vault) - setup walkthrough for vault-backed secrets
+- [Secrets & Vault Reference](/references/base/secrets) - full provider API (`registerSecrets`, `SecretProviders`, `VaultAuthMethods`)
+- [DataSources Guide](/guides/core-concepts/persistent/datasources) - wiring `APP_ENV_POSTGRES_*` into a DataSource
+- [Logger Helper](/extensions/helpers/logger/) - `APP_ENV_LOGGER_*` variables in depth

package/content/references/configuration/index.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-Configuration options and environment variables for IGNIS applications.
+How IGNIS applications read configuration - the `APP_ENV_` variable convention, the `EnvironmentKeys` constants, and where to look up every value.
 
 ## Quick Reference
 
@@ -14,22 +14,20 @@ Configuration options and environment variables for IGNIS applications.
 | Storage | MinIO/S3 file storage (application-level convention) | `APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY` |
 | Mail | SMTP email sending (application-level convention) | `APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER` |
 
-## Environment Variable Prefix
+**Full list:** [Environment Variables Reference](./environment-variables.md) - every `APP_ENV_*` variable, its default, and whether it's required.
 
-IGNIS uses the `APP_ENV_` prefix to avoid conflicts with system variables:
+## In one example
+
+IGNIS uses the `APP_ENV_` prefix to avoid conflicts with system variables. Create a `.env` file in your project root:
 
 ```bash
 # ✅ IGNIS variables
 APP_ENV_POSTGRES_HOST=localhost
 
-# ❌ Might conflict with system
+# ❌ Might conflict with system variables
 POSTGRES_HOST=localhost
 ```
 
-## Quick Start
-
-Create a `.env` file in your project root:
-
 ```bash
 # .env
 APP_ENV_APPLICATION_NAME=my-app
@@ -39,26 +37,40 @@ APP_ENV_POSTGRES_HOST=localhost
 APP_ENV_POSTGRES_DATABASE=my_database
 ```
 
-## What's in This Section
-
-- [Environment Variables](./environment-variables.md) - Complete reference of all `APP_ENV_*` variables
-
-## Configuration Patterns
-
-### 1. Accessing Variables
+Read a value either directly or through the `applicationEnvironment` helper:
 
 ```typescript
 // 1. Direct access
 const host = process.env.APP_ENV_POSTGRES_HOST;
 
-// 2. Using helper (recommended)
+// 2. Using the helper (recommended)
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 import { EnvironmentKeys } from '@venizia/ignis';
 const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
 ```
 
-### 2. Environment Files
+## How it works
+
+- **One prefix, layered files.** Everything IGNIS reads is prefixed `APP_ENV_` (configurable - see the [Environment Variables Reference](./environment-variables.md#custom-environment-prefix)). Layer `.env`, `.env.local`, and `.env.{NODE_ENV}` the same way any dotenv-based tool does.
+- **`applicationEnvironment` snapshots `process.env` once at import.** It's built from whatever is in `process.env` when `@venizia/ignis-helpers` loads.
+- **Late values need an explicit merge.** A value set programmatically at runtime, after that snapshot, won't appear in `.keys()` unless merged in - secret hydration does this, see below.
+- **Startup validation is fail-closed on emptiness, not absence.** IGNIS iterates every `APP_ENV_*` key that IS set and throws if its value is empty. It does not require a variable to exist at all.
+- **Bypass and per-component checks.** Bypass emptiness validation with `ALLOW_EMPTY_ENV_VALUE=true`. Component-level checks (e.g., the authentication component's `jwtSecret` check) still cover values that must be present.
+- **Secrets don't have to live in a file.** IGNIS can hydrate `APP_ENV_*` keys from a vault at boot, before datasources are configured - see [Secrets & Vault](./environment-variables.md#secrets-vault).
+
+## Common tasks
+
+### Access a variable in code
+Prefer `applicationEnvironment.get()` over `process.env` directly - it stays in sync when secrets are hydrated from a vault.
+
+```typescript
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+import { EnvironmentKeys } from '@venizia/ignis';
 
+const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
+```
+
+### Add a per-environment file
 ```
 project/
 ├── .env                 # Default (development)
@@ -67,14 +79,18 @@ project/
 └── .env.example         # Template (committed)
 ```
 
-### 3. Validation on Startup
-
-IGNIS validates every set `APP_ENV_*` variable on startup and fails with a clear error if any is empty (bypass with `ALLOW_EMPTY_ENV_VALUE=true`). Absent variables are not flagged - components validate their own required inputs.
+### Bypass startup validation during local prototyping
+```bash
+ALLOW_EMPTY_ENV_VALUE=true
+```
+Not recommended once real secrets are wired in - see [Validation](./environment-variables.md#validation).
 
-> **Related:** [Environment Variables Reference](./environment-variables.md) | [DataSources Guide](../../guides/core-concepts/persistent/datasources)
+### Look up every variable's default and requirement
+See the [Environment Variables Reference](./environment-variables.md) for the full table, grouped by Application, Server, Database, Authentication, Logging, Storage, Mail, and Secrets & Vault.
 
-## EnvironmentKeys Class
+## Reference
 
+### EnvironmentKeys class
 ```typescript
 import { EnvironmentKeys } from '@venizia/ignis';
 ```
@@ -82,7 +98,7 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | Constant | Description |
 |----------|-------------|
 | `APP_ENV_APPLICATION_NAME` | Application display name |
-| `APP_ENV_APPLICATION_TIMEZONE` | Application timezone (e.g., 'Asia/Ho_Chi_Minh') |
+| `APP_ENV_APPLICATION_TIMEZONE` | Application timezone (e.g., `'Asia/Ho_Chi_Minh'`) |
 | `APP_ENV_APPLICATION_SECRET` | Application-wide secret key |
 | `APP_ENV_JWT_SECRET` | JWT signing secret |
 | `APP_ENV_JWT_EXPIRES_IN` | JWT token expiration |
@@ -92,8 +108,8 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | `APP_ENV_APPLICATION_DS_AUTHORIZE` | DataSource name for authorization |
 | `APP_ENV_APPLICATION_DS_OAUTH2` | DataSource name for OAuth2 |
 | `APP_ENV_OAUTH2_VIEW_FOLDER` | OAuth2 view templates folder |
-| `APP_ENV_SERVER_HOST` | HTTP server host (e.g., '0.0.0.0') |
-| `APP_ENV_SERVER_PORT` | HTTP server port (e.g., 3000) |
+| `APP_ENV_SERVER_HOST` | HTTP server host (e.g., `'0.0.0.0'`) |
+| `APP_ENV_SERVER_PORT` | HTTP server port (e.g., `3000`) |
 | `APP_ENV_SERVER_BASE_PATH` | Base URL path prefix |
 | `APP_ENV_DATASOURCE_NAME` | Default datasource name |
 | `APP_ENV_POSTGRES_HOST` | PostgreSQL host |
@@ -102,11 +118,15 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | `APP_ENV_POSTGRES_PASSWORD` | PostgreSQL password |
 | `APP_ENV_POSTGRES_DATABASE` | PostgreSQL database name |
 
-Usage:
+## See also
 
-```typescript
-import { applicationEnvironment } from '@venizia/ignis-helpers';
-import { EnvironmentKeys } from '@venizia/ignis';
+- [Environment Variables Reference](./environment-variables.md) - complete variable list, defaults, and the Secrets & Vault section
+- [Secrets & Vault Guide](/guides/core-concepts/secrets-vault) - setup walkthrough
+- [Secrets & Vault Reference](/references/base/secrets) - full provider API
+- [DataSources Guide](/guides/core-concepts/persistent/datasources) - wiring `APP_ENV_POSTGRES_*` into a DataSource
 
-const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
-```
+**Files:**
+
+- [`packages/core-server/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/common/environments.ts) - `EnvironmentKeys`
+- [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `applicationEnvironment`, `Environment`, `ApplicationEnvironment`
+- [`packages/core-server/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution

package/content/references/index.md

@@ -162,7 +162,7 @@ import {
 import {
   LoggerFactory,
   RedisSingleHelper,
-  QueueHelper,
+  SequentialQueueHelper,
 } from '@venizia/ignis-helpers';
 
 // DI Container

package/content/references/quick-reference.md

@@ -81,9 +81,8 @@ class GreeterController extends BaseGrpcController {
 ### BaseService
 
 ```typescript
-import { BaseService, injectable } from '@venizia/ignis';
+import { BaseService } from '@venizia/ignis';
 
-@injectable({})
 class UserService extends BaseService {
   constructor() {
     super({ scope: UserService.name });
@@ -308,17 +307,6 @@ const users = await userRepository.find({
 
 ## Dependency Injection
 
-### Injectable Decorator
-
-```typescript
-import { injectable } from '@venizia/ignis';
-
-@injectable({})
-class MyService extends BaseService {
-  // ...
-}
-```
-
 ### Inject Decorator
 
 ```typescript
@@ -368,7 +356,6 @@ import {
 
   // DI
   inject,
-  injectable,
 
   // Utilities
   jsonResponse,
@@ -513,7 +500,7 @@ if (Statuses.isCompleted(order.status)) {
 
 ```typescript
 import {
-  appErrorHandler,
+  AppErrorMiddleware,
   notFoundHandler,
   RequestSpyMiddleware,
   emojiFavicon,
@@ -529,7 +516,7 @@ app.use(requestSpy.value());
 app.use(emojiFavicon({ icon: '🚀' }));
 
 // Error handling (register last)
-app.onError(appErrorHandler({ logger: app.logger }));
+app.onError(new AppErrorMiddleware({ logger: app.logger }).value());
 
 // 404 handler
 app.notFound(notFoundHandler({ logger: app.logger }));

package/content/references/utilities/crypto.md

@@ -1,98 +1,57 @@
-# Crypto Utility
-
-The Crypto utility provides a single stateless `hash` function built on Node's built-in `node:crypto` module. It covers the two most common lightweight hashing needs - MD5 digests and HMAC-SHA256 signatures - without any external dependencies.
-
-::: tip Full AES / RSA / ECDH encryption
-This page covers only the utility-level `hash` function. For full symmetric/asymmetric encryption (AES-256-CBC, AES-256-GCM, RSA, ECDH key exchange) see the [Crypto helper](/extensions/helpers/crypto/).
-:::
-
-## `hash`
-
-Creates a hash or HMAC digest of a string and returns it as a text-encoded string.
-
-### Signature
-
-```typescript
-hash(
-  text: string,
-  options: {
-    algorithm: 'SHA256' | 'MD5';
-    secret?: string;
-    outputType: BinaryToTextEncoding; // 'hex' | 'base64' | 'base64url' | 'latin1'
-  },
-): string
-```
-
-**Parameters**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `text` | `string` | The input string to hash. |
-| `options.algorithm` | `'SHA256' \| 'MD5'` | Hashing algorithm. |
-| `options.secret` | `string` (optional) | Secret key for HMAC. Only used when `algorithm` is `'SHA256'`. |
-| `options.outputType` | `BinaryToTextEncoding` | Encoding of the output string - typically `'hex'` or `'base64'`. |
+---
+title: Crypto Utility
+description: Stateless MD5 and HMAC-SHA256 hashing built on node:crypto
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-### Behavior
-
-| Algorithm | `secret` provided | Result |
-|-----------|-------------------|--------|
-| `'MD5'` | ignored | MD5 digest of `text` |
-| `'SHA256'` | yes | HMAC-SHA256 of `text` signed with `secret` |
-| `'SHA256'` | no / `undefined` | `text` returned unchanged (no-op) |
-| any other | - | `text` returned unchanged (no-op) |
-
-The SHA256 pass-through is intentional: it lets callers skip hashing conditionally (for example, when a secret is not yet configured) without adding an extra `if` at the call site. If you need an unconditional SHA256 hash without a secret, use MD5 or the full [Crypto helper](/extensions/helpers/crypto/).
+# Crypto Utility
 
-### Examples
+A single stateless `hash` function for lightweight MD5 digests and HMAC-SHA256 signatures, with no external dependencies beyond Node's built-in `node:crypto`.
 
-**MD5 digest (hex)**
+## In one example
 
 ```typescript
 import { hash } from '@venizia/ignis-helpers';
 
 const digest = hash('user@example.com', { algorithm: 'MD5', outputType: 'hex' });
 // => 'b58996c504c5638798eb6b511e6f49af'
-```
-
-**MD5 digest (base64) - useful for HTTP ETags**
-
-```typescript
-const etag = hash(JSON.stringify(payload), { algorithm: 'MD5', outputType: 'base64' });
-// => 'tYlsUExWOHeY62a1EW9Jr...'
-```
-
-**HMAC-SHA256 - signing a webhook payload**
-
-```typescript
-import { hash } from '@venizia/ignis-helpers';
 
 const signature = hash(rawBody, {
   algorithm: 'SHA256',
   secret: process.env.WEBHOOK_SECRET,
   outputType: 'hex',
 });
-
-// Compare against the value in the X-Hub-Signature-256 header
-const expected = `sha256=${signature}`;
+// Compare against the X-Hub-Signature-256 header: `sha256=${signature}`
 ```
 
-**HMAC-SHA256 in base64 - API request signing**
+## Functions
 
-```typescript
-const hmac = hash(`${timestamp}.${body}`, {
-  algorithm: 'SHA256',
-  secret: apiKey,
-  outputType: 'base64',
-});
-```
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `hash` | `hash(text: string, options: { algorithm: 'SHA256' \| 'MD5'; secret?: string; outputType: BinaryToTextEncoding }): string` | Creates an MD5 digest or an HMAC-SHA256 signature of `text`, encoded via `outputType` (`'hex'`, `'base64'`, `'base64url'`, `'latin1'`). |
+
+## Behavior
+
+| Algorithm | `secret` provided | Result |
+|-----------|-------------------|--------|
+| `'MD5'` | ignored | MD5 digest of `text` |
+| `'SHA256'` | yes | HMAC-SHA256 of `text` signed with `secret` |
+| `'SHA256'` | no / `undefined` | `text` returned unchanged (no-op) |
+| any other value | - | `text` returned unchanged (no-op) |
+
+## Notes
+
+- **The SHA256 pass-through is intentional.** It lets callers skip hashing conditionally (for example, when a secret is not yet configured) without an extra `if` at the call site.
+- **Need an unconditional SHA256 hash with no secret?** Use `'MD5'`, or reach for the full [Crypto helper](/extensions/helpers/crypto/).
+- **Typical uses:** cache keys or ETags from response bodies (MD5), webhook signature verification (HMAC-SHA256), API request signing (HMAC-SHA256), anonymising PII before logging (MD5).
+- **Out of scope:** encryption, decryption, and asymmetric operations (AES, RSA, ECDH) - see the [Crypto helper](/extensions/helpers/crypto/) instead.
 
-## When to use
+## See also
 
-Use `hash` for lightweight, one-off hashing that does not require key management or IV handling:
+- [Crypto helper](/extensions/helpers/crypto/) - full AES / RSA / ECDH encryption
+- [Utilities Overview](/references/utilities/) - all utility functions
 
-- Building cache keys or ETags from response bodies (MD5)
-- Verifying webhook signatures (HMAC-SHA256)
-- Signing API requests with a shared secret (HMAC-SHA256)
-- Anonymising personally identifiable data before storing in logs (MD5)
+**Files:**
 
-For encryption, decryption, or asymmetric operations (AES, RSA, ECDH) use the [Crypto helper](/extensions/helpers/crypto/) instead.
+- [`packages/helpers/src/utilities/crypto.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/crypto.utility.ts)