@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/guides/core-concepts/secrets-vault.md

@@ -0,0 +1,177 @@
+---
+title: Secrets & Vault
+description: Load configuration and credentials from a vault, hydrate them at boot, and rotate database credentials without a restart
+difficulty: intermediate
+---
+
+# Secrets & Vault
+
+IGNIS can load configuration and credentials from a vault instead of reading `process.env` directly. This guide shows how to enable it, how to consume secrets in your code, and how to rotate dynamic database credentials into a live pool without restarting the server.
+
+> [!TIP] You do not have to do anything to keep working as before
+> Until you override `registerSecrets()`, IGNIS uses the `system-envs` provider, which reads `process.env`. Everything below is opt-in.
+
+## The Mental Model
+
+Secrets reach your app through two paths:
+
+- **Hydrate** - at boot, IGNIS fetches secrets and merges them into `process.env` / `Envs`. Existing code that reads `process.env.APP_ENV_*` keeps working with no change.
+- **Provider** - the resolved provider is bound in the container at `@app/config`. Inject it wherever you need on-demand reads, dynamic credentials, or rotation.
+
+You configure both in one place: a `registerSecrets()` override on your application class.
+
+## Enabling a Provider
+
+Override `registerSecrets()` on your `Application extends BaseApplication`.
+
+### HashiCorp Vault
+
+Recommended for enterprise: KV v2 static secrets plus dynamic database credentials with automatic rotation.
+
+```typescript
+import { SecretProviders, VaultAuthMethods } from '@venizia/ignis-helpers';
+
+export class Application extends BaseApplication {
+  override registerSecrets() {
+    return {
+      provider: SecretProviders.HASHICORP_VAULT,
+
+      config: {
+        endpoint: 'https://vault.internal:8200',
+        // Dev: a raw token. Production: AppRole or Kubernetes.
+        auth: { method: VaultAuthMethods.APP_ROLE, roleId, secretId },
+        // or: { method: VaultAuthMethods.TOKEN, token }
+        // or: { method: VaultAuthMethods.KUBERNETES, role: 'my-app' }
+      },
+
+      // Static KV v2 secrets -> merged into Envs once at boot.
+      hydrate: [
+        { path: 'secret/data/myapp/config' },                    // keys land as-is
+        { path: 'secret/data/myapp/db', prefix: 'APP_ENV_DS_' }, // optional prefix
+        // { path: 'secret/data/myapp/db', keys: { password: 'APP_ENV_DS_PASSWORD' } },
+      ],
+
+      // Dynamic engine secrets -> renewed and rotated automatically.
+      lease: [
+        { key: 'datasources.PostgresDataSource', path: 'database/creds/app-role' },
+      ],
+    };
+  }
+}
+```
+
+`node-vault` is an optional peer. Install it in the application that uses this provider:
+
+```bash
+bun add node-vault
+```
+
+Applications that do not use this provider never need it - not even when compiling a binary with
+`Bun.build`. If your application uses this provider **and** compiles a binary, ship `node-vault` in
+`node_modules` next to the binary, or inject a ready-made `client` through the helper options.
+
+### Dotenv Vault
+
+An encrypted `.env.vault` file decrypted at runtime with a per-environment `DOTENV_KEY`. Static only.
+
+```typescript
+import { SecretProviders } from '@venizia/ignis-helpers';
+
+export class Application extends BaseApplication {
+  override registerSecrets() {
+    return {
+      provider: SecretProviders.DOTENV_VAULT,
+      config: { path: '.env.vault', dotenvKey: process.env.DOTENV_KEY },
+      hydrate: [{ path: 'ignored' }], // decrypts the file and merges it into Envs
+    };
+  }
+}
+```
+
+```bash
+bun add @dotenvx/dotenvx
+```
+
+### System Env (default)
+
+The default; shown here only to be explicit. Reads `process.env`, no dependencies.
+
+```typescript
+override registerSecrets() {
+  return { provider: SecretProviders.SYSTEM_ENVS };
+}
+```
+
+## Addressing and Merging
+
+Each `hydrate` entry resolves a path to a flat key-value object that is merged into `Envs` and `process.env`:
+
+- **Convention** - store the keys in the vault already named `APP_ENV_...` and they merge as-is, no mapping needed.
+- **`prefix`** - prepend a string to every merged key.
+- **`keys`** - an explicit `vaultKey -> envKey` map for precise control (wins over `prefix`).
+
+When the provider is live, vault values take precedence over `process.env`.
+
+## Reading Secrets in Your Code
+
+Inject the provider bound at `@app/config`.
+
+```typescript
+import type { ISecretsHelper } from '@venizia/ignis-helpers';
+
+@service()
+export class BillingService {
+  constructor(
+    @inject({ key: '@app/config' }) private secrets: ISecretsHelper,
+  ) {}
+
+  async run() {
+    // A single keyed value (TTL-cached):
+    const apiKey = await this.secrets.get({ path: 'secret/data/myapp/stripe', key: 'apiKey' });
+
+    // Or the whole bundle at a path:
+    const bundle = await this.secrets.getBundle({ path: 'secret/data/myapp/stripe' });
+  }
+}
+```
+
+Code that only relies on hydrated values keeps reading `process.env.APP_ENV_*` and needs no injection at all.
+
+## Rotating Database Credentials
+
+Dynamic secrets let Vault mint short-lived database credentials that expire and rotate. IGNIS renews them and, on rotation, rebuilds the connection pool gracefully.
+
+You do **not** write any rotation code for PostgreSQL. Two steps enable it:
+
+1. Configure a dynamic database engine in Vault so a read against `database/creds/<role>` returns fresh credentials with a TTL.
+2. Add a `lease` entry whose `key` is the DI binding key of your datasource (`datasources.<ClassName>`), as in the HashiCorp example above.
+
+From there IGNIS:
+
+- renews the lease before it expires;
+- when Vault issues fresh credentials, calls the datasource's `onSecretRotated()`, which swaps the new credentials in, builds a new pool, and drains the old one so in-flight transactions finish;
+- keeps the app running - no restart.
+
+> [!WARNING] Your datasource configure() must read from this.settings
+> Rotation writes the new credentials onto `this.settings` and re-runs `configure()`. If your `configure()` builds the pool from a hard-coded connection string instead, rotation rebuilds with stale credentials. Build the pool from `this.settings`:
+> ```typescript
+> override configure(): void {
+>   this.client = new Pool(this.settings);
+> }
+> ```
+
+## Behaviour When the Vault Is Down
+
+The failure policy is keyed on `NODE_ENV`:
+
+- **Development** (`local`, `debug`, `development`, `dev`, `sit`) - a vault failure logs a warning and falls back to `process.env`, so you can work offline.
+- **Everything else** - a vault failure throws and crashes the boot. The app never starts with missing or empty secrets.
+
+## Testing Against a Real Vault
+
+A local end-to-end setup (Vault dev-mode plus a throwaway PostgreSQL) is described in `docs/superpowers/vault-integration-local-testing.md` in the repository.
+
+## See Also
+
+- [Secrets & Vault Reference](/references/base/secrets) - full API, machinery, and const-classes
+- [DataSources](/guides/core-concepts/persistent/datasources) - the pool that rotation rebuilds

package/content/guides/core-concepts/services.md

@@ -57,7 +57,7 @@ export class UserService extends BaseService {
 
 ## Registering a Service
 
-Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method. Do not add `@injectable` to services; `this.service()` handles the binding.
+Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method, which handles the binding. There is no class-level decorator for this.
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';

package/content/guides/get-started/5-minute-quickstart.md

@@ -1,21 +1,27 @@
 # 5-Minute Quickstart
 
-Build your first IGNIS API endpoint in 5 minutes. No database, no complex setup - just a working "Hello World" API.
+Build a working IGNIS API: one controller, one route, dependency injection, and generated API docs - no database required.
 
-**Time to Complete:** ~5 minutes
+**Time to complete:** ~5 minutes
 
-> **Prerequisites:** [Bun installed](./setup) and basic TypeScript knowledge.
+> **Prerequisite:** [Install Bun](./setup) 1.3 or later before you start.
 
-## Step 1: Create Project (30 seconds)
+## 1. Create the project
+
+Scaffold a project and install IGNIS:
 
 ```bash
 mkdir my-app && cd my-app
 bun init -y
 bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis @venizia/ignis-helpers
-bun add -d typescript @types/bun @venizia/dev-configs eslint prettier tsc-alias
+bun add -d typescript @types/bun @venizia/dev-configs
 ```
 
-## Step 2: Configure Development Tools (30 seconds)
+Both commands finish in a few seconds. You now have a `package.json` with IGNIS in `dependencies`.
+
+## 2. Configure TypeScript for decorators
+
+IGNIS controllers use TypeScript's legacy decorators (`@controller`, `@get`). Set the two decorator flags directly in your own `tsconfig.json`. Bun does not reliably resolve them through an `extends` chain, and a missing flag drops your routes silently.
 
 Create `tsconfig.json`:
 
@@ -26,59 +32,23 @@ Create `tsconfig.json`:
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",
-    "baseUrl": "src",
     "paths": {
-      "@/*": ["./*"]
-    }
+      "@/*": ["./src/*"]
+    },
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]
 }
 ```
 
-Create `eslint.config.mjs`:
-
-```javascript
-import { eslintConfigs } from "@venizia/dev-configs";
-
-export default eslintConfigs;
-```
-
-Create `.prettierrc.mjs`:
-
-```javascript
-import { prettierConfigs } from "@venizia/dev-configs";
-
-export default prettierConfigs;
-```
-
-Create `.prettierignore`:
-
-```
-dist
-node_modules
-*.log
-.*-audit.json
-```
-
-## Step 3: Write Your API (2 minutes)
-
-:::info What is a Decorator?
-A decorator is a TypeScript feature that adds behavior to classes, methods, or properties. It's the `@something` syntax you see before definitions (like `@controller`, `@get`, `@inject`). Decorators in IGNIS handle routing, dependency injection, and API documentation automatically.
-
-[Learn more →](/guides/reference/glossary#decorators)
-:::
-
-:::info What is Binding?
-"Binding" means registering a component (like a service or repository) with the application's dependency injection container. Think of it as telling the app: "Hey, this service exists and here's how to create it." Once bound, you can inject it anywhere using `@inject`.
-
-[Learn more →](/guides/core-concepts/dependency-injection)
-:::
+## 3. Write the API
 
 Create `src/index.ts`:
 
 ```typescript
-import { z } from "@hono/zod-openapi";
+import { z } from '@hono/zod-openapi';
 import {
   BaseApplication,
   BaseRestController,
@@ -87,224 +57,107 @@ import {
   IApplicationInfo,
   jsonContent,
   ApiReferenceComponent,
-} from "@venizia/ignis";
-import { HTTP } from "@venizia/ignis-helpers";
-import { Context } from "hono";
-import appInfo from "./../package.json";
+} from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
+import { Context } from 'hono';
+import appInfo from './../package.json';
 
-// 1. Define a controller
-@controller({ path: "/hello" })
+@controller({ path: '/hello' })
 class HelloController extends BaseRestController {
   constructor() {
-    super({ scope: "HelloController", path: "/hello" });
+    super({ scope: 'HelloController', path: '/hello' });
   }
 
-  // Override binding() to register custom routes via bindRoute() or defineRoute().
-  // For decorator-based routes (@get, @post), this can be empty.
+  // binding() is abstract - leave it empty when every route uses @get/@post decorators.
   override binding() {}
 
   @get({
     configs: {
-      path: "/",
+      path: '/',
       responses: {
         [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
-          description: "Says hello",
+          description: 'Says hello',
           schema: z.object({ message: z.string() }),
         }),
       },
     },
   })
   sayHello(c: Context) {
-    return c.json({ message: "Hello from IGNIS!" }, HTTP.ResultCodes.RS_2.Ok);
+    return c.json({ message: 'Hello from IGNIS!' }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 
-// 2. Create the application
 class App extends BaseApplication {
   getAppInfo(): IApplicationInfo {
     return appInfo;
   }
 
-  staticConfigure() {
-    // Static configuration before dependency injection
-  }
+  staticConfigure() {}
 
   preConfigure() {
     this.component(ApiReferenceComponent);
     this.controller(HelloController);
   }
 
-  postConfigure() {
-    // Configuration after all bindings are complete
-  }
+  postConfigure() {}
 
-  setupMiddlewares() {
-    // Custom middleware setup (optional)
-  }
+  setupMiddlewares() {}
 }
 
-// 3. Start the server
 const app = new App({
-  scope: "App",
+  scope: 'App',
   config: {
-    host: "0.0.0.0",
+    host: '0.0.0.0',
     port: 3000,
-    path: { base: "/api", isStrict: false },
-    debug: { shouldShowRoutes: true }, // Prints all registered routes on startup
+    path: { base: '/api', isStrict: false },
   },
 });
 
-// start() runs the full lifecycle: preConfigure → register resources → setupMiddlewares → HTTP server
-app.start();
+app.init();
+await app.start();
 ```
 
-Update `package.json` to add build scripts:
+`@controller` groups routes under `/hello`. `@get` registers a GET route together with its OpenAPI schema. `preConfigure()` wires the controller and the API docs component into dependency injection before the server starts. `app.init()` registers the application's core bindings - call it before `app.start()`.
 
-```json
-{
-  "name": "5-mins-qs",
-  "version": "1.0.0",
-  "description": "5-minute quickstart example",
-  "private": true,
-  "scripts": {
-    "start": "bun run src/index.ts",
-    "lint": "eslint --report-unused-disable-directives . && prettier \"**/*.{js,ts}\" -l",
-    "lint:fix": "eslint --report-unused-disable-directives . --fix && prettier \"**/*.{js,ts}\" --write",
-    "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
-    "clean": "sh ./scripts/clean.sh",
-    "rebuild": "bun run clean && bun run build",
-    "server:dev": "NODE_ENV=development bun run src/index.ts",
-    "server:prod": "NODE_ENV=production bun run dist/index.js"
-  },
-  "dependencies": {
-    "hono": "^4.12.25",
-    "@hono/zod-openapi": "latest",
-    "@scalar/hono-api-reference": "latest",
-    "@venizia/ignis": "latest",
-    "@venizia/ignis-helpers": "latest"
-  },
-  "devDependencies": {
-    "typescript": "^6.0.3",
-    "@types/bun": "latest",
-    "@venizia/dev-configs": "latest",
-    "eslint": "^10.5.0",
-    "prettier": "^3.8.4",
-    "tsc-alias": "^1.8.10"
-  }
-}
-```
+New to decorators or dependency injection? See the [glossary](/guides/reference/glossary#decorators) and [Dependency Injection](../core-concepts/dependency-injection.md).
 
-Create `scripts/clean.sh`:
+## 4. Run it
 
-```bash
-#!/bin/bash
+Start the server:
 
-# Remove build artifacts
-rm -rf dist/
-rm -rf node_modules/.cache/
+```bash
+bun run src/index.ts
+```
 
-# Remove log files
-rm -f *.log
-rm -f .*.log
-rm -f .*-audit.json
+After a moment you'll see:
 
-echo "Cleaned build artifacts and logs"
+```
+[App-start] Server STARTED | Address: 0.0.0.0:3000
 ```
 
-## Step 4: Run It (30 seconds)
+In a new terminal, request the endpoint:
 
 ```bash
-bun run src/index.ts
+curl http://localhost:3000/api/hello
 ```
 
-Visit `http://localhost:3000/api/hello` in your browser!
-
-**Response:**
+You get:
 
 ```json
-{ "message": "Hello from IGNIS!" }
+{"message":"Hello from IGNIS!"}
 ```
 
-## View API Docs
-
-Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI documentation!
-
-## What Just Happened?
-
-### Framework Patterns
-
-| Component | What It Does |
-|-----------|--------------|
-| `@controller` | Registers a class as an API controller at `/api/hello`. Supports `transport` field for REST (default) or gRPC |
-| `@get` | Defines a GET endpoint with OpenAPI metadata (auto-sets HTTP method) |
-| `Zod schema` | Validates request/response and auto-generates OpenAPI docs |
-| `BaseRestController` | Provides lifecycle hooks, route binding, and OpenAPI integration for REST controllers |
-| `BaseApplication` | Manages dependency injection, middleware, and server startup |
-| `ApiReferenceComponent` | Generates interactive API docs at `/doc/explorer` |
-| `app.start()` | Runs the full lifecycle (preConfigure → register resources → middlewares) then starts HTTP server on port 3000 |
-
-### Why Development Configs?
-
-You might wonder why we set up TypeScript, ESLint, and Prettier configs in a "quickstart". Here's why:
-
-**IGNIS is opinionated about code quality.** We believe clean, consistent code from day one prevents technical debt later. The `@venizia/dev-configs` package provides pre-configured settings that:
-
-| Config | Purpose |
-|--------|---------|
-| `tsconfig.json` | Strict TypeScript settings optimized for IGNIS decorators and path aliases |
-| `eslint.config.mjs` | Catches common errors, enforces best practices, works with TypeScript |
-| `.prettierrc.mjs` | Consistent formatting across your team - no more style debates |
+## 5. View the API docs
 
-**Benefits of starting with IGNIS code style:**
+Open `http://localhost:3000/api/doc/explorer` in your browser. You'll see an interactive Scalar API reference listing `GET /hello`, generated from the Zod schema you wrote.
 
-- **Consistency** - Same patterns across all IGNIS projects
-- **IDE Support** - Better autocomplete, error detection, and refactoring
-- **Team Ready** - New developers can onboard faster with familiar structure
-- **CI/CD Friendly** - Lint and format checks work out of the box
+## What you built
 
-> [!TIP]
-> All configs extend from `@venizia/dev-configs`, so you get updates automatically. Customize by overriding specific rules in your local config files.
+A running IGNIS REST API: one controller, one route, dependency injection wired through `BaseApplication`, and OpenAPI docs served automatically - all in a single file.
 
-## Next Steps
+## Next steps
 
-**You have a working API!**
-
-**Want more?**
-
-- **Add a database?** → [Building a CRUD API](../tutorials/building-a-crud-api.md)
-- **Production setup?** → [Complete Setup Guide](../tutorials/complete-installation.md) (ESLint, Prettier, etc.)
-- **Understand the architecture?** → [Core Concepts](../core-concepts/application/)
-
-**Quick additions:**
-
-**Add a POST endpoint:**
-
-```typescript
-@post({
-  configs: {
-    path: '/greet',
-    request: {
-      body: jsonContent({
-        schema: z.object({ name: z.string() }),
-      }),
-    },
-    responses: {
-      [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
-        schema: z.object({ greeting: z.string() }),
-      }),
-    },
-  },
-})
-async greet(c: Context) {
-  const { name } = c.req.valid('json');
-  return c.json({ greeting: `Hello, ${name}!` }, HTTP.ResultCodes.RS_2.Ok);
-}
-```
-
-Test it:
-
-```bash
-curl -X POST http://localhost:3000/api/hello/greet \
-  -H "Content-Type: application/json" \
-  -d '{"name":"World"}'
-```
+- Add a database: [Building a CRUD API](../tutorials/building-a-crud-api.md)
+- Add lint, formatting, and build scripts: [Complete Installation](../tutorials/complete-installation.md)
+- Add more routes and methods: [REST Controllers](../core-concepts/rest-controllers.md)
+- Understand the application lifecycle: [Core Concepts: Application](../core-concepts/application/)