Overview

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.

Smallest Example

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",
});

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 });
    },
  }),
);

# 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"}'

Progressive Patterns

From a fingerprinted secret to cleartext config, plain env helpers, and Docker-local fallbacks:

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",
});

Declaration Reference

Resolution Chain

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):

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 for contracts and Config for cleartext + vault.env.

Redacted until reveal

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

Without a bound encrypted backend, mutations throw:

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:

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)
    },
  },
});

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.

The Capabilities of Vault

Troubleshooting

Learn more

• Secrets — options, Redacted, effects, tenancy paths
• Config — cleartext contracts and vault.env
• Key Rotation — oke vault rotate / rotate-master
• fx — fx.vault.get · set · rotate · delete · list · status
• Errors — VaultBootError · VaultError · VaultSealed
• Environment variables — OKE_VAULT_*

Next