okengine 0.18.4 → 0.19.0

package/site/content/docs/elements/vault/config.mdx

@@ -0,0 +1,256 @@
+---
+title: "Config"
+description: "vault.config cleartext settings, Console visibility, and vault.env helpers for plain process configuration."
+icon: "SlidersHorizontal"
+source: "docs/spec/unified-theory.md"
+---
+
+Config contracts (`vault.config`) hold **non-secret** operational settings — public origins,
+feature flags, workspace labels. They resolve through the same boot chain as secrets, but Console
+may show them in the clear.
+
+For developers who need validated settings without fingerprinting — declare `vault.config`, read
+with `fx.vault.get`, keep credentials on `vault.secret` instead.
+
+<Callout title="The one rule">
+  Use `vault.config` only when cleartext in Console and logs is acceptable. API keys, tokens, and
+  connection passwords belong on `vault.secret`.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a config contract
+
+```typescript title="src/core/vault.ts"
+import { vault } from "okengine";
+import { z } from "zod";
+
+export const publicAppUrl = vault.config("PUBLIC_APP_URL", {
+  description: "Public origin for email links and redirects",
+  schema: z.string().url(),
+  // Dev-only fallback — never used in prod boot
+  dev: "http://localhost:6530",
+});
+```
+
+</Step>
+
+<Step>
+### Read it in a Flow
+
+```typescript title="src/flows/invites/create.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { member } from "@/core/gate";
+import { publicAppUrl, noteCreatedMail } from "@/core";
+
+export const create = on(
+  http.post().gate(member),
+  flow({
+    in: z.object({ email: z.string().email() }),
+    do: async ({ email }, fx) => {
+      const origin = await fx.vault.get(publicAppUrl);
+      await fx.send(noteCreatedMail, {
+        to: email,
+        // Config may be revealed for URL building — still prefer holding Redacted
+        // until the send boundary when mixed with secrets
+        link: `${origin.reveal()}/accept`,
+      });
+      return fx.json.empty();
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### See it in Console
+
+The Config band shows `PUBLIC_APP_URL` in the clear after boot (secrets stay fingerprinted). Update
+via Console write or `oke vault set PUBLIC_APP_URL`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a public URL to flags, registration, and the env escape hatch:
+
+<Tabs items={["URL", "Flag", "Register", "Env"]}>
+
+<Tab value="URL">
+
+```typescript
+export const publicApiUrl = vault.config("PUBLIC_API_URL", {
+  description: "Browser-facing API origin",
+  schema: z.string().url(),
+  dev: "http://localhost:6530",
+});
+```
+
+</Tab>
+
+<Tab value="Flag">
+
+Feature toggles as config (cleartext by design):
+
+```typescript
+export const newDashboard = vault.config("FEATURE_NEW_DASHBOARD", {
+  description: "Enable the redesigned dashboard",
+  schema: z.enum(["on", "off"]),
+  dev: "off",
+});
+```
+
+</Tab>
+
+<Tab value="Register">
+
+`vault.config` is **not** auto-drained into `oke({ secrets })` (unlike `vault.secret`). Pass
+handles explicitly when the Manifest must list them:
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { publicAppUrl, publicApiUrl } from "@/core/vault";
+
+export const app = oke({
+  name: "notes",
+  env: "dev",
+  secrets: [publicAppUrl, publicApiUrl],
+});
+```
+
+</Tab>
+
+<Tab value="Env">
+
+Plain process configuration — no contract, no fingerprint, no driver bag:
+
+```typescript
+import { vault } from "okengine";
+
+const port = vault.env.int("PORT", 6530);
+const verbose = vault.env.bool("VERBOSE", false);
+const bag = vault.env.json<{ region: string }>("DEPLOY_META");
+```
+
+`vault.env.required("NAME")` registers the name so a missing value joins `VaultBootError` gaps
+alongside secret contracts.
+
+</Tab>
+
+</Tabs>
+
+## Options Reference
+
+Same option bag as secrets (`VaultSecretOptions`), with different defaults:
+
+| Option        | Type      | Default | Meaning                                                   |
+| ------------- | --------- | ------- | --------------------------------------------------------- |
+| `description` | `string`  | —       | Boot-gap and Console label                                |
+| `rotate`      | `string`  | omit    | Optional cadence hint (rarely used for config)            |
+| `schema`      | Schema    | —       | Declared shape for docs / tooling                         |
+| `dev`         | `string`  | —       | Dev-only fallback                                         |
+| `sensitive`   | `boolean` | `false` | Set `true` only if this config must never show in Console |
+
+Empty name throws `TypeError: vault.config: name is required`.
+
+**Consequence:** `sensitive: true` on a config behaves like a secret for Console cleartext —
+prefer `vault.secret` when that is the intent.
+
+## `vault.env` helpers
+
+Synchronous reads of process environment. Empty strings count as unset.
+
+| Helper                       | Returns               | Throws when                                  |
+| ---------------------------- | --------------------- | -------------------------------------------- |
+| `vault.env(name)`            | `string \| undefined` | —                                            |
+| `vault.env.required(name)`   | `string`              | unset — also registers for boot gaps         |
+| `vault.env.int(name, def?)`  | `number`              | unset without default, or not an integer     |
+| `vault.env.bool(name, def?)` | `boolean`             | unset without default, or not boolean-shaped |
+| `vault.env.json(name)`       | `T \| undefined`      | value present but not valid JSON             |
+
+Boolean true: `1` · `true` · `yes` · `on`. False: `0` · `false` · `no` · `off` (case-insensitive).
+
+```typescript
+// TypeError: vault.env.required: CI_TOKEN is not set
+vault.env.required("CI_TOKEN");
+
+// TypeError: vault.env.int: PORT is not an integer
+process.env.PORT = "abc";
+vault.env.int("PORT");
+```
+
+Reach for `vault.secret` / `vault.config` when the value must participate in the resolution chain,
+fingerprinting, or Console Vault.
+
+## Cleartext vs fingerprint
+
+| Kind     | Console list     | `runtime.cleartext(name)` | `runtime.fingerprint(name)` |
+| -------- | ---------------- | ------------------------- | --------------------------- |
+| `secret` | Fingerprint only | always `undefined`        | defined when loaded         |
+| `config` | Shown in clear   | loaded value              | always `undefined`          |
+
+Both still return `Redacted` from `fx.vault.get` — reveal when you need a plain string.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Config missing from Manifest / Console">
+  `vault.config` is not auto-registered. Pass `oke({ secrets: [publicAppUrl] })` or ensure the
+  declaring module is adopted the same way your app wires secrets.
+</Accordion>
+
+<Accordion title="VaultBootError includes a PUBLIC_* name">
+  Same resolution chain as secrets — set the value or provide `dev:` for local boot. Config gaps
+  fail boot just like secrets when registered.
+</Accordion>
+
+<Accordion title="TypeError: vault.env.required: NAME is not set">
+  Call site threw immediately. For boot-time collection, keep the `required` call so the name is
+  registered; boot then lists it with other gaps.
+</Accordion>
+
+<Accordion title="TypeError: vault.env.bool / int / json">
+  Value is present but malformed. Use the documented boolean tokens, an integer string, or valid
+  JSON — or supply a default for `int` / `bool` when unset is allowed.
+</Accordion>
+
+<Accordion title="Secret shown in the Config band">
+  You declared `vault.config` (or `sensitive: false`). Move credentials to `vault.secret`.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Secrets](/docs/elements/vault/secrets) — fingerprinted contracts and Redacted
+- [Vault overview](/docs/elements/vault) — resolution order and drivers
+- [Environment variables](/docs/reference/environment-variables) — `OKE_*` knobs
+- [fx](/docs/reference/fx) — `fx.vault.get` on any contract
+
+## Next
+
+<Cards>
+  <Card
+    title="Key Rotation"
+    description="Rotate versions and the builtin master key."
+    href="/docs/elements/vault/rotation"
+  />
+  <Card
+    title="Secrets"
+    description="Fingerprinted vault.secret contracts."
+    href="/docs/elements/vault/secrets"
+  />
+  <Card
+    title="Vault Overview"
+    description="Resolution chain and fx.vault surface."
+    href="/docs/elements/vault"
+  />
+</Cards>

package/site/content/docs/elements/vault/index.mdx

@@ -0,0 +1,356 @@
+---
+title: "Overview"
+description: "Protected knowledge — declare secret and config contracts, resolve values at boot, read Redacted credentials through fx.vault."
+icon: "KeyRound"
+source: "docs/spec/unified-theory.md"
+---
+
+Vault is how your backend **holds secrets and configuration safely**. Declare a contract
+(`vault.secret`, `vault.config`), resolve the value through the boot chain, and read it inside
+Flows as `Redacted` — never as a plain string in logs or responses.
+
+For developers wiring Stripe keys, SMTP URLs, and feature flags on okengine — contracts first,
+values only at the provider edge.
+
+<Callout title="The one rule">
+  **Contracts, never values.** Application code declares `vault.secret("STRIPE_KEY")` (or
+  `vault.config`). Cleartext crosses only at `.reveal()` on the credential boundary — never in
+  `console.log`, JSON, or the HTTP envelope.
+</Callout>
+
+<VaultResolution />
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a secret contract
+
+```typescript title="src/core/vault.ts"
+import { vault } from "okengine";
+
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC secret for outbound note webhooks",
+  // Dev-only fallback — never used in prod boot
+  dev: "dev-webhook-secret-change-me",
+});
+```
+
+</Step>
+
+<Step>
+### Read it in a Flow
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http } from "okengine";
+import { webhookSecret } from "@/core/vault";
+import { notesMutate } from "@/core/gate";
+
+export const create = on(
+  http.post().gate(notesMutate),
+  flow({
+    do: async (input, fx) => {
+      // Touches the contract → effects.secrets; reveal only at an SDK edge
+      await fx.vault.get(webhookSecret);
+      return fx.json.create({ id: fx.id(), title: input.title });
+    },
+  }),
+);
+```
+
+The compiler stamps `secrets: ["APP_WEBHOOK_SECRET"]` on the Flow’s effects.
+
+</Step>
+
+<Step>
+### Boot and call
+
+```bash
+# Missing value → VaultBootError lists every gap at once
+oke vault set APP_WEBHOOK_SECRET
+
+curl -X POST http://localhost:6530/notes \
+  -H "accept: application/json" \
+  -H "content-type: application/json" \
+  -d '{"title":"hello"}'
+```
+
+`fx.log` / `String(key)` / `JSON.stringify(key)` all show `[redacted]` — never the HMAC material.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a fingerprinted secret to cleartext config, plain env helpers, and Docker-local fallbacks:
+
+<Tabs items={["Secret", "Config", "Env", "fromDocker"]}>
+
+<Tab value="Secret">
+
+Fingerprinted contract — Console shows a fingerprint, never the value:
+
+```typescript title="src/core/vault.ts"
+import { vault } from "okengine";
+import { z } from "zod";
+
+export const stripeKey = vault.secret("STRIPE_KEY", {
+  description: "Stripe secret API key",
+  schema: z.string().startsWith("sk_"),
+  rotate: "90d",
+  // Optional local fallback when drivers.vault.dev allows it
+  dev: "sk_test_local",
+});
+```
+
+`vault("STRIPE_KEY", opts)` is the same as `vault.secret`.
+
+</Tab>
+
+<Tab value="Config">
+
+Non-sensitive settings — Console may show them in the clear:
+
+```typescript title="src/core/vault.ts"
+import { vault } from "okengine";
+import { z } from "zod";
+
+export const publicAppUrl = vault.config("PUBLIC_APP_URL", {
+  description: "Public origin for email links",
+  schema: z.string().url(),
+  dev: "http://localhost:6530",
+});
+```
+
+**Consequence:** `vault.config` is **not** auto-registered into `oke({ secrets })` — pass the
+handle (or import the declaring module before `oke()` when you need it on the Manifest).
+
+</Tab>
+
+<Tab value="Env">
+
+Plain process configuration — no boot chain, no redaction. Prefer contracts when the value must
+fingerprint or fail boot:
+
+```typescript
+import { vault } from "okengine";
+
+const port = vault.env.int("PORT", 6530);
+const debug = vault.env.bool("DEBUG", false);
+const raw = vault.env("FEATURE_FLAG"); // string | undefined
+const must = vault.env.required("CI_TOKEN"); // joins VaultBootError gaps when missing
+```
+
+</Tab>
+
+<Tab value="fromDocker">
+
+Local fallback that reads the URL the image recipe built for a role — kernel never sees the
+underlying env-var names:
+
+```typescript
+export const databaseUrl = vault.secret("DATABASE_URL", {
+  description: "Primary SQL URL",
+  dev: vault.fromDocker("store.sql"),
+});
+```
+
+Resolves from `OKE_STORE_SQL_URL` (and peers) when `allowDevFallbacks` is on.
+
+</Tab>
+
+</Tabs>
+
+## Declaration Reference
+
+| Declaration        | Signature                                              | Purpose                               |
+| ------------------ | ------------------------------------------------------ | ------------------------------------- |
+| `vault.secret`     | `vault.secret(name, options?)`                         | Fingerprinted secret contract         |
+| `vault`            | `vault(name, options?)`                                | Alias for `vault.secret`              |
+| `vault.config`     | `vault.config(name, options?)`                         | Cleartext config contract             |
+| `vault.fromDocker` | `vault.fromDocker(role)`                               | Dev fallback marker for an image role |
+| `vault.env`        | `vault.env` / `.required` / `.int` / `.bool` / `.json` | Sync process env — no contract        |
+
+| Option        | Type      | Default                        | Meaning                                                                |
+| ------------- | --------- | ------------------------------ | ---------------------------------------------------------------------- |
+| `description` | `string`  | —                              | Shown in boot-gap listings and Console                                 |
+| `rotate`      | `string`  | omit ≈ `"never"`               | Cadence hint (`"90d"`) or `"never"` — Console posture, not auto-rotate |
+| `schema`      | Schema    | —                              | Declared shape (Zod / Standard Schema) for docs and tooling            |
+| `dev`         | `string`  | —                              | Dev-only fallback; never used in prod boot                             |
+| `sensitive`   | `boolean` | `true` secret · `false` config | Whether cleartext must never leave the runtime                         |
+| `perTenant`   | `boolean` | `true` when tenancy on         | Resolve `{tenantId}/{name}` at request time; not boot-gap fatal        |
+
+## Resolution Chain
+
+<Callout title="Detailed section">
+  If you only need “declare and `fx.vault.get`”, the Smallest Example is enough. This section is how
+  boot finds a value — first hit wins.
+</Callout>
+
+Order (Console labels match these source ids):
+
+1. **driver** — built-in encrypted store, managed bag, or `env` / `memory` driver
+2. **process.env** — real environment (CI, hosting)
+3. **`.env.local`** — local overrides (gitignored)
+4. **dev-fallback** — `dev:` on the contract (dev boot only)
+
+Miss every layer → `VaultBootError` listing **all** gaps in one pass (including
+`vault.env.required` names):
+
+```text
+vault boot failed — 2 missing secret(s):
+  - STRIPE_KEY: Payments gateway key
+  - DATABASE_URL: Primary SQL URL
+```
+
+**Consequence:** fix every listed name before traffic — boot does not take a half-configured app.
+
+See [Secrets](/docs/elements/vault/secrets) for contracts and [Config](/docs/elements/vault/config)
+for cleartext + `vault.env`.
+
+## Redacted until reveal
+
+<VaultRedacted />
+
+`fx.vault.get(contract)` returns `Promise<Redacted<string>>`. Printing, logging, and JSON all
+yield `[redacted]`. Call `.reveal()` only at the Stripe / SMTP / SDK edge.
+
+Loaded secret substrings are also scrubbed from `fx.log` even when you pass cleartext by mistake
+(mask token `[redacted:secret]`).
+
+## `fx.vault` surface
+
+| Method                    | Needs backend | Meaning                                     |
+| ------------------------- | ------------- | ------------------------------------------- |
+| `get(contract)`           | No            | `Redacted<string>` — every app has this     |
+| `set(path, value, opts?)` | Yes (`vault`) | New version; optional `ttlMs` / `metadata`  |
+| `rotate(path, value)`     | Yes (`vault`) | New version under a fresh data key          |
+| `delete(path)`            | Yes (`vault`) | Crypto-shred; returns whether anything went |
+| `list(prefix?)`           | Yes (`vault`) | Paths only — never values                   |
+| `status()`                | Yes (`vault`) | `{ sealed, initialized, backend }`          |
+
+Without a bound encrypted backend, mutations throw:
+
+```text
+fx.vault.set needs a bound Vault backend — configure the vault element (drivers.vault = "vault") …
+```
+
+Dry-run refuses writes rather than mutate a live secret (`DryRunWriteIsolationError`).
+
+## Per-environment drivers
+
+Defaults from `DRIVER_DEFAULTS.vault` — pin overrides in `oke.config.ts`:
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    // Default vault.dev is "env"; Docker-first starters pin built-in:
+    vault: {
+      dev: "vault",
+      // test: "memory" (default)
+      // prod: "vault" (default)
+    },
+  },
+});
+```
+
+| Driver    | Runs as                          | Best for                                     |
+| --------- | -------------------------------- | -------------------------------------------- |
+| `env`     | Process / dotenv bag             | Simple local / CI without SQL vault tables   |
+| `vault`   | Built-in AES-256-GCM in Postgres | Docker-first apps; `oke vault init` / unseal |
+| `memory`  | In-process map                   | Tests                                        |
+| `managed` | Remote provider bag              | AWS / Azure / GCP / Doppler / 1Password      |
+
+create-oke Notes starters pin `vault.dev: "vault"` and declare stack + app contracts in
+`src/vault.ts` (`vault.secret` / `vault.config`). Console Vault lists those contracts —
+values still resolve from `.env.local`, process env, `oke vault set`, or `dev:` /
+`vault.fromDocker` fallbacks. Pass `oke({ secrets: NOTES_VAULT })` so configs resolve
+(only `vault.secret` auto-registers).
+
+Managed provider ids: `aws-secrets-manager` · `azure-key-vault` · `gcp-secret-manager` ·
+`doppler` · `1password`. Env knobs: [Environment variables](/docs/reference/environment-variables).
+
+## The Capabilities of Vault
+
+<Cards>
+  <Card
+    title="Secrets"
+    description="Fingerprinted vault.secret contracts, Redacted reads, boot gaps."
+    href="/docs/elements/vault/secrets"
+  />
+  <Card
+    title="Config"
+    description="vault.config cleartext settings and vault.env helpers."
+    href="/docs/elements/vault/config"
+  />
+  <Card
+    title="Key Rotation"
+    description="Version rotate, master-key rewrap, seal / unseal, CLI."
+    href="/docs/elements/vault/rotation"
+  />
+</Cards>
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="VaultBootError — N missing secret(s)">
+  Cause: `vault boot failed — N missing secret(s):` with every gap listed. On a TTY, `oke dev`
+  prompts each into `.env.local`; otherwise use `oke vault set` / env / managed, or a `dev:`
+  fallback. `vault.env.required` joins the same list.
+</Accordion>
+
+<Accordion title='vault: secret "…" is not loaded'>
+  `fx.vault.get` ran after boot without that name in the merged bag. Declare the contract, ensure a
+  resolution layer supplies it, and import the declaring module before `oke()`.
+</Accordion>
+
+<Accordion title="fx.vault.set / rotate needs a bound Vault backend">
+  Mutations require `drivers.vault = "vault"` (encrypted-at-rest adapter). `get` works on `env` /
+  `memory` / `managed` bags; writes need the builtin backend.
+</Accordion>
+
+<Accordion title="Logs still show a secret substring">
+  Prefer holding `Redacted` until `.reveal()` at the edge. Revealed cleartext is scrubbed from
+  `fx.log` when the value is registered — but third-party loggers bypass Vault redaction.
+</Accordion>
+
+<Accordion title="VaultSealed / cannot rotate while sealed">
+  Export `OKE_VAULT_MASTER_KEY` or run `oke vault unseal`. See [Key
+  Rotation](/docs/elements/vault/rotation).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Secrets](/docs/elements/vault/secrets) — options, Redacted, effects, tenancy paths
+- [Config](/docs/elements/vault/config) — cleartext contracts and `vault.env`
+- [Key Rotation](/docs/elements/vault/rotation) — `oke vault rotate` / `rotate-master`
+- [fx](/docs/reference/fx) — `fx.vault.get` · `set` · `rotate` · `delete` · `list` · `status`
+- [Errors](/docs/reference/errors) — `VaultBootError` · `VaultError` · `VaultSealed`
+- [Environment variables](/docs/reference/environment-variables) — `OKE_VAULT_*`
+
+## Next
+
+<Cards>
+  <Card
+    title="Secrets"
+    description="Declare fingerprinted contracts and read Redacted values."
+    href="/docs/elements/vault/secrets"
+  />
+  <Card
+    title="Channel Element"
+    description="Send email, SMS, and other human reach through templates."
+    href="/docs/elements/channel"
+  />
+  <Card
+    title="Gate Element"
+    description="Attach policies and rates before do runs."
+    href="/docs/elements/gate"
+  />
+</Cards>

package/site/content/docs/elements/vault/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Vault",
+  "icon": "KeyRound",
+  "pages": ["index", "secrets", "config", "rotation"]
+}