Secrets

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.

Smallest Example

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 { 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({
      in: z.object({ amount: z.number().int().positive() }),
    })
    .gate(member),
  flow({
    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 };
    },
  }),
);

Progressive Patterns

From a bare name to schema, cadence, tenancy, and sensitivity overrides:

export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
  description: "HMAC secret for outbound webhooks",
});

Options Reference

Third argument shape is VaultSecretOptions on vault.secret(name, options):

Empty name throws TypeError: vault.secret: name is required.

Reading secrets

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:

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:

vault boot failed — 2 missing secret(s):
  - STRIPE_KEY: Stripe secret API key
  - APP_WEBHOOK_SECRET: HMAC secret for outbound webhooks

Fill gaps with:

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

Learn more

• Vault overview — resolution chain and drivers
• Config — cleartext contracts vs secrets
• Key Rotation — version and master-key rotate
• Tenancy — fx.tenant.id for per-tenant paths
• fx — full fx.vault table

Next