@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/best-practices/security-guidelines.md

@@ -20,17 +20,17 @@ APP_ENV_POSTGRES_PASSWORD=database_password_here
 
 **Generate strong secrets:**
 ```bash
-node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+bun -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"
 ```
 
 ### Redaction at Log Time
 
-Never hard-coding a secret is not enough on its own -- an options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
+Never hard-coding a secret is not enough on its own - an options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
 
 | Function | Use For | Behavior |
 |----------|---------|----------|
-| `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name (`password`, `token`, `apiKey`, `authorization`, HTTP header spellings like `x-api-key`/`cookie`/`proxy-authorization`, etc., case-insensitive) with `'[REDACTED]'` |
-| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section (`mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`); a value that doesn't parse as a URL is returned unchanged |
+| `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name with `'[REDACTED]'` |
+| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section (`mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`); a value that doesn't parse as a URL, or one with no password, is returned unchanged |
 
 ```typescript
 import { redactSecrets, redactUrlCredentials } from '@venizia/ignis-helpers';
@@ -39,7 +39,19 @@ this.logger.info('[connect] Options: %s', redactSecrets(connectionOptions));
 this.logger.info('[connect] Broker: %s', redactUrlCredentials(brokerUrl));
 ```
 
-These are the primitives the framework itself uses -- outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+`redactSecrets` matches on the **key name**, case-insensitively, at any depth:
+
+- Options-object spellings: `password`, `passphrase`, `secret`, `token`, `apiKey`, `privateKey`, `credentials`, `authorization`, `connectionString`, ...
+- Any `*_token` / `*Token` key: `access_token`, `refresh_token`, `vaultToken`, ...
+- Vault wire keys: `client_token`, `secret_id`, `role_id`
+- HTTP header spellings: `x-api-key`, `x-vault-token`, `cookie`, `set-cookie`, `proxy-authorization`, `www-authenticate`
+
+It also handles the shapes naive redaction breaks on: an `Error` is reprojected so its non-enumerable `message`/`stack` survive, cycles become `'[Circular]'`, and buffers/typed arrays are summarized as `[Binary N bytes]` instead of serialized.
+
+These are the primitives the framework itself uses - outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+
+> [!WARNING]
+> `APP_ENV_LOGGER_DO_REDACT=false` turns both functions into the identity function. It is a local-debugging kill-switch and must never be set in production. The check is fail-closed - only the literal string `false` disables redaction - and is read per call, so it can be flipped at runtime.
 
 ## 2. Input Validation
 
@@ -110,7 +122,7 @@ Configure model properties that should **never be returned** through repository
     hiddenProperties: ['password', 'apiSecret', 'internalToken'],
   },
 })
-export class User extends BasePostgresEntity<typeof User.schema> {
+export class User extends BaseRelationalEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),
@@ -131,7 +143,7 @@ export class User extends BasePostgresEntity<typeof User.schema> {
 
 ```typescript
 // For authentication - access password via connector
-const connector = userRepository.getConnector();
+const connector = userRepository.connector;
 const [user] = await connector
   .select({ id: User.schema.id, password: User.schema.password })
   .from(User.schema)
@@ -339,7 +351,7 @@ const redisHelper = new RedisSingleHelper({
   name: 'rate-limiter',
   host: process.env.APP_ENV_REDIS_HOST ?? 'localhost',
   port: process.env.APP_ENV_REDIS_PORT ?? '6379',
-  password: process.env.APP_ENV_REDIS_PASSWORD,
+  password: process.env.APP_ENV_REDIS_PASSWORD ?? '',
 });
 
 const distributedRateLimiter = async (opts: { key: string; max: number; windowSeconds: number }) => {
@@ -462,6 +474,18 @@ export class AuthService extends BaseService {
 }
 ```
 
+### Error Responses Are Hardened in Production
+
+The global error handler decides what a client sees by environment, and it is **fail-closed**: an unset or unrecognized `NODE_ENV` is treated as production. Only `NODE_ENV` values in the development set relax it.
+
+| In production | Behavior |
+|---|---|
+| Unexpected errors | Replaced with a generic `"Internal Server Error"` - raw text may carry SQL, schema names or connection details |
+| Database constraint errors (400) | Base message only; the driver's `Detail:` (which echoes row values like emails), `Table:` and `Constraint:` are stripped |
+| `details.stack` / `details.cause` | Omitted |
+
+Deliberate `getError` messages are always returned verbatim, in every environment - so never put internal detail in one. Use `requestId` plus the server log to diagnose what the response no longer shows. See [Error Handling](./error-handling#_5-error-response-format).
+
 **Events to Log:**
 - Failed login attempts
 - Successful logins
@@ -471,7 +495,7 @@ export class AuthService extends BaseService {
 - Admin actions
 
 > [!NOTE]
-> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw -- see [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
+> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw - see [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
 
 ## Security Checklist
 
@@ -489,6 +513,8 @@ Before deploying to production, verify:
 | **Dependencies** | No known vulnerabilities (`bun audit`) |
 | **HTTPS** | TLS configured for production |
 | **Hidden Data** | Sensitive fields use `hiddenProperties` |
+| **Redaction** | `APP_ENV_LOGGER_DO_REDACT` is unset (never `false`) |
+| **Error Leakage** | `NODE_ENV` set to a production value so responses are sanitized |
 
 ## See Also
 

package/content/best-practices/testing-strategies.md

@@ -102,8 +102,8 @@ bun test
 # Run specific test file
 bun test src/__tests__/user.service.test.ts
 
-# Run tests matching pattern
-bun test --grep "UserService"
+# Run tests whose name matches a pattern
+bun test -t "UserService"
 
 # Watch mode
 bun test --watch
@@ -410,6 +410,11 @@ describe('UserController E2E', () => {
       });
 
       expect(response.status).toBe(409);
+
+      // Error responses carry one message shape: { text, code, args }.
+      // There is no flat top-level messageCode - branch on normalized.code.
+      const body = await response.json();
+      expect(body.normalized.code).toBeDefined();
     });
   });
 

package/content/best-practices/troubleshooting-tips.md

@@ -50,11 +50,9 @@ This prints all registered routes on startup.
 
 **Debug bindings:**
 ```typescript
-// In postConfigure() method
-async postConfigure(): Promise<void> {
-  this.logger.info('Available bindings: %s',
-    Array.from(this.bindings.keys())
-  );
+// In your Application class - `bindings` is protected on the container it extends
+override async postConfigure(): Promise<void> {
+  this.logger.info('[postConfigure] Available bindings: %j', Array.from(this.bindings.keys()));
 }
 ```
 
@@ -77,16 +75,21 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \
 
 **Enable detailed logging:**
 ```bash
-# Enable debug mode via environment variable
+# `debug` is the only gated level - it is dropped unless DEBUG is set
 DEBUG=true
+
+# File logging is OPT-IN. Without this, logs go to console/dgram only
+APP_ENV_LOGGER_FOLDER_PATH=./logs
 ```
 
 **Use method-scoped logging with `.for()`:**
 ```typescript
+import { ApplicationLogger, type ILogger } from '@venizia/ignis-helpers';
+
 class UserService {
-  private logger = Logger.get('UserService');
+  private logger: ILogger = ApplicationLogger.get('UserService');
 
-  async createUser(data: CreateUserDto) {
+  async createUser(data: TCreateUserRequest) {
     this.logger.for('createUser').info('Creating user: %j', data);
     // Output: [UserService-createUser] Creating user: {...}
 
@@ -102,16 +105,19 @@ class UserService {
 }
 ```
 
+Annotate against `ILogger`, never a concrete provider class. Acquire a logger via `BaseHelper.logger` (inside any helper, service, controller or repository), `ApplicationLogger.get('Scope')`, or `LoggerFactory.getLogger(['A', 'B'])`.
+
 **Common debugging commands:**
 ```bash
-# View application logs
-tail -f logs/app.log
+# View application logs - the rotating files are <APP_ENV_APPLICATION_NAME>-info-<date>.log
+# and -error-<date>.log inside APP_ENV_LOGGER_FOLDER_PATH
+tail -f "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log
 
-# Check TypeScript compilation errors
-bun run build
+# Check TypeScript compilation errors (from the repo root)
+make core
 
 # Validate environment variables
-cat .env | grep APP_ENV
+grep APP_ENV .env
 ```
 
 **Useful debugging patterns:**
@@ -144,10 +150,10 @@ async getUser(c: Context) {
 **Filtering logs by request:**
 ```bash
 # Find all logs for a specific request
-grep "abc123" logs/app.log
+grep "abc123" "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log
 
 # Extract request timing
-grep "\[abc123\]" logs/app.log | grep "Took:"
+grep "\[abc123\]" "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log | grep "Took:"
 ```
 
 **Why this matters:**
@@ -159,12 +165,16 @@ grep "\[abc123\]" logs/app.log | grep "Took:"
 
 When Zod validation fails, IGNIS returns a structured error response. Understanding this format helps debug client-side issues.
 
-**Error response structure** (top-level `message`/`messageCode` come from the first issue; the fallback message is `ValidationError`):
+**Error response structure** (`message`/`normalized.code` come from the first issue; the fallback message is `ValidationError`):
 ```json
 {
   "statusCode": 422,
   "message": "Invalid email address",
-  "messageCode": "invalid_format",
+  "normalized": {
+    "text": "Invalid email address",
+    "code": "invalid_format",
+    "args": {}
+  },
   "requestId": "abc123",
   "details": {
     "url": "http://localhost:3000/api/users",