@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/components/websocket/index.md

@@ -42,11 +42,12 @@ export class Application extends BaseApplication {
 
 ## How it works
 
-- **Two-phase startup solves a timing problem.** `binding()` runs during `initialize()`, before any Bun server exists. It validates bindings and registers a post-start hook; the actual `WebSocketServerHelper` is only constructed once `executePostStartHooks()` runs, after `Bun.serve()` has produced a live server instance.
-- **Two bindings gate startup.** `REDIS_CONNECTION` (must be an `AbstractRedisHelper` instance) and `AUTHENTICATE_HANDLER` are required. `binding()` throws synchronously if either is missing or the wrong type - before the post-start hook is even registered.
+- **Two-phase startup solves a timing problem.** `binding()` runs during `initialize()`, before any Bun server exists. It validates bindings and registers a post-start hook. The actual `WebSocketServerHelper` is only constructed once `executePostStartHooks()` runs, after `Bun.serve()` has produced a live server instance.
+- **Two bindings gate startup.** `REDIS_CONNECTION` and `AUTHENTICATE_HANDLER` are both required. `REDIS_CONNECTION` must be an `AbstractRedisHelper` instance. `binding()` throws synchronously if either is missing or the wrong type - before the post-start hook is even registered.
 - **Runtime is checked first, fast.** `RuntimeModules.detect()` runs at the top of `binding()`. On Node.js it throws immediately, so a misconfigured app fails at startup, not on first connection.
 - **The instance appears only after start.** The post-start hook binds the configured helper to `WebSocketBindingKeys.WEBSOCKET_INSTANCE`. It does not exist during DI construction. Inject it lazily from a service or controller, never via `@inject` in a constructor.
-- **A custom `fetch` handler splits traffic.** After the post-start hook runs, `server.reload()` swaps in a handler that routes WebSocket upgrade requests (`GET <path>` with an `Upgrade: websocket` header) to Bun's native handler, and everything else to the existing Hono server unchanged.
+- **A custom `fetch` handler splits traffic.** After the post-start hook runs, `server.reload()` swaps in a new handler. It routes WebSocket upgrade requests - `GET <path>` with an `Upgrade: websocket` header - to Bun's native handler.
+  - Everything else goes to the existing Hono server, unchanged.
 
 ## Common tasks
 
@@ -120,7 +121,7 @@ this.bind({ key: WebSocketBindingKeys.HANDSHAKE_HANDLER }).toValue(handshakeFn);
 
 **Files:**
 
-- [`packages/core/src/components/websocket/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/component.ts) - `WebSocketComponent`
-- [`packages/core/src/components/websocket/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/common/keys.ts) - `WebSocketBindingKeys`
-- [`packages/core/src/components/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/common/types.ts) - `IServerOptions`, `DEFAULT_SERVER_OPTIONS`
-- [`packages/core/src/components/websocket/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/websocket/handlers/bun.handler.ts) - `createBunFetchHandler`
+- [`packages/core-server/src/components/websocket/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/component.ts) - `WebSocketComponent`
+- [`packages/core-server/src/components/websocket/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/common/keys.ts) - `WebSocketBindingKeys`
+- [`packages/core-server/src/components/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/common/types.ts) - `IServerOptions`, `DEFAULT_SERVER_OPTIONS`
+- [`packages/core-server/src/components/websocket/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/handlers/bun.handler.ts) - `createBunFetchHandler`

package/content/extensions/components/websocket/usage.md

@@ -61,11 +61,19 @@ export class NotificationService extends BaseService {
 
 - **Never `@inject` `WEBSOCKET_INSTANCE` in a constructor.** It is not bound yet at that point - the lazy getter is the only correct pattern.
 - **`sendToClient`/`sendToUser`/`sendToRoom`/`broadcast` are local-only.** They fan out to clients connected to this process. Cross-instance delivery goes through `send()` (Redis-backed) or `WebSocketEmitter` - see below.
-- **`send({ destination, payload })` resolves `destination` dynamically** against local clients, then local rooms, then falls back to publishing as a `ROOM` message on Redis. There is no `userId` destination in `send()` - use `sendToUser()` (local) or `WebSocketEmitter.toUser()` (cross-instance) to reach every session of a user.
+- **`send({ destination, payload })` resolves `destination` dynamically**, in this order:
+
+  | Order | Checks |
+  |---|---|
+  | 1 | Local clients |
+  | 2 | Local rooms |
+  | 3 | Redis, publishing as a `ROOM` message (fallback) |
+
+  There is no `userId` destination in `send()`. To reach every session of a user, use `sendToUser()` (local) or `WebSocketEmitter.toUser()` (cross-instance).
 
 ## Send from a process with no WebSocket server
 
-`WebSocketEmitter` is a standalone, Redis-only publisher for background workers, cron jobs, other microservices, or CLI scripts - anything that needs to push a WebSocket message without running a server. It publishes the same `IRedisSocketMessage` envelope the server helper listens for, so every connected server instance delivers it to its local clients.
+`WebSocketEmitter` is a standalone, Redis-only publisher. Use it from background workers, cron jobs, other microservices, or CLI scripts - anything that needs to push a WebSocket message without running a server. It publishes the same `IRedisSocketMessage` envelope the server helper listens for, so every connected server instance delivers it to its local clients.
 
 | Scenario | Use |
 |----------|-----|
@@ -90,9 +98,9 @@ await emitter.broadcast({ event: 'system:maintenance', data: { message: 'Schedul
 await emitter.shutdown(); // always release the Redis connection when done
 ```
 
-- **Fixed `serverId`.** The emitter always publishes with `serverId: 'emitter'`, which never matches a server's `crypto.randomUUID()` - so every server instance processes its messages, none self-dedup.
-- **One Redis client, not two.** The emitter only needs a pub client; the server helper needs pub + sub.
-- **`toUser()` is the recommended cross-instance path.** It publishes to `ws:user:{userId}`; every server subscribed via `psubscribe('ws:user:*')` receives it and calls `sendToUser()` locally, reaching every session of that user across all instances.
+- **Fixed `serverId`.** The emitter always publishes with `serverId: 'emitter'`. That value never matches a server's `crypto.randomUUID()`, so every server instance processes its messages - none self-dedup.
+- **One Redis client, not two.** The emitter only needs a pub client. The server helper needs both pub and sub.
+- **`toUser()` is the recommended cross-instance path.** It publishes to `ws:user:{userId}`. Every server subscribed via `psubscribe('ws:user:*')` receives it and calls `sendToUser()` locally - reaching every session of that user across all instances.
 
 ## Read the wire protocol
 
@@ -216,8 +224,13 @@ Client                          Server
   |                                |-- clientConnectedFn()
 ```
 
-- **Two timeout phases, not one.** The initial `authTimeout` (5s default) starts on connect and closes with `4001` if no `authenticate` event arrives. Once `authenticate` is received, that timer is replaced with `authTimeout * 3` (15s default) to give the async `authenticateFn` (and `handshakeFn`) room to complete.
-- **A client's own ID becomes a room.** After authentication, `joinRoom({ clientId, room: clientId })` runs automatically - this is what lets `send({ destination: clientId })` or `sendToRoom({ room: clientId })` target one specific client.
+- **Two timeout phases, not one:**
+
+  | Phase | Timeout | Starts when | On expiry |
+  |---|---|---|---|
+  | Initial | `authTimeout` (5s default) | Connection opens | Closes with `4001` if no `authenticate` event arrives |
+  | Post-authenticate | `authTimeout * 3` (15s default) | `authenticate` event is received | Gives the async `authenticateFn` (and `handshakeFn`, when encryption is required) room to complete |
+- **A client's own ID becomes a room.** After authentication, `joinRoom({ clientId, room: clientId })` runs automatically. This is what lets `send({ destination: clientId })` or `sendToRoom({ room: clientId })` target one specific client.
 - **Encrypted clients skip Bun's native topics.** A client's own `clientId` topic is subscribed before auth (always). `BROADCAST_TOPIC` and rooms are subscribed after auth, but only when `!client.encrypted`. Encrypted clients rely entirely on the per-client `outboundTransformer` path.
 
 ## Understand the delivery strategy
@@ -232,7 +245,7 @@ The helper picks a delivery path per call, based on encryption and `exclude`:
 | `outboundTransformer` bound at all | **All** room/broadcast sends fall back to per-client iteration, even for non-encrypted clients in the same room - Bun's native pub/sub cannot selectively transform |
 
 > [!IMPORTANT]
-> Only bind `outboundTransformer` when you actually need per-client message transformation (e.g. per-client encryption). Binding it removes the fast path for every room/broadcast send, encrypted or not.
+> Only bind `outboundTransformer` when you actually need per-client message transformation (for example per-client encryption). Binding it removes the fast path for every room/broadcast send, encrypted or not.
 
 ## See also
 

package/content/extensions/helpers/cron/index.md

@@ -6,7 +6,7 @@ difficulty: beginner
 
 # Cron
 
-`CronHelper` wraps the `cron` package's `CronJob` with scoped logging and convenience methods for rescheduling and duplicating jobs.
+`CronHelper` wraps the `cron` package's `CronJob`. It adds scoped logging, and convenience methods for rescheduling and duplicating jobs.
 
 ## In one example
 
@@ -27,11 +27,12 @@ const job = new CronHelper({
 
 ## How it works
 
-- **The constructor builds the job synchronously.** `buildInstance()` runs inside the constructor and creates a `CronJob` via `CronJob.from(...)`. An empty `cronTime` or a malformed cron expression throws immediately - `getError` never lets the object come back into your hands half-built.
-- **`start()` and `stop()` guard against a missing instance.** If `buildInstance()` never produced a `CronJob` (a prior `configure()` failure), `start()` logs `'Invalid cron instance to start cronjob!'` and returns without throwing. `stop()` is `async` because the underlying `CronJob.stop()` resolves only once an in-flight tick finishes - awaiting it prevents a replacement job from starting while the old handler is still running.
-- **`modifyCronTime()` reschedules in place.** It builds a new `CronTime`, calls `instance.setTime(...)`, and updates the stored `cronTime` - the same `CronJob` keeps running, it just fires on the new schedule.
-- **`duplicate()` clones configuration, not state.** The new instance shares `onTick`, `onCompleted`, `autoStart`, `tz`, and `errorHandler` with a different `cronTime`. It is fully independent - stopping or modifying one does not touch the other.
-- **The `instance` property is the raw `CronJob`.** Use it for anything the wrapper does not expose - `isActive`, `lastDate()`, `fireOnTick()` - from the [`cron`](https://github.com/kelektiv/node-cron) package (an optional peer dependency, `^4.3.3`).
+- **The constructor builds the job right away.** `buildInstance()` runs inside the constructor and creates a `CronJob` via `CronJob.from(...)`. An empty `cronTime`, or a malformed cron expression, throws immediately - `getError` never lets you hold a half-built job.
+- **`start()` checks for a built job first.** If a prior `configure()` call failed, `buildInstance()` never produced a `CronJob`. `start()` then logs a warning and returns - it does not throw.
+- **`stop()` is `async` on purpose.** The underlying `CronJob.stop()` resolves only once an in-flight tick finishes. Awaiting it stops a replacement job from starting while the old handler still runs.
+- **`modifyCronTime()` reschedules in place.** It builds a new `CronTime`, calls `instance.setTime(...)`, and updates the stored `cronTime`. The same `CronJob` keeps running - it just fires on the new schedule.
+- **`duplicate()` clones configuration, not state.** The new instance shares `onTick`, `onCompleted`, `autoStart`, `tz`, and `errorHandler`, with a different `cronTime`. Stopping or modifying one instance never touches the other.
+- **`instance` is the raw `CronJob`.** Reach it for anything the wrapper skips - `isActive`, `lastDate()`, `fireOnTick()`. It comes from the [`cron`](https://github.com/kelektiv/node-cron) package, an optional peer dependency (`^4.3.3`).
 
 **`ICronHelperOptions`**
 
@@ -61,7 +62,7 @@ job.start();
 
 ### Reschedule at runtime
 
-`modifyCronTime()` swaps the cron pattern without recreating the job. Set `shouldFireOnTick: true` to fire once immediately after the change (fire-and-forget - errors are logged, not thrown).
+`modifyCronTime()` swaps the cron pattern without recreating the job. Set `shouldFireOnTick: true` to fire once immediately after the change. That fire is fire-and-forget - errors are logged, not thrown.
 
 ```typescript
 job.modifyCronTime({ cronTime: '0 */10 * * * *', shouldFireOnTick: true });

package/content/extensions/helpers/crypto/index.md

@@ -25,14 +25,20 @@ const decrypted = aes.decrypt({ message: encrypted, secret });
 // => 'This is a secret message.'
 ```
 
-`RSA` and `ECDH` follow the same `withAlgorithm()` factory + `encrypt`/`decrypt` shape - only the secret type and speed/message-size trade-offs differ.
+`RSA` and `ECDH` follow the same `withAlgorithm()` factory + `encrypt`/`decrypt` shape. Only the secret type and the speed/message-size trade-offs differ.
 
 ## How it works
 
-- **One factory pattern.** Every algorithm class exposes a static `withAlgorithm()` that returns an instance; there is no public constructor to call directly.
-- **`AES` and `RSA` share `BaseCryptoAlgorithm`.** It adds `normalizeSecretKey()` (pads/truncates a string secret to the algorithm's key size) and `getAlgorithmKeySize()` (parses the bit size out of the algorithm name, e.g. `256` from `aes-256-gcm`).
-- **`ECDH` extends the neutral `AbstractCryptoAlgorithm` directly.** It uses `CryptoKey` objects from the Web Crypto API (`crypto.subtle`), not string secrets, so it skips the string-normalization helpers entirely.
-- **Options objects, throw-by-default.** Every `encrypt`/`decrypt` takes `{ message, secret, opts? }`. On internal error, each throws unless `opts.doThrow: false`, in which case the original input is returned unchanged.
+- **One factory pattern.** Every algorithm class exposes a static `withAlgorithm()` that returns an instance. There is no public constructor to call directly.
+- **`ECDH` extends the neutral `AbstractCryptoAlgorithm` directly.** It uses `CryptoKey` objects from the Web Crypto API (`crypto.subtle`), not string secrets. It skips the string-normalization helpers entirely.
+- **Options objects, throw-by-default.** Every `encrypt`/`decrypt` takes `{ message, secret, opts? }`. On internal error, each throws by default. Pass `opts.doThrow: false` to get the original input back unchanged instead.
+
+**`AES` and `RSA` share `BaseCryptoAlgorithm`**, which adds two helpers:
+
+| Method | Does |
+|---|---|
+| `normalizeSecretKey()` | Pads or truncates a string secret to the algorithm's key size |
+| `getAlgorithmKeySize()` | Parses the bit size out of the algorithm name - `256` from `aes-256-gcm` |
 
 **Class comparison**
 
@@ -42,7 +48,9 @@ const decrypted = aes.decrypt({ message: encrypted, secret });
 | `RSA` | `BaseCryptoAlgorithm` | `string` (base64 DER key) | No | Public-key encryption, small payloads |
 | `ECDH` | `AbstractCryptoAlgorithm` | `CryptoKey` | Yes | Session key exchange with forward secrecy |
 
-`AES` supports two modes selected at construction: `aes-256-cbc` (plain block cipher) and `aes-256-gcm` (authenticated - detects tampering). Everything on this page uses the default options; the [Full reference](/extensions/helpers/crypto/reference) covers every option, the ECDH key-exchange flow, `IECDHEncryptedPayload`, and the standalone `hash()` utility that lives alongside these classes in the same package.
+`AES` supports two modes selected at construction: `aes-256-cbc` (plain block cipher) and `aes-256-gcm` (authenticated - detects tampering). Everything on this page uses the default options.
+
+See the [Full reference](/extensions/helpers/crypto/reference) for every option, the ECDH key-exchange flow, `IECDHEncryptedPayload`, and the standalone `hash()` utility.
 
 ## Common tasks
 
@@ -66,7 +74,7 @@ const decrypted = aes.decryptFile({ absolutePath: '/path/to/config.json.enc', se
 
 ### Generate an RSA key pair and encrypt with it
 
-Keys are DER-encoded (`SPKI` public, `PKCS8` private); base64-encode them to pass as the `secret` string.
+Keys are DER-encoded (`SPKI` public, `PKCS8` private). Base64-encode them to pass as the `secret` string.
 
 ```typescript
 import { RSA } from '@venizia/ignis-helpers';
@@ -81,7 +89,7 @@ const decrypted = rsa.decrypt({ message: encrypted, secret: privateKey.toString(
 
 ### Fail soft instead of throwing
 
-Pass `opts: { doThrow: false }` to get the original message back on error instead of an exception - useful when decryption failure should be a fallback path, not a crash.
+Pass `opts: { doThrow: false }` to get the original message back on error instead of an exception. Use this when a decryption failure should be a fallback path, not a crash.
 
 ```typescript
 const result = rsa.encrypt({ message: 'test', secret: 'invalid-key', opts: { doThrow: false } });

package/content/extensions/helpers/crypto/reference.md

@@ -80,16 +80,16 @@ interface ICryptoAlgorithm<
 }
 ```
 
-`AbstractCryptoAlgorithm` extends `BaseHelper` and declares `encrypt`/`decrypt` as abstract; it adds no behavior of its own. `BaseCryptoAlgorithm` is the concrete base for string-secret algorithms:
+`AbstractCryptoAlgorithm` extends `BaseHelper` and declares `encrypt`/`decrypt` as abstract. It adds no behavior of its own. `BaseCryptoAlgorithm` is the concrete base for string-secret algorithms:
 
 | Member | Signature | Description |
 |--------|-----------|--------------|
 | constructor | `(opts: { scope: string; algorithm: AlgorithmType })` | Sets `this.algorithm`, calls `validateAlgorithmName` |
 | `validateAlgorithmName` | `(opts: { algorithm: AlgorithmType }) => void` | Throws if `algorithm` is empty/falsy |
-| `normalizeSecretKey` | `(opts: { secret: string; length: number; padEnd?: string }) => string` | Truncates to `length` or right-pads with `padEnd` (default `'0'` - the digit character, since `DEFAULT_PAD_END` is `(0x00).toString()`, not a null byte) |
+| `normalizeSecretKey` | `(opts: { secret: string; length: number }) => Buffer` | Derives a `length`-byte key with PBKDF2-SHA256, 100,000 iterations. Results are memoised per secret |
 | `getAlgorithmKeySize` | `() => number` | Parses the bit size out of `this.algorithm` (e.g. `256` from `'aes-256-gcm'`), divides by 8 for byte length |
 
-`ECDH` extends `AbstractCryptoAlgorithm` directly - it does not inherit `normalizeSecretKey` or `getAlgorithmKeySize`, since its secrets are `CryptoKey` objects, not strings.
+`ECDH` extends `AbstractCryptoAlgorithm` directly. It does not inherit `normalizeSecretKey` or `getAlgorithmKeySize` - its secrets are `CryptoKey` objects, not strings.
 
 ## AES
 
@@ -119,7 +119,16 @@ encrypt(opts: { message: string; secret: string; opts?: IAESExtraOptions }): str
 | `outputEncoding` | `crypto.Encoding` | `'base64'` | Encoding of the returned ciphertext |
 | `doThrow` | `boolean` | `true` | If `false`, returns the original `message` instead of throwing on error |
 
-The secret is normalized via `normalizeSecretKey` to the algorithm's key size (32 bytes for both modes) before being used as the cipher key. The output layout is `IV [+ GCM auth tag] + ciphertext`, concatenated and encoded with `outputEncoding`.
+The secret is normalized via `normalizeSecretKey` to the algorithm's key size (32 bytes for both modes) before being used as the cipher key. The output is a self-describing envelope, concatenated and encoded with `outputEncoding`:
+
+```
+[version(1)][idLen(1)][id(idLen)][iv(16)][authTag(16, gcm only)][ciphertext]
+```
+
+The version byte is `0x01`. The key id is the entry `decrypt` looks up in a keyring - `'0'` when `secret` is a bare string.
+
+> [!WARNING] This envelope is not the pre-PBKDF2 one
+> Ciphertext written before this format started with the raw IV and derived its key by padding the secret. `decrypt` rejects it. Read that data with [`LegacyAES`](#legacyaes) instead.
 
 ```typescript
 import C from 'node:crypto';
@@ -139,20 +148,21 @@ const encrypted = aes.encrypt({
 ### `decrypt`
 
 ```typescript
-decrypt(opts: { message: string; secret: string; opts?: IAESExtraOptions }): string
+decrypt(opts: { message: string; secret: TAESSecret; opts?: IAESDecryptOptions }): string
 ```
 
+`decrypt` takes no `iv`. The envelope carries the one `encrypt` used, so passing another would be ignored - the option is absent from `IAESDecryptOptions` and supplying it is a compile error.
+
 | Option (`opts.opts`) | Type | Default | Description |
 |-----------------------|------|---------|-------------|
-| `iv` | `Buffer` | Extracted from the first 16 bytes of the decoded ciphertext | Initialization vector |
 | `inputEncoding` | `crypto.Encoding` | `'base64'` | Encoding of `message` |
 | `outputEncoding` | `crypto.Encoding` | `'utf-8'` | Encoding of the returned plaintext |
 | `doThrow` | `boolean` | `true` | If `false`, returns the original `message` instead of throwing on error |
 
-For `aes-256-gcm`, the next 16 bytes after the IV are read as the auth tag and passed to `setAuthTag` before the remaining bytes are treated as ciphertext.
+For `aes-256-gcm`, the next 16 bytes after the IV are read as the auth tag. That tag is passed to `setAuthTag` before the remaining bytes are treated as ciphertext.
 
 > [!WARNING]
-> Decrypting `aes-256-gcm` ciphertext with an `aes-256-cbc` instance (or vice versa) throws `Unsupported state or unable to authenticate data` - the two modes produce incompatible byte layouts. Always encrypt and decrypt with the same algorithm mode.
+> Decrypting `aes-256-gcm` ciphertext with an `aes-256-cbc` instance (or vice versa) throws `Unsupported state or unable to authenticate data`. The two modes produce incompatible byte layouts - always encrypt and decrypt with the same one.
 
 ### `encryptFile` / `decryptFile`
 
@@ -168,6 +178,66 @@ const encrypted = aes.encryptFile({ absolutePath: '/path/to/config.json', secret
 const decrypted = aes.decryptFile({ absolutePath: '/path/to/config.json.enc', secret: 'my-secret' });
 ```
 
+### Key rotation with a keyring
+
+`secret` accepts a list as well as a string. Encryption always uses the first entry; decryption looks up the id stamped in the envelope.
+
+```typescript
+const KEYRING = [
+  { id: '2', secret: process.env.APP_ENV_SECRET_V2! }, // current - everything new is written with this
+  { id: '1', secret: process.env.APP_ENV_SECRET_V1! }, // retired - still needed to read old rows
+];
+
+const fresh = aes.encrypt({ message: 'payload', secret: KEYRING }); // tagged id '2'
+const old = aes.decrypt({ message: rowFromLastYear, secret: KEYRING }); // resolved by its own id
+```
+
+Rotating means prepending a new entry, not re-encrypting the estate. Drop an old entry only once nothing carries its id any more - `decrypt` throws `No key in keyring matches ciphertext key id` when it cannot resolve one, and a keyring entry with an empty `secret` is refused by name rather than failing later inside OpenSSL.
+
+| `secret` shape | Encrypts with | Envelope key id |
+|---|---|---|
+| `'my-secret'` | that string | `'0'` |
+| `[{ id, secret }, ...]` | the FIRST entry | that entry's `id` |
+
+### LegacyAES
+
+`Source ->` [`packages/helpers/src/modules/crypto/algorithms/aes-legacy.algorithm.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/crypto/algorithms/aes-legacy.algorithm.ts)
+
+`LegacyAES` reproduces the pre-PBKDF2 behaviour exactly: the key is the secret padded with `'0'` (or truncated) to the algorithm's key size, and the output is `IV [+ GCM auth tag] + ciphertext` with no version header.
+
+Reach for it when you hold data written by an earlier IGNIS and do not want to re-encrypt it. The API mirrors `AES`, minus the keyring - `secret` is a plain string.
+
+```typescript
+import { LegacyAES } from '@venizia/ignis-helpers';
+
+const legacy = LegacyAES.withAlgorithm('aes-256-cbc');
+const plaintext = legacy.decrypt({ message: rowWrittenBeforeTheUpgrade, secret: APPLICATION_SECRET });
+```
+
+The two formats never cross-decrypt, by design. `AES` rejects a legacy envelope on its version byte; `LegacyAES` fails the auth tag on a new one. Nothing falls back silently in either direction.
+
+### IPayloadCipher - choosing the cipher a component uses
+
+A component that encrypts on your behalf takes `IPayloadCipher`, the string-in/string-out slice both classes satisfy:
+
+```typescript
+export interface IPayloadCipher {
+  encrypt(opts: { message: string; secret: string }): string;
+  decrypt(opts: { message: string; secret: string }): string;
+}
+```
+
+The bearer-token services accept it as `cipher`. An application holding tokens issued before the envelope change keeps them readable by handing over the legacy cipher instead of invalidating every session:
+
+```typescript
+new JWSTokenService({
+  jwtSecret,
+  getTokenExpiresFn,
+  applicationSecret,
+  cipher: LegacyAES.withAlgorithm('aes-256-cbc'), // omit it and you get AES
+});
+```
+
 ## RSA
 
 `Source ->` [`rsa.algorithm.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/crypto/algorithms/rsa.algorithm.ts)
@@ -188,7 +258,7 @@ generateDERKeyPair(opts?: { modulus: number }): { publicKey: Buffer; privateKey:
 |--------|------|---------|-------------|
 | `modulus` | `number` | `2048` | RSA modulus length in bits, passed to `crypto.generateKeyPairSync` |
 
-`publicKey` is exported as `{ type: 'spki', format: 'der' }`; `privateKey` as `{ type: 'pkcs8', format: 'der' }`. Both are raw `Buffer`s - base64-encode them (`.toString('base64')`) to pass as the `secret` string to `encrypt`/`decrypt`.
+`publicKey` is exported as `{ type: 'spki', format: 'der' }`, `privateKey` as `{ type: 'pkcs8', format: 'der' }`. Both are raw `Buffer`s. Base64-encode them (`.toString('base64')`) to pass as the `secret` string to `encrypt`/`decrypt`.
 
 ### `encrypt`
 
@@ -245,13 +315,15 @@ const decrypted = rsa.decrypt({
 
 ```typescript
 const ecdh = ECDH.withAlgorithm(); // curve is always 'ecdh-p256'
-const ecdhCustom = ECDH.withAlgorithm({ hkdfInfo: 'my-app-session-keys' });
+const ecdhCustom = ECDH.withAlgorithm({ algorithm: 'ecdh-p256', hkdfInfo: 'my-app-session-keys' });
 ```
 
-| Constructor option | Type | Default | Description |
-|---------------------|------|---------|-------------|
-| `algorithm` | `'ecdh-p256'` | `'ecdh-p256'` | Accepted but not branched on - the curve is always P-256 |
-| `hkdfInfo` | `string` | `'ignis-ecdh-p256-aes-256-gcm-v1'` | HKDF info string, UTF-8 encoded, used to isolate key derivation between application contexts |
+The options argument is optional. Pass one and `algorithm` becomes required, even though the constructor ignores it and always sets `'ecdh-p256'`.
+
+| Constructor option | Type | Required | Description |
+|---------------------|------|----------|-------------|
+| `algorithm` | `'ecdh-p256'` | Only when you pass an options object | Accepted but not branched on - the curve is always P-256 |
+| `hkdfInfo` | `string` | No - defaults to `'ignis-ecdh-p256-aes-256-gcm-v1'` | HKDF info string, UTF-8 encoded, used to isolate key derivation between application contexts |
 
 Different `hkdfInfo` values produce **incompatible** derived keys from the same ECDH shared secret.
 
@@ -277,7 +349,7 @@ deriveAESKey(opts: {
 }): Promise<{ key: CryptoKey; salt: string }>
 ```
 
-Derives shared bits via ECDH (`deriveBits`, 256 bits), imports them as an HKDF key, then derives a non-extractable AES-256-GCM `CryptoKey` via HKDF-SHA256 using `salt` and the instance's `hkdfInfo`.
+Derives shared bits via ECDH (`deriveBits`, 256 bits) and imports them as an HKDF key. It then derives a non-extractable AES-256-GCM `CryptoKey` via HKDF-SHA256, using `salt` and the instance's `hkdfInfo`.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -286,7 +358,7 @@ Derives shared bits via ECDH (`deriveBits`, 256 bits), imports them as an HKDF k
 | `salt` | `string` | A random 32-byte salt is generated | Base64-encoded HKDF salt. Omit to generate a new random one |
 
 > [!IMPORTANT]
-> Both parties must use the **same salt** to derive matching keys. The initiator omits `salt` (a random one is generated and returned); the responder must pass that returned `salt` back into their own `deriveAESKey` call. If both sides generate their own salt, they derive different, non-matching keys.
+> Both parties must use the **same salt** to derive matching keys. The initiator omits `salt` - a random one is generated and returned. The responder passes that returned `salt` back into their own `deriveAESKey` call. If both sides generate their own salt instead, the two keys never match.
 
 ### `encrypt` / `decrypt`
 
@@ -308,7 +380,7 @@ interface IECDHExtraOptions {
 }
 ```
 
-`opts.additionalData` (AAD) is authenticated but not encrypted - it binds the ciphertext to a context (channel ID, session ID) so the ciphertext cannot be replayed in a different context. Decrypt must supply the exact same `additionalData`; a mismatch (including an omitted value where one was used to encrypt) throws.
+`opts.additionalData` (AAD) is authenticated but not encrypted. It binds the ciphertext to a context - a channel ID, a session ID - so it can't be replayed into a different one. Decrypt must supply the exact same `additionalData`. A mismatch throws, and so does omitting it when encrypt supplied one.
 
 ### Complete flow
 
@@ -356,7 +428,7 @@ const decrypted = await ecdh.decrypt({ message: encrypted, secret: bobKey });
 
 `Source ->` [`crypto.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/crypto.utility.ts)
 
-`hash()` is a standalone function - not a class, not part of the `AES`/`RSA`/`ECDH` hierarchy - exported from `packages/helpers/src/utilities`, not `modules/crypto`. It is documented in full on the [Crypto Utility reference](/references/utilities/crypto).
+`hash()` is a standalone function, not a class - it isn't part of the `AES`/`RSA`/`ECDH` hierarchy. It's exported from `packages/helpers/src/utilities`, not `modules/crypto`. It is documented in full on the [Crypto Utility reference](/references/utilities/crypto).
 
 ```typescript
 function hash(
@@ -398,7 +470,7 @@ const sha256Hmac = hash('some text', { algorithm: 'SHA256', secret: 'a-secret-ke
 | `generateDERKeyPair(opts?)` | `RSA` | `{ publicKey: Buffer; privateKey: Buffer }` | Generate a DER-format key pair |
 | `encrypt(opts)` | `RSA` | `string` | Encrypt with a public key |
 | `decrypt(opts)` | `RSA` | `string` | Decrypt with a private key |
-| `ECDH.withAlgorithm(opts?)` | `ECDH` | `ECDH` | Create an ECDH instance with optional `hkdfInfo` |
+| `ECDH.withAlgorithm(opts?)` | `ECDH` | `ECDH` | Create an ECDH instance. Passing options requires `algorithm` alongside `hkdfInfo` |
 | `generateKeyPair()` | `ECDH` | `Promise<{ keyPair: CryptoKeyPair; publicKeyB64: string }>` | Generate a P-256 key pair |
 | `importPublicKey(opts)` | `ECDH` | `Promise<CryptoKey>` | Import a peer's base64 public key |
 | `deriveAESKey(opts)` | `ECDH` | `Promise<{ key: CryptoKey; salt: string }>` | Derive an AES-256-GCM key via HKDF |
@@ -422,13 +494,13 @@ const ecdh = ECDH.withAlgorithm();             // no parameter needed
 
 ### "[ECDH.fromBase64] Invalid base64 input"
 
-**Cause:** A value passed to an ECDH method (public key, salt, IV, or ciphertext) is not valid base64 - length not divisible by 4, or characters outside `A-Za-z0-9+/=`.
+**Cause:** A value passed to an ECDH method - a public key, salt, IV, or ciphertext - is not valid base64. Its length isn't divisible by 4, or it has characters outside `A-Za-z0-9+/=`.
 
-**Fix:** Pass base64 strings through exactly as produced by the methods that generated them (`publicKeyB64`, `salt`, `iv`, `ct`) - do not trim, re-encode, or modify them.
+**Fix:** Pass base64 strings through exactly as produced by the methods that generated them (`publicKeyB64`, `salt`, `iv`, `ct`). Do not trim, re-encode, or modify them.
 
 ### "Unsupported state or unable to authenticate data"
 
-**Cause:** The ciphertext or auth tag was modified in transit, or you decrypted `aes-256-gcm` ciphertext with a `aes-256-cbc` instance (or vice versa) - the two modes produce incompatible byte layouts.
+**Cause:** Either the ciphertext or auth tag was modified in transit, or encrypt and decrypt used different algorithm modes. The two modes produce incompatible byte layouts.
 
 **Fix:** Use the same algorithm mode for both encrypt and decrypt.
 
@@ -436,11 +508,11 @@ const ecdh = ECDH.withAlgorithm();             // no parameter needed
 
 **Cause:** Each `deriveAESKey` call without a `salt` generates a new random 32-byte salt. If both sides generate their own, they derive different AES keys.
 
-**Fix:** The initiator calls `deriveAESKey` without `salt` and sends the returned `salt` to the responder; the responder passes that exact `salt` into their own `deriveAESKey` call.
+**Fix:** The initiator calls `deriveAESKey` without `salt` and sends the returned `salt` to the responder. The responder passes that exact `salt` into their own `deriveAESKey` call.
 
 ### SHA256 hash returns the original text instead of a hash
 
-**Cause:** `hash()` with `algorithm: 'SHA256'` requires `secret`; when `secret` is `undefined` it short-circuits and returns `text` unchanged.
+**Cause:** `hash()` with `algorithm: 'SHA256'` requires `secret`. When `secret` is `undefined`, it short-circuits and returns `text` unchanged.
 
 **Fix:**
 

package/content/extensions/helpers/env/index.md

@@ -6,7 +6,7 @@ difficulty: beginner
 
 # Environment
 
-`applicationEnvironment` is a singleton that filters `process.env` down to your app's prefix and gives typed access to it; `Environment` reads the current deployment stage from `NODE_ENV`.
+`applicationEnvironment` is a singleton that filters `process.env` down to your app's prefix, and gives typed access to it. `Environment` reads the current deployment stage from `NODE_ENV`.
 
 ## In one example
 
@@ -17,14 +17,18 @@ const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
 const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', { defaultValue: 5000 });
 ```
 
-The singleton is created once at module load, reading only keys that start with `APP_ENV` (the default prefix) from `process.env`. `Envs` is an exported alias for the same instance.
+The singleton is created once at module load. It reads only keys that start with `APP_ENV` (the default prefix) from `process.env`. `Envs` is an exported alias for the same instance.
 
 ## How it works
 
-- **Construction filters by prefix.** `new ApplicationEnvironment({ prefix, envs })` copies only the keys of `envs` that start with `prefix` into an internal map - everything else is invisible to `get()`. The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` and `process.env`.
-- **`get()` takes an options object, not a positional default.** The signature is `get<ReturnType, BeforeTransformType = unknown>(key, opts?: { defaultValue?, transform? })`. Without `transform`, it returns the raw value (still a `string`) or `defaultValue` when the key is missing. With `transform`, it calls `transform(rawValue)` and falls back to `defaultValue` if that returns `undefined` or `null`.
-- **`get<T>()` is a type cast without `transform`, not a runtime conversion.** Every `process.env` value is a `string`; asking for `get<number>('APP_ENV_PORT')` still returns a string at runtime unless you pass `transform: Number`.
-- **Stage detection is separate from the singleton.** `Environment.current` reads `process.env.NODE_ENV` directly (falling back to `'development'` when unset); `Environment.is({ name })` compares against it. `ApplicationEnvironment.isDevelopment()` is narrower - it checks `NODE_ENV === 'development'` exactly, so the `'dev'` alias returns `false` there even though it counts as a development stage everywhere else.
+- **Construction filters by prefix.** `new ApplicationEnvironment({ prefix, envs })` copies only the keys of `envs` that start with `prefix` into an internal map. Everything else stays invisible to `get()`. The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` and `process.env`.
+- **`get()` takes an options object, not a positional default.** The signature is `get<ReturnType, BeforeTransformType = unknown>(key, opts?: { defaultValue?, transform? })`.
+- **Without `transform`,** `get()` returns the raw value - still a `string` - or `defaultValue` when the key is missing.
+- **With `transform`,** `get()` calls `transform(rawValue)`. It falls back to `defaultValue` only if that call returns `undefined` or `null`.
+- **`get<T>()` is a type cast, not a runtime conversion, unless you pass `transform`.** Every `process.env` value is a `string`. Asking for `get<number>('APP_ENV_PORT')` still returns a string at runtime, unless you also pass `transform: Number`.
+- **Stage detection is separate from the singleton.** `Environment.current` reads `process.env.NODE_ENV` directly. It falls back to `'development'` when `NODE_ENV` is unset.
+- **`Environment.is({ name })` compares a name against `Environment.current`.**
+- **`ApplicationEnvironment.isDevelopment()` is narrower.** It checks `NODE_ENV === 'development'` exactly. The `'dev'` alias fails that check, even though `dev` counts as a development stage everywhere else in IGNIS.
 
 **Deployment stages** (`Environment.*`)
 
@@ -41,7 +45,7 @@ The singleton is created once at module load, reading only keys that start with
 | `STAGING` | `'staging'` | no |
 | `PRODUCTION` | `'production'` | no |
 
-All ten stages are in `Environment.COMMON_ENVS`, which the Logger uses to decide whether `DEBUG=true` is honored. The five marked above are `Environment.DEVELOPMENT_ENVS` - the set IGNIS's error handler consults to decide whether a response may carry a stack trace or a raw driver message. The rule is fail-closed: `alpha`, `beta`, `uat`, `staging`, a typo'd name, and an unset `NODE_ENV` are all sanitized as production.
+All ten stages are in `Environment.COMMON_ENVS`, which the Logger uses to decide whether `DEBUG=true` is honored. The five marked above are `Environment.DEVELOPMENT_ENVS`. IGNIS's error handler consults this set to decide whether a response may carry a stack trace or a raw driver message. The rule is fail-closed: `alpha`, `beta`, `uat`, `staging`, a typo'd name, and an unset `NODE_ENV` are all sanitized as production.
 
 ## Common tasks
 
@@ -66,7 +70,7 @@ const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', {
 
 ### Set or merge variables at runtime
 
-`set()` writes a single key; `merge()` overwrites several at once - both bypass the prefix filter (they write directly, no `startsWith` check).
+`set()` writes a single key. `merge()` overwrites several keys at once. Both bypass the prefix filter - they write directly, with no `startsWith` check.
 
 ```typescript
 applicationEnvironment.set('APP_ENV_FEATURE_FLAG', 'enabled');
@@ -85,7 +89,7 @@ if (Environment.is({ name: Environment.STAGING })) {
 
 ### Use a custom prefix
 
-Set `APPLICATION_ENV_PREFIX` before the first import of `@venizia/ignis-helpers` - the singleton is constructed at module load, so a later change has no effect on it.
+Set `APPLICATION_ENV_PREFIX` before the first import of `@venizia/ignis-helpers`. The singleton is constructed at module load, so a later change has no effect on it.
 
 ```
 APPLICATION_ENV_PREFIX=MY_APP_ENV
@@ -100,7 +104,7 @@ const allKeys = applicationEnvironment.keys();
 ```
 
 > [!TIP]
-> `BaseApplication` validates every prefixed key at startup and throws on an empty value unless `ALLOW_EMPTY_ENV_VALUE` is truthy - see [Application](/guides/core-concepts/application/).
+> `BaseApplication` validates every prefixed key at startup and throws on an empty value, unless `ALLOW_EMPTY_ENV_VALUE` is truthy - see [Application](/guides/core-concepts/application/).
 
 ## See also