@zyno-io/ts-server-foundation 26.712.36

package/docs/content/authentication.md

@@ -0,0 +1,213 @@
+# Authentication
+
+TSF includes JWT helpers, request authentication utilities, entity auth middleware, HTTP Basic auth middleware, password hashing, and reset tokens.
+
+## JWT Configuration
+
+Generated JWTs use HS256 when an HMAC secret is configured and EdDSA when `AUTH_JWT_ED_SECRET` is configured. Exactly one secret source may be configured: `AUTH_JWT_SECRET`, `AUTH_JWT_SECRET_B64`, or `AUTH_JWT_ED_SECRET`. Conflicts are rejected when JWT signing or configured-key verification first resolves the key.
+
+| Config key                 | Description                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `AUTH_JWT_SECRET`          | Plain string HMAC secret. Mutually exclusive with the base64 and Ed25519 secrets.                                              |
+| `AUTH_JWT_SECRET_B64`      | Base64-encoded HMAC secret. Mutually exclusive with the plain and Ed25519 secrets.                                             |
+| `AUTH_JWT_ED_SECRET`       | Base64 DER or PEM PKCS#8 Ed25519 private key. Mutually exclusive with both HMAC secrets.                                       |
+| `AUTH_JWT_ISSUER`          | Default issuer.                                                                                                                |
+| `AUTH_JWT_EXPIRATION_MINS` | Default token lifetime. Defaults to 60 minutes.                                                                                |
+| `AUTH_JWT_COOKIE_NAME`     | Cookie name. Defaults to `jwt`.                                                                                                |
+| `AUTH_JWT_ENABLE_VERIFY`   | When false, request processing only decodes tokens; signatures, required claims, and expiry are not checked. Defaults to true. |
+
+::: danger Verification must stay enabled at trust boundaries
+Setting `AUTH_JWT_ENABLE_VERIFY=false` makes `JWT.process()`, request helpers, and `ParsedJwt` injection trust any decodable token, including one with a forged signature, missing claims, or an expired `exp`. `JWT.decode()` has the same validation bypass regardless of configuration. Use either only for explicitly untrusted inspection or tightly controlled compatibility work, never to authorize a request.
+:::
+
+## Generating JWTs
+
+```ts
+import { JWT } from '@zyno-io/ts-server-foundation';
+
+const token = await JWT.generate({
+    subject: String(user.id),
+    payload: { role: user.role }
+});
+
+await JWT.generateCookie({ subject: String(user.id) }, response, {
+    sameSite: 'Lax',
+    secure: true
+});
+
+await JWT.clearCookie(response);
+```
+
+JWT cookies default to the configured `AUTH_JWT_COOKIE_NAME` or `jwt`, with `Path=/`, `HttpOnly`, `Secure`, and `SameSite=Lax`. Pass `secure: false` only when the transport is intentionally not HTTPS. `clearCookie()` uses the same attributes and an expiration in 1970, so pass matching `domain`, `sameSite`, and `secure` options when clearing a customized cookie.
+
+Generation options:
+
+| Option       | Description                                |
+| ------------ | ------------------------------------------ |
+| `id`         | Optional JWT ID stored as `jti`.           |
+| `issuer`     | Overrides `AUTH_JWT_ISSUER`.               |
+| `audience`   | String or string array audience.           |
+| `subject`    | Required subject.                          |
+| `expiresAt`  | Expiration as `Date` or Unix milliseconds. |
+| `expiryMins` | Relative expiration in minutes.            |
+| `payload`    | Extra application claims.                  |
+
+## Verifying And Decoding
+
+```ts
+const result = await JWT.verify<{ role: string }>(token);
+
+if (result.isValid) {
+    result.subject;
+    result.payload.role;
+    result.expiresAt;
+} else {
+    result.isDecodable;
+    result.isSignatureValid;
+    result.isPayloadValid;
+    result.isNotExpired;
+}
+```
+
+Helpers:
+
+| Helper                              | Description                                                                 |
+| ----------------------------------- | --------------------------------------------------------------------------- |
+| `JWT.verify(token, key?, options?)` | Verifies signatures and standard claims with an explicit or configured key. |
+| `JWT.decode(token)`                 | Decodes without validating signatures, required claims, or expiry.          |
+| `JWT.process(token)`                | Fully verifies or only decodes according to `AUTH_JWT_ENABLE_VERIFY`.       |
+| `JWT.processWithRequest(request)`   | Reads Bearer token or JWT cookie from a request.                            |
+| `JWT.createVerifier(options)`       | Returns a reusable async verifier.                                          |
+
+`processWithRequest()` checks `Authorization: Bearer <token>` first, then the configured JWT cookie.
+
+Verification requires `iss`, non-empty `sub`, numeric `iat`, and numeric `exp`; expiration and any requested issuer/audience are enforced. `aud` is optional unless a verifier specifies an audience. Generated tokens always include `iss`, `sub`, `iat`, and `exp`.
+
+`JWT.generate()` pins signing to HS256 or EdDSA from configuration. `JWT.verify()` and `JWT.createVerifier()` restrict verification to one algorithm only when their `algorithm` option is supplied. With no explicit algorithm, `fast-jwt` validates the token using the supplied/configured key and its compatible algorithms. An unknown explicit algorithm returns an invalid result instead of falling back. For an EdDSA verifier created with an explicit public key, pass `algorithm: 'EdDSA'` so TSF normalizes a bare base64 SPKI key correctly.
+
+Bearer precedence applies once the header matches `Bearer <non-whitespace-token>`. If that selected token is invalid, TSF returns the invalid result and does not fall back to a valid cookie. A missing or malformed/non-Bearer authorization header still allows cookie lookup.
+
+`JWT.decode()` produces a `ParsedJwt` from decodable payload fields but does not prove their type, presence, signature, or freshness. Its `isValid: true` means decoding succeeded, not that the token is trustworthy.
+
+## Controller Injection
+
+Controllers can request `ParsedJwt<T>` directly. The parameter is required unless it is optional.
+
+```ts
+import { http, ParsedJwt } from '@zyno-io/ts-server-foundation';
+
+interface SessionClaims {
+    role: string;
+}
+
+@http.controller('/session')
+class SessionController {
+    @http.GET('/me')
+    async me(jwt: ParsedJwt<SessionClaims>) {
+        return { subject: jwt.subject, role: jwt.payload.role };
+    }
+}
+```
+
+With verification enabled, invalid or expired JWTs produce `HttpUnauthorizedError`; a missing required JWT always does. An optional `ParsedJwt` accepts absence, but a token that is present and invalid still produces `401`. When `AUTH_JWT_ENABLE_VERIFY=false`, any decodable token bypasses signature, claim, and expiry checks.
+
+## Request Helpers
+
+```ts
+import { resolveEntityFromRequestJwt, getSubjectFromRequestJwt, getJwtFromRequest } from '@zyno-io/ts-server-foundation';
+
+const jwt = await getJwtFromRequest(request);
+const userId = await getSubjectFromRequestJwt(request);
+const user = await resolveEntityFromRequestJwt(request, User);
+```
+
+JWT processing is cached per request.
+
+## Entity Auth Middleware
+
+`createAuthMiddleware(Entity)` creates a middleware class that requires a JWT subject and can optionally validate the resolved entity.
+
+```ts
+import {
+    createApp,
+    createAuthMiddleware,
+    resolveEntityFromRequestJwt,
+    http,
+    HttpRequest,
+    HttpUnauthorizedError
+} from '@zyno-io/ts-server-foundation';
+
+class UserAuthMiddleware extends createAuthMiddleware(User) {
+    async validateEntity(_request: HttpRequest, user: User) {
+        if (user.disabled || user.deletedAt) throw new HttpUnauthorizedError('Account is not active');
+    }
+}
+
+@http.controller('/account')
+class AccountController {
+    @(http.GET('/me').use(UserAuthMiddleware))
+    async me(request: HttpRequest) {
+        return await resolveEntityFromRequestJwt(request, User);
+    }
+}
+
+const app = createApp({
+    providers: [UserAuthMiddleware],
+    controllers: [AccountController]
+});
+```
+
+`handle()` always resolves and caches the subject for the request. If the generated middleware class does not define `validateEntity()`, it does not query the database; this is an authentication-presence/subject check only. When a hook is present, the middleware loads the entity with `getEntityOrUndefined()`, rejects a missing entity, caches the loaded entity for that request, and invokes the hook. Repeated middleware execution on the same request reuses the cached subject and entity, although the validation hook runs each time.
+
+## Custom Entity Resolvers
+
+`resolveEntityFromRequestJwt(contextOrRequest, Entity)` can be used as a custom parameter resolver helper. It throws unauthorized for missing non-optional route parameters.
+
+`createCachingParameterResolver(key, resolver)` wraps a route parameter resolver and caches its value per request.
+
+## HTTP Basic Auth
+
+```ts
+import { createBasicAuthMiddleware, http } from '@zyno-io/ts-server-foundation';
+
+const AdminBasicAuth = createBasicAuthMiddleware('admin');
+
+@http.controller('/admin')
+class AdminController {
+    @(http.GET('/stats').use(AdminBasicAuth))
+    async stats() {
+        return { ok: true };
+    }
+}
+```
+
+The password must match `AUTH_BASIC_SECRET`. When an expected username is provided, the username must match too.
+
+## Password Hashing
+
+```ts
+import { Auth } from '@zyno-io/ts-server-foundation';
+
+const hash = await Auth.hashPassword('secret');
+const valid = await Auth.verifyHash('secret', hash);
+```
+
+New passwords are hashed with `scrypt` and a random salt. Encoded hashes use the format `scrypt$<salt>$<hash>`. `verifyHash()` also accepts existing bcrypt hashes (including the common `$2y$` variant), which supports migrations from bcrypt-backed applications without rehashing every password at once.
+
+## Reset Tokens
+
+```ts
+const reset = await Auth.generateResetToken({ userId: user.id });
+const decoded = await Auth.decodeResetToken<{ userId: number }>(reset.token);
+```
+
+Reset tokens use three base64url-safe parts: a base36 Unix timestamp in seconds, 16 random bytes, and the JSON payload. `generationTime` is returned in Unix milliseconds at whole-second precision. The payload is encoded, not encrypted or signed; use the random-byte `verifier` for server-side validation and enforce expiration in application code. `decodeResetToken()` validates the token structure and payload but does not check a stored verifier or an expiry policy.
+
+The returned `ResetToken<T>` contains:
+
+| Field            | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `token`          | Encoded token string.                                 |
+| `data`           | JSON-serializable payload.                            |
+| `generationTime` | Unix timestamp in milliseconds.                       |
+| `verifier`       | SHA-256 verifier derived from the random token bytes. |

package/docs/content/cli.md

@@ -0,0 +1,214 @@
+# CLI Tools
+
+TSF ships application scaffolding, compiler setup, development orchestration, tests, migrations, OpenAPI generation, and protobuf generation as package binaries. All TSF-owned commands use the `tsf` prefix.
+
+## Package Binaries
+
+| Binary | Description |
+| --- | --- |
+| `tsf` | Umbrella CLI for `create-app`, `test`, and `gen-proto`. |
+| `ts-server-foundation` | Alias for the umbrella CLI. |
+| `tsf-create-app` | Scaffold a new app from `template-app`. |
+| `tsf-dev` | Build/watch/run/test and application development workflows. |
+| `tsf-test` | Compile-output-aware Node test runner. |
+| `tsf-migrate` | Create, run, reset, and charset migration commands. |
+| `tsf-gen-proto` | Generate TypeScript protobuf codecs through `ts-proto`. |
+| `tsf-install` | Configure the supported TypeScript 7/`ttsc` compiler and TSF transform. |
+| `tsf-update` | Reserved update command; currently reports that no automatic updater is available. |
+
+## Umbrella Command
+
+`tsf` forwards to the matching standalone binary:
+
+```bash
+tsf create-app <package-name> [path]
+tsf test [node-test-options] [test-files-or-dirs...]
+tsf gen-proto <proto-file-or-dir> <output-dir> [options]
+```
+
+The standalone names remain useful in package scripts and when a command needs to be invoked directly.
+
+## App Scaffolding
+
+```bash
+npx @zyno-io/ts-server-foundation create-app my-api
+npx @zyno-io/ts-server-foundation create-app @myorg/my-api
+tsf-create-app @myorg/my-api ./services/api
+```
+
+The first argument must be a valid npm package name. The output path defaults to the unscoped package name, so `@myorg/my-api` creates `./my-api/`. Scaffolding refuses to overwrite an existing directory.
+
+The command copies `template-app` and fills in:
+
+- package and database names
+- the Redis prefix
+- the TSF package version
+- the supported `typescript` and `ttsc` versions
+- template `.gitignore` and other `.tmpl` file names
+
+When scaffolding from an unpublished `0.0.0-dev` checkout, the generated TSF dependency uses `*`; published versions use a compatible `^<version>` range. The generated app prints its install and development commands when complete.
+
+## Development Workflow
+
+```bash
+tsf-dev <command> [options]
+```
+
+All commands resolve the project root from the working directory. `-p <file>` and `--tsconfig <file>` select a TypeScript config where applicable.
+
+| Command | Behavior |
+| --- | --- |
+| `clean` | Removes `dist/`. |
+| `build [--watch]` | Ensures compiler setup, cleans when needed, and compiles with the supported `ttsc`. |
+| `run [--debug] [script] -- <app-command>` | Ensures a watch build, then starts Node with source maps, file watching, and the requested app command. |
+| `test [--debug]` | Builds the test config and delegates to `tsf-test`. |
+| `migrate [--debug]` | Builds, then invokes the package entrypoint with `migrate:run`. |
+| `migrate:create [--debug]` | Builds, then delegates to `tsf-migrate create`. |
+| `migrate:reset [--debug]` | Builds, then delegates to `tsf-migrate reset`. |
+| `migrate:charset [--debug]` | Builds, then delegates to `tsf-migrate charset`. |
+| `openapi:generate` | Builds, then invokes the package entrypoint with `openapi:generate`. |
+
+### Build And Watch
+
+```bash
+tsf-dev clean
+tsf-dev build
+tsf-dev build --watch
+tsf-dev build -p tsconfig.test.json
+```
+
+`tsf-dev build` records a fingerprint of compiler inputs and outputs under `dist/`. A later command reuses a fresh build; changing TypeScript/JavaScript sources, JSON configuration, or the lockfile invalidates it. Watch mode uses the selected tsconfig's files/include/exclude/outDir rules and ignores generated and dependency directories.
+
+`tsf-install` runs before normal development builds so the project uses the package-supported compiler versions and transform. Test builds are the exception: `tsf-dev test` compiles directly and does not mutate package/compiler setup during a test run.
+
+### Run
+
+```bash
+tsf-dev run -- server:start
+tsf-dev run -- worker:start
+tsf-dev run dist/custom-entry.js -- maintenance:run
+tsf-dev run --debug -- server:start
+```
+
+Arguments before `--` belong to `tsf-dev`; arguments after it are passed to the application. The script defaults to `.`, which asks Node to load the package `main`. An explicit app command is required by scaffolded applications.
+
+The first `tsf-dev run` for a project owns the compiler watcher. Concurrent run processes share its build-ready state instead of starting duplicate compilers. If an existing output fingerprint is fresh, the watcher waits for an input change before compiling again.
+
+Normal run mode enables the Node inspector. `--debug` changes it to `--inspect-brk`. When `PORT` is set, the inspector uses `PORT + 1000`; otherwise Node selects/reports its inspector port.
+
+### Tests
+
+```bash
+tsf-dev test
+tsf-dev test tests/http.spec.ts
+tsf-dev test --test-name-pattern='uploads'
+tsf-dev test --debug tests/http.spec.ts
+```
+
+The command selects `tsconfig.test.json` when present, otherwise `tsconfig.json`, compiles if needed, and forwards remaining Node test flags and file/directory selectors to `tsf-test`. Debug mode starts with `--inspect-brk=9268`.
+
+## Test Runner
+
+```bash
+tsf-test [node-test-options] [test-files-or-dirs...]
+```
+
+`tsf-test` sets `APP_ENV=test` and `TZ=UTC`, maps source selectors such as `tests/http.spec.ts` to compiled files under `dist/tests/`, and runs Node with source maps, a 180-second per-test timeout, and forced process exit. With no selector it discovers compiled `*.spec.js` files below `dist/tests`.
+
+If `dist/tests/shared/globalSetup.js` exists, its optional `setup()` runs before the test subprocess and `teardown()` runs after it. See [Testing](./testing.md#global-setup-and-module-state).
+
+When MySQL test configuration is available and savepoints are allowed, the runner starts a shared MySQL session manager. Its pool size follows `--test-concurrency` or defaults to available parallelism minus one. Control it with:
+
+| Environment key | Behavior |
+| --- | --- |
+| `TSF_TEST_MYSQL_SESSION_MANAGER=0` | Disable the shared manager. |
+| `TSF_TEST_MYSQL_SESSION_MANAGER=1` | Force the manager on; missing MySQL configuration still fails startup. |
+| `TSF_TEST_ALLOW_SAVEPOINTS=0` | Disable savepoint-backed facade reuse globally. |
+| `TEST_RUN_TS=<value>` | Reuse an explicit run identifier for generated test database names. |
+
+Database readiness is checked only by database-enabled facades, not as a runner-wide preflight.
+
+## Migrations
+
+Use `tsf-dev migrate*` during development when source must be compiled first. Use `tsf-migrate` directly when compiled application output already exists.
+
+```bash
+tsf-migrate create [options]
+tsf-migrate run [options]
+tsf-migrate reset [options]
+tsf-migrate charset [charset collation] [options]
+```
+
+| Command | Behavior |
+| --- | --- |
+| `create` | Diffs reflected entity schemas against the live database and writes a raw-SQL migration when changes exist. `create:raw` is an alias. |
+| `run` | Loads compiled migrations and runs migrations not recorded in `_migrations`. |
+| `reset` | Removes source migration files and creates one base migration from registered entities. |
+| `charset` | Standardizes the MySQL database and table charset/collation; PostgreSQL reports a skipped operation. |
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `--app <path>` | Compiled app module. Defaults to `dist/src/app.js`. |
+| `--description <text>`, `-d <text>` | Migration description. Defaults to `auto_migration`. |
+| `--migrations-dir <path>` | Source migration directory. Defaults to `src/migrations`. |
+| `--pg-schema <schema>` | PostgreSQL schema used for diff/reset. Defaults to the database reader's schema. |
+| `--table <name>` | Limits a create diff to one table. Repeatable. |
+| `--tables <a,b>` | Limits a create diff to a comma-separated table list. |
+
+Option values may also use `--name=value`. Table names are de-duplicated; empty values and unknown options fail rather than being ignored.
+
+The app module may export an `App` instance or zero-argument app factory as `app` or `default`. As a compatibility fallback, a zero-argument named export matching `create*App` is also accepted. The CLI resolves `BaseDatabase` through that app and closes the database driver when the command completes.
+
+For `run`, a source path containing `src` maps to the equivalent compiled `dist` path. Pass a path already containing `dist` to load it directly. See [Migrations](./migrations.md) for migration file format, directory loading, schema diffs, reset behavior, and charset defaults.
+
+Migration debug mode under `tsf-dev` uses `--inspect-brk=9226`.
+
+## OpenAPI Generation
+
+```bash
+tsf-dev openapi:generate
+tsf-dev openapi:generate -p tsconfig.json
+```
+
+This builds the project, then runs `node . openapi:generate`. The built-in `App.run()` command serializes registered routes to `openapi.yaml` without binding the HTTP server. The application package must expose its compiled entrypoint through `package.json#main`, as scaffolded TSF apps do.
+
+Runtime OpenAPI routes and serializer options are documented in [OpenAPI](./openapi.md).
+
+## Proto Generation
+
+```bash
+tsf-gen-proto resources/proto/service.proto src/generated/proto
+tsf-gen-proto resources/proto src/generated/proto --only-types
+```
+
+The input may be one `.proto` file or a directory. Directory mode generates every direct `.proto` child and does not recurse. The output directory is created when necessary.
+
+| Flag | Effect |
+| --- | --- |
+| `--only-types` | Passes `onlyTypes=true` to `ts-proto`. |
+| `--use-date` | Uses `Date` for `google.protobuf.Timestamp`; the default is `useDate=false`. |
+| `--use-map-type` | Uses ES `Map` for protobuf maps; the default is `useMapType=false`. |
+
+Generation always enables `esModuleInterop` and disables generated service clients because SRPC uses the message codecs directly. The command uses `PROTOC` when set, then the package's `protoc` binary, then a `protoc` executable on `PATH`. It resolves `ts-proto` from the app or TSF package.
+
+## Compiler Installation
+
+`tsf-install` prepares an app for TSF's reflected metadata compiler. It:
+
+- adds itself to `postinstall` without replacing an existing postinstall command
+- moves the supported `typescript` and `ttsc` versions into `devDependencies`
+- keeps TSF/compiler versions aligned in other packages in the same workspace when those dependencies are present
+- finds `tsconfig*.json` files outside generated/dependency directories
+- adds the TSF transform to `compilerOptions.plugins`
+- sets top-level `reflection: true`
+- avoids duplicating the plugin in configs that extend an already configured local base config
+
+When compiler dependencies change outside a package-manager lifecycle, it detects Yarn, npm, pnpm, or Bun and refreshes the install/lockfile. During `postinstall`, it reports that another install is needed instead of recursively starting the package manager.
+
+The generated app registers `tsf-install` as `postinstall`, so normal dependency installation keeps compiler setup aligned. See [Getting Started: TypeScript Configuration](./getting-started.md#typescript-configuration) for the resulting config.
+
+## Update Command
+
+`tsf-update` is included as a reserved compatibility binary but does not currently modify the project. Dependency updates should be performed through the package manager, followed by `tsf-install` when compiler configuration must be refreshed.

package/docs/content/configuration.md

@@ -0,0 +1,191 @@
+# Configuration
+
+Configuration is loaded by reflecting a config class. `createApp()` defaults to `BaseAppConfig`, but apps usually extend it.
+
+```ts
+import { BaseAppConfig, Env } from '@zyno-io/ts-server-foundation';
+
+class AppConfig extends BaseAppConfig {
+    STRIPE_KEY_SECRET!: string;
+    MAX_UPLOAD_BYTES = 10_000_000;
+}
+
+Env.APP_ENV = 'test';
+```
+
+## Loading Order
+
+`ConfigLoader` creates the config class, applies `defaultConfig`, then loads env files and `Env` through `@zyno-io/config`.
+
+Loaded string values receive configuration-specific primitive coercion for reflected numbers, booleans, and matching literals. The completed config instance is then reflected-validated, so required fields, unions, constraints, custom validators, and invalid numeric values such as `NaN` fail application startup. Configuration loading does not run the general reflected deserializer registry: transforms such as `TrimmedString` and phone normalization are not applied automatically.
+
+Env files are read from the process cwd:
+
+1. `.env`
+2. `.env.local`
+3. `.env.development` and `.env.development.local` in test mode
+4. `.env.${APP_ENV}`
+5. `.env.${APP_ENV}.local`
+
+Values from `Env` override file values.
+
+Keys ending in `_SECRET` may contain encrypted `@zyno-io/config` payloads. They are decrypted while loading when `CONFIG_DECRYPTION_SECRET` is set; `CONFIG_DECRYPTION_KEY` is also supported as a fallback for older deployments. Encrypted `_SECRET` values from process env are decrypted the same way.
+
+## Env Behavior
+
+`Env` is the only runtime bridge to `process.env`. It is preloaded from `process.env`, typed as optional strings, and exported from the package root.
+
+Config loading reads from `Env` without deleting consumed keys from `process.env`. Values loaded into the typed config object remain available to later code and child processes.
+
+## Required Environment
+
+`APP_ENV` is required only when `NODE_ENV=production`. The loader infers `APP_ENV=test` under Node's test runner and otherwise defaults to `development` outside production.
+
+## Built-In Configuration And Environment Surface
+
+`BaseAppConfig` owns the reflected application settings used during `createApp()`. Some observability keys below are read directly from `Env` by the early telemetry bootstrap instead, so they do not need to be declared on `BaseAppConfig` unless an application wants to load them through a custom config class.
+
+### Application
+
+| Variable                                 | Type      | Default                                           | Description                                                                                                   |
+| ---------------------------------------- | --------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `APP_ENV`                                | `string`  | test/development inferred; required in production | Application environment.                                                                                      |
+| `DEVCONSOLE_ENABLED`                     | `boolean` | enabled in development                            | Enable or disable `/_devconsole` independently of `APP_ENV`.                                                  |
+| `PORT`                                   | `number`  | `3000`                                            | HTTP server port. Ignored in `APP_ENV=test` unless `frameworkConfig.port` or `serverConfig.port` is provided. |
+| `USE_REAL_IP_HEADER`                     | `boolean` | unset                                             | Trust proxy remote-address headers.                                                                           |
+| `HTTP_MAX_REQUEST_BODY_BYTES`            | `number`  | `104857600`                                       | Maximum decoded request body bytes.                                                                           |
+| `HTTP_MAX_REQUEST_COMPRESSED_BODY_BYTES` | `number`  | `26214400`                                        | Maximum compressed request body bytes before gzip decoding.                                                   |
+
+### Database
+
+| Variable                 | Type                    | Default | Description                                                      |
+| ------------------------ | ----------------------- | ------- | ---------------------------------------------------------------- |
+| `DB_ADAPTER`             | `'mysql' \| 'postgres'` | unset   | Dialect used by shared `createDatabase(config, entities)` calls. |
+| `TSF_TEST_DATABASE_NAME` | `string`                | unset   | Internal test database override used by `TestingFacade`.         |
+
+### MySQL
+
+| Variable                     | Type     | Default                           |
+| ---------------------------- | -------- | --------------------------------- |
+| `MYSQL_HOST`                 | `string` | unset                             |
+| `MYSQL_PORT`                 | `number` | unset                             |
+| `MYSQL_USER`                 | `string` | unset                             |
+| `MYSQL_PASSWORD_SECRET`      | `string` | unset                             |
+| `MYSQL_DATABASE`             | `string` | unset                             |
+| `MYSQL_CONNECTION_LIMIT`     | `number` | 10 production, 5 development/test |
+| `MYSQL_MIN_IDLE_CONNECTIONS` | `number` | unset                             |
+| `MYSQL_IDLE_TIMEOUT_SECONDS` | `number` | 60 production, 5 development/test |
+
+### PostgreSQL
+
+| Variable                     | Type      | Default                           |
+| ---------------------------- | --------- | --------------------------------- |
+| `PG_HOST`                    | `string`  | unset                             |
+| `PG_PORT`                    | `number`  | unset                             |
+| `PG_USER`                    | `string`  | unset                             |
+| `PG_PASSWORD_SECRET`         | `string`  | unset                             |
+| `PG_DATABASE`                | `string`  | unset                             |
+| `PG_SCHEMA`                  | `string`  | unset                             |
+| `PG_SSL`                     | `boolean` | unset                             |
+| `PG_SSL_REJECT_UNAUTHORIZED` | `boolean` | unset                             |
+| `PG_CONNECTION_LIMIT`        | `number`  | 10 production, 5 development/test |
+| `PG_IDLE_TIMEOUT_SECONDS`    | `number`  | 60 production, 5 development/test |
+
+### Authentication
+
+| Variable                   | Type      | Default                |
+| -------------------------- | --------- | ---------------------- |
+| `AUTH_JWT_ISSUER`          | `string`  | unset                  |
+| `AUTH_JWT_EXPIRATION_MINS` | `number`  | runtime fallback `60`  |
+| `AUTH_JWT_COOKIE_NAME`     | `string`  | runtime fallback `jwt` |
+| `AUTH_JWT_SECRET`          | `string`  | unset                  |
+| `AUTH_JWT_SECRET_B64`      | `string`  | unset                  |
+| `AUTH_JWT_ED_SECRET`       | `string`  | unset                  |
+| `AUTH_JWT_ENABLE_VERIFY`   | `boolean` | `true`                 |
+| `AUTH_BASIC_SECRET`        | `string`  | unset                  |
+
+### Crypto
+
+| Variable           | Type     | Default |
+| ------------------ | -------- | ------- |
+| `CRYPTO_SECRET`    | `string` | unset   |
+| `CRYPTO_IV_LENGTH` | `number` | `12`    |
+
+### Redis And Workers
+
+| Variable              | Type                 | Default                 |
+| --------------------- | -------------------- | ----------------------- |
+| `REDIS_SENTINEL_HOST` | `string`             | unset                   |
+| `REDIS_SENTINEL_PORT` | `number`             | unset                   |
+| `REDIS_SENTINEL_NAME` | `string`             | unset                   |
+| `REDIS_HOST`          | `string`             | unset                   |
+| `REDIS_PORT`          | `number`             | unset                   |
+| `REDIS_PREFIX`        | `string`             | package name            |
+| `CACHE_REDIS_*`       | `string`/`number`    | falls back to `REDIS_*` |
+| `MUTEX_REDIS_*`       | `string`/`number`    | falls back to `REDIS_*` |
+| `BROADCAST_REDIS_*`   | `string`/`number`    | falls back to `REDIS_*` |
+| `MESH_REDIS_*`        | `string`/`number`    | falls back to `REDIS_*` |
+| `BULL_REDIS_*`        | `string`/`number`    | falls back to `REDIS_*` |
+| `BULL_QUEUE`          | `string`             | `default`               |
+| `MUTEX_MODE`          | `'local' \| 'redis'` | `local`                 |
+| `ENABLE_JOB_RUNNER`   | `boolean`            | unset                   |
+| `TEST_KEEP_DB`        | `string`             | unset                   |
+| `TEST_RUN_TS`         | `string`             | unset                   |
+
+### Observability
+
+| Variable                              | Type      | Default |
+| ------------------------------------- | --------- | ------- |
+| `SENTRY_DSN`                          | `string`  | unset   |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`         | `string`  | unset   |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`  | `string`  | unset   |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `string`  | unset   |
+| `OTEL_METRICS_ENDPOINT_ENABLED`       | `boolean` | unset   |
+| `OTEL_DEBUG`                          | `boolean` | unset   |
+| `OTEL_SDK_DISABLED`                   | `boolean` | unset   |
+| `ALERTS_SLACK_WEBHOOK_URL`            | `string`  | unset   |
+
+### SRPC
+
+| Variable                   | Type     | Default |
+| -------------------------- | -------- | ------- |
+| `SRPC_AUTH_SECRET`         | `string` | unset   |
+| `SRPC_AUTH_CLOCK_DRIFT_MS` | `number` | `30000` |
+
+### HTTP And OpenAPI
+
+| Variable                         | Type                                      | Default                                          | Description                                                                              |
+| -------------------------------- | ----------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `HTTP_REQUEST_LOGGING_MODE`      | `'none' \| 'e2e' \| 'finish' \| 'errors'` | `errors` in test, `e2e` otherwise                | Controls request start, finish, and error logs.                                          |
+| `HEALTHZ_ENABLE_REQUEST_LOGGING` | `boolean`                                 | `false`                                          | Includes `/healthz` in normal request logging.                                           |
+| `ENABLE_OPENAPI_SCHEMA`          | `boolean`                                 | development outside Node tests                   | Writes `openapi.yaml` after startup; legacy route fallback when the route flag is unset. |
+| `ENABLE_OPENAPI_ROUTE`           | `boolean`                                 | enabled in development/test                      | Serves `/openapi.json` and `/openapi.yaml`; takes precedence over the schema flag.       |
+| `ENABLE_PINO_PRETTY`             | `boolean`                                 | enabled in development/test                      | Enables pretty log output.                                                               |
+| `ENABLE_PINO_SINGLE_LINE`        | `boolean`                                 | enabled in development/test                      | Keeps pretty log entries on one line.                                                    |
+| `LOG_LEVEL`                      | `string`                                  | `debug` outside production, `info` in production | Sets the `pino-pretty` output filter; JSON logging is not filtered by this key.          |
+
+### Mail
+
+| Variable               | Type                   | Default     |
+| ---------------------- | ---------------------- | ----------- |
+| `MAIL_FROM`            | `string`               | unset       |
+| `MAIL_FROM_NAME`       | `string`               | unset       |
+| `MAIL_PROVIDER`        | `'smtp' \| 'postmark'` | `smtp`      |
+| `SMTP_HOST`            | `string`               | `127.0.0.1` |
+| `SMTP_PORT`            | `number`               | `1025`      |
+| `SMTP_USER`            | `string`               | unset       |
+| `SMTP_PASSWORD_SECRET` | `string`               | unset       |
+| `SMTP_TLS`             | `boolean`              | `false`     |
+| `POSTMARK_SECRET`      | `string`               | unset       |
+
+## `isDevFeatureEnabled`
+
+```ts
+import { isDevFeatureEnabled } from '@zyno-io/ts-server-foundation';
+
+if (isDevFeatureEnabled(config.ENABLE_OPENAPI_SCHEMA)) {
+    // enabled
+}
+```
+
+`'1'` and `'true'` enable a flag. `'0'` and `'false'` disable a flag. Undefined flags default to enabled in development/test and disabled in production unless a different default is passed.