okengine 0.18.4 → 0.19.0

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

@@ -0,0 +1,273 @@
+---
+title: "Key Rotation"
+description: "Rotate secret versions under a fresh data key, rewrap the master key, and seal or unseal the builtin vault."
+icon: "RefreshCw"
+source: "docs/spec/unified-theory.md"
+---
+
+Key rotation keeps credentials and encryption keys moving without dropping the app. On the builtin
+`vault` driver you rotate a **secret version** (fresh data key) or the **master key** (KEK rewrap).
+Contract `rotate: "90d"` is a Console cadence hint — it does not rotate by itself.
+
+For operators and Flows that must cut over keys safely — prefer CLI for master material; use
+`fx.vault.rotate` for path versions inside privileged Flows.
+
+<Callout title="The one rule">
+  Never pass master keys as CLI argv in shared shells — they land in history. Prefer `oke vault
+  unseal --key -`, the env `OKE_VAULT_MASTER_KEY`, or the hidden prompt.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Initialize and set a secret (builtin driver)
+
+```bash
+# drivers.vault = "vault" — SQL-backed AES-256-GCM
+oke vault init          # prints master key once — store out of band
+export OKE_VAULT_MASTER_KEY=…   # or --key - from stdin
+
+oke vault set STRIPE_KEY
+# prompts for value, or: oke vault set STRIPE_KEY sk_live_…
+```
+
+</Step>
+
+<Step>
+### Rotate to a new version
+
+```bash
+oke vault rotate STRIPE_KEY sk_live_new_key
+# → oke vault: rotated STRIPE_KEY → v2 (fresh data key)
+```
+
+Omit the value to re-encrypt the current cleartext under a new data key (version bumps, readers
+still see the same string until you change it).
+
+</Step>
+
+<Step>
+### Confirm status
+
+```bash
+oke vault status
+# initialized, unsealed, kek version, secret count
+```
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From CLI path rotate to Flow mutations, cadence hints, and master rewrap:
+
+<Tabs items={["CLI rotate", "fx.vault.rotate", "Cadence", "Master"]}>
+
+<Tab value="CLI rotate">
+
+```bash
+oke vault rotate prod/api/stripe sk_live_new
+oke vault rotate prod/api/stripe          # same cleartext, fresh DEK
+```
+
+Needs an unsealed builtin backend. Missing path:
+
+```text
+oke vault: no such secret: prod/api/stripe
+```
+
+</Tab>
+
+<Tab value="fx.vault.rotate">
+
+Privileged Flow — requires `drivers.vault = "vault"` (bound adapter):
+
+```typescript title="src/flows/ops/rotate-stripe.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { gate } from "okengine";
+
+const operator = gate.policy("operator", ({ operator: op }) => !!op);
+
+export const rotateStripe = on(
+  http.post().gate(operator),
+  flow({
+    plane: "operator",
+    in: z.object({ value: z.string().min(1) }),
+    effects: { secrets: ["STRIPE_KEY"] },
+    do: async ({ value }, fx) => {
+      const result = await fx.vault.rotate("STRIPE_KEY", value);
+      return { path: result.path, version: result.version };
+    },
+  }),
+);
+```
+
+`fx.vault.set` writes a new version without forcing a fresh DEK policy the same way; prefer
+`rotate` when retiring the previous data key is the point.
+
+Dry-run refuses both (`DryRunWriteIsolationError`).
+
+</Tab>
+
+<Tab value="Cadence">
+
+Declare intent for Console posture — operators still run rotate:
+
+```typescript
+export const stripeKey = vault.secret("STRIPE_KEY", {
+  description: "Stripe secret API key",
+  rotate: "90d",
+});
+```
+
+Omit or `"never"` when the secret must not rotate on a schedule.
+
+</Tab>
+
+<Tab value="Master">
+
+Rewrap every DEK under a new KEK generation:
+
+```bash
+oke vault rotate-master
+# prints the new master key once — store it, then update OKE_VAULT_MASTER_KEY
+
+# Resume an interrupted rewrap:
+oke vault rotate-master --new-key -
+```
+
+Overlapping batches surface `VaultRotateBusy`. Console rotate-master while sealed → `VaultSealed`.
+
+</Tab>
+
+</Tabs>
+
+## Version physics
+
+<VaultRotate />
+
+Builtin storage encrypts each version with its own data key (DEK), wrapped by a KEK derived from
+the master key:
+
+| Operation                | What changes                     | Readers see                          |
+| ------------------------ | -------------------------------- | ------------------------------------ |
+| `set` / `rotate` + value | New version + (rotate) fresh DEK | New cleartext on next `get`          |
+| `rotate` without value   | New version + fresh DEK          | Same cleartext                       |
+| `rotate-master`          | New KEK; DEKs re-wrapped         | Same cleartexts; new master required |
+| `delete`                 | Crypto-shred path                | Subsequent `get` misses              |
+
+Paths are slash-separated with no leading slash (`prod/api/stripe`). Invalid paths throw
+`VaultError` `INVALID_PATH`.
+
+**Consequence:** secret access is not journaled — durable Flow replay re-reads live vault state
+after a rotate instead of replaying a stale credential from the journal.
+
+## Seal & unseal
+
+| Command / state    | Meaning                                                 |
+| ------------------ | ------------------------------------------------------- |
+| `oke vault init`   | Create backend state; print master key **once**         |
+| `oke vault seal`   | Drop in-memory master; reads fail with `SEALED`         |
+| `oke vault unseal` | Restore master from `--key` / env / prompt              |
+| `oke vault status` | `initialized`, sealed flag, `kekVersion`, `secretCount` |
+
+```bash
+oke vault unseal --key -          # read base64 master from stdin
+oke vault status --json
+```
+
+## CLI reference
+
+Env / dotenv bag loop:
+
+| Command                        | Purpose                   |
+| ------------------------------ | ------------------------- |
+| `oke vault set <NAME> [value]` | Write / overwrite a name  |
+| `oke vault list`               | List names (never values) |
+| `oke vault import <file>`      | Bulk import               |
+| `oke vault key rotate`         | Env-loop key helper       |
+
+Builtin encrypted store:
+
+| Command                           | Purpose                      |
+| --------------------------------- | ---------------------------- |
+| `oke vault init`                  | First-time initialize        |
+| `oke vault status [--json]`       | Seal / KEK / counts          |
+| `oke vault seal` / `unseal`       | Master lifecycle             |
+| `oke vault rotate <path> [value]` | Version + fresh DEK          |
+| `oke vault rotate-master`         | KEK rewrap                   |
+| `oke vault audit` …               | Audit trail / verify / purge |
+| `oke vault purge-expired`         | Drop expired rows            |
+| `oke vault backup` / `restore`    | File snapshot                |
+
+`--url` overrides the SQL URL (`DATABASE_URL` / `OKE_STORE_SQL_URL`).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="oke vault: no such secret">
+  Rotate/get targeted a path that was never set. `oke vault list` (or Console) for live paths;
+  remember per-tenant storage uses `{tenantId}/{name}`.
+</Accordion>
+
+<Accordion title="VaultSealed">
+  Process holds no master key. Export `OKE_VAULT_MASTER_KEY` or `oke vault unseal` before
+  rotate-master / reads that need the adapter.
+</Accordion>
+
+<Accordion title="VaultRotateBusy">
+  Another master-rotation lease or batch is in flight. Wait, or resume with `oke vault rotate-master
+  --new-key` (stdin `-` preferred).
+</Accordion>
+
+<Accordion title="VaultUnsupported / needs drivers.vault = vault">
+  Console or `fx.vault.rotate` hit a non-builtin bag (`env` / `memory` / `managed`). Pin
+  `drivers.vault` to `"vault"` and ensure SQL is available.
+</Accordion>
+
+<Accordion title="fx.vault.rotate needs a bound Vault backend">
+  Same as above — mutations need the encrypted adapter. `fx.vault.get` alone works on any driver.
+</Accordion>
+
+<Accordion title="DryRunWriteIsolationError on set / rotate">
+  Dry-run refuses vault writes so a live secret is never mutated. Use a real run for rotation.
+</Accordion>
+
+<Accordion title="VaultError EXPIRED">
+  A version’s absolute expiry passed on the builtin adapter. Rotate or set a new value; purge
+  expired rows with `oke vault purge-expired` when cleaning storage.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Secrets](/docs/elements/vault/secrets) — contracts and `fx.vault.get`
+- [Vault overview](/docs/elements/vault) — drivers and resolution
+- [Errors](/docs/reference/errors) — `VaultSealed` · `VaultRotateBusy` · `VaultUnsupported`
+- [Environment variables](/docs/reference/environment-variables) — `OKE_VAULT_MASTER_KEY`
+
+## Next
+
+<Cards>
+  <Card
+    title="Channel Element"
+    description="Send email and other human reach through templates."
+    href="/docs/elements/channel"
+  />
+  <Card
+    title="Secrets"
+    description="Declare contracts readers will rotate."
+    href="/docs/elements/vault/secrets"
+  />
+  <Card
+    title="Vault Overview"
+    description="Resolution chain, Redacted, and drivers."
+    href="/docs/elements/vault"
+  />
+</Cards>

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

@@ -0,0 +1,285 @@
+---
+title: "Secrets"
+description: "Typed vault.secret contracts, boot-time resolution, Redacted reads through fx.vault.get, and per-tenant paths."
+icon: "Key"
+source: "docs/spec/unified-theory.md"
+---
+
+Secret contracts (`vault.secret`) declare the credentials your backend requires — Stripe keys,
+webhook HMACs, SMTP URLs. Values resolve at boot; Flows read them as `Redacted` through
+`fx.vault.get`.
+
+For developers who must never leak credentials into logs or HTTP bodies — declare the name,
+resolve it, reveal only at the provider edge.
+
+<Callout title="The one rule">
+  Touch secrets only through `fx.vault.get(contract)`. That records the `secret` effect and returns
+  `Redacted` — `.reveal()` belongs at the SDK / HMAC boundary, not in return values.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare the contract
+
+```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",
+  dev: "sk_test_local",
+});
+```
+
+Import this module before `oke()` so auto-registry can adopt the contract (or pass it in
+`oke({ secrets: […] })`).
+
+</Step>
+
+<Step>
+### Read inside `do`
+
+```typescript title="src/flows/payments/charge.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { member } from "@/core/gate";
+import { stripeKey } from "@/core/vault";
+
+export const charge = on(
+  http.post().gate(member),
+  flow({
+    in: z.object({ amount: z.number().int().positive() }),
+    do: async ({ amount }, fx) => {
+      const key = await fx.vault.get(stripeKey);
+      const stripe = new Stripe(key.reveal());
+      const intent = await stripe.paymentIntents.create({ amount, currency: "usd" });
+      return { id: intent.id };
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Confirm the effect
+
+Manifest / Console list `secrets: ["STRIPE_KEY"]` on `payments.charge`. Logs that stringify
+`key` show `[redacted]`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a bare name to schema, cadence, tenancy, and sensitivity overrides:
+
+<Tabs items={["Minimal", "Schema", "Per-tenant", "Shared"]}>
+
+<Tab value="Minimal">
+
+Name only — description helps boot gaps and Console:
+
+```typescript
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC secret for outbound webhooks",
+});
+```
+
+</Tab>
+
+<Tab value="Schema">
+
+Attach a schema for tooling and human contracts (Zod / Standard Schema). Prefer validating at the
+provider edge when the remote value must match a prefix:
+
+```typescript
+export const resendApiKey = vault.secret("RESEND_API_KEY", {
+  description: "Resend email delivery API key",
+  schema: z.string().startsWith("re_"),
+});
+```
+
+</Tab>
+
+<Tab value="Per-tenant">
+
+When `gate.auth.tenant` is on, contracts default to request-time paths
+`{tenantId}/{name}` — they are **not** boot-gap fatal (value appears per tenant):
+
+```typescript
+export const tenantStripe = vault.secret("STRIPE_KEY", {
+  description: "Per-workspace Stripe key",
+  perTenant: true, // explicit; also the default when tenancy is on
+});
+```
+
+`fx.vault.get(tenantStripe)` resolves under the active `fx.tenant.id`. Missing tenant throws
+`TENANT_REQUIRED`. Opt out of isolation with `perTenant: false`.
+
+**Consequence:** seed or `set` the tenant path (`acme/STRIPE_KEY`), not only the bare contract
+name.
+
+</Tab>
+
+<Tab value="Shared">
+
+A secret shared across all tenants while tenancy is enabled:
+
+```typescript
+export const platformWebhook = vault.secret("PLATFORM_WEBHOOK", {
+  description: "Platform-wide webhook secret",
+  perTenant: false,
+});
+```
+
+Boot still requires a value for shared contracts.
+
+</Tab>
+
+</Tabs>
+
+## Options Reference
+
+Third argument shape is `VaultSecretOptions` on `vault.secret(name, options)`:
+
+| Option        | Type      | Default                | Meaning                                                              |
+| ------------- | --------- | ---------------------- | -------------------------------------------------------------------- |
+| `description` | `string`  | —                      | Boot-gap and Console label                                           |
+| `rotate`      | `string`  | omit ≈ `"never"`       | Cadence hint (`"90d"`) for Console posture — not automatic rotation  |
+| `schema`      | Schema    | —                      | Declared validator for docs / tooling                                |
+| `dev`         | `string`  | —                      | Dev-only fallback (`vault.fromDocker(role)` allowed)                 |
+| `sensitive`   | `boolean` | `true`                 | Fingerprinted; Console never shows cleartext                         |
+| `perTenant`   | `boolean` | `true` when tenancy on | Storage path `{tenantId}/{name}`; skipped in boot-gap scan when true |
+
+Empty name throws `TypeError: vault.secret: name is required`.
+
+## Reading secrets
+
+<VaultRedacted />
+
+| Call                         | Returns            | Notes                                  |
+| ---------------------------- | ------------------ | -------------------------------------- |
+| `await fx.vault.get(handle)` | `Redacted<string>` | Preferred — capability from the handle |
+| `await fx.vault.get("NAME")` | `Redacted<string>` | Same when the name is declared         |
+| `key.reveal()`               | `string`           | One explicit cleartext escape          |
+| `key.map(fn)`                | `Redacted<U>`      | Transform without exposing to callers  |
+| `String(key)` / `toJSON`     | `"[redacted]"`     | Safe for accidental serialization      |
+
+```typescript
+const key = await fx.vault.get(stripeKey);
+
+fx.log.info(`using ${key}`); // message contains [redacted]
+// JSON.stringify({ key }) → { "key": "[redacted]" }
+
+const client = new Stripe(key.reveal());
+```
+
+Secret access is **never journaled** — durable replay re-reads the live value so a rotated
+credential is not resurrected from the journal.
+
+## Effects & Manifest
+
+Calling `fx.vault.get` records `effects.secrets` with the contract name. Declare the same list
+explicitly when you want Manifest truth without inference:
+
+```typescript
+flow("payments.charge", {
+  effects: { secrets: ["STRIPE_KEY"] },
+  do: async (_, fx) => {
+    await fx.vault.get(stripeKey);
+  },
+});
+```
+
+Capability enforcement: reading a name not allowed by the Flow’s effects fails the `secret`
+capability check.
+
+## Boot gaps
+
+Missing non-tenant contracts fail boot with every hole listed once:
+
+```text
+vault boot failed — 2 missing secret(s):
+  - STRIPE_KEY: Stripe secret API key
+  - APP_WEBHOOK_SECRET: HMAC secret for outbound webhooks
+```
+
+Fill gaps with:
+
+| Layer        | How                                                       |
+| ------------ | --------------------------------------------------------- |
+| Driver       | `oke vault set NAME`, managed provider write, memory seed |
+| process.env  | Export `NAME=…` in the host / CI                          |
+| `.env.local` | Local override file (gitignored)                          |
+| `dev:`       | Contract fallback — only when dev fallbacks are allowed   |
+
+On a TTY, `oke dev` prompts for each gap before the app starts and writes values
+into `.env.local` (same store as `oke vault set`). Non-interactive runs still
+fail with `VaultBootError` listing every hole.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="VaultBootError lists this secret">
+  No resolution layer supplied a value. On a TTY, `oke dev` prompts into `.env.local`; otherwise use
+  `oke vault set` / env / managed, or a `dev:` fallback. Per-tenant contracts are skipped at boot —
+  seed the tenant path.
+</Accordion>
+
+<Accordion title='vault: secret "…" is not loaded'>
+  Boot succeeded but the name is absent from the merged bag (or you never declared it). Import the
+  declaring module; confirm auto-registry or `oke({ secrets: [handle] })`.
+</Accordion>
+
+<Accordion title="TENANT_REQUIRED on fx.vault.get">
+  Tenancy is on, the contract is per-tenant, and `fx.tenant.id` is null. Resolve a tenant on the
+  request, or set `perTenant: false` for a platform-wide secret.
+</Accordion>
+
+<Accordion title="Capability / secret effect denied">
+  The Flow’s `effects.secrets` (inferred or declared) must include the name you `get`. Touch the
+  handle inside `do`, or list the name explicitly.
+</Accordion>
+
+<Accordion title="Redacted still leaked through a third-party logger">
+  Vault scrubs `fx.log` and known substrings. Direct `console.log(key.reveal())` or foreign sinks
+  are outside the redactor — keep cleartext off those paths.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Vault overview](/docs/elements/vault) — resolution chain and drivers
+- [Config](/docs/elements/vault/config) — cleartext contracts vs secrets
+- [Key Rotation](/docs/elements/vault/rotation) — version and master-key rotate
+- [Tenancy](/docs/elements/gate/tenancy) — `fx.tenant.id` for per-tenant paths
+- [fx](/docs/reference/fx) — full `fx.vault` table
+
+## Next
+
+<Cards>
+  <Card
+    title="Config"
+    description="Non-sensitive vault.config and vault.env helpers."
+    href="/docs/elements/vault/config"
+  />
+  <Card
+    title="Key Rotation"
+    description="Rotate secret versions and the master key."
+    href="/docs/elements/vault/rotation"
+  />
+  <Card
+    title="Vault Overview"
+    description="Resolution chain, Redacted, and drivers."
+    href="/docs/elements/vault"
+  />
+</Cards>