Secrets

What

createSecretsFeature stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest with AES-256, using a key-encryption-key (KEK) loaded from the KUMIKO_SECRETS_MASTER_KEY_V1 env var (plus successive versions for rotation). It belongs on the server/platform side, values should not live in plain env vars per tenant.

import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";

How it works

• Read a secret in a handler via ctx.secrets.get(tenantId, handle); every read automatically appends a tenantSecretRead audit event, so all access is traceable.
• A rotate job re-encrypts all envelopes after a KEK version bump.
• set / delete / list handlers share one access rule (no per-handler drift in the blast radius).

Access control

set/delete/list are gated by a single rule. Default is admin-only; adopt the host’s role vocabulary or open it to any authenticated tenant user:

createSecretsFeature({ roles: ["TenantAdmin"] });                       // default
createSecretsFeature({ access: { roles: ["Ops"] } });                   // custom vocabulary
// any tenant member
createSecretsFeature({
  access: {
    openToAll: { reason: "every tenant member maintains the integration API keys in this product" },
  },
});

• Default: { roles: ["TenantAdmin"] }, only admins read previews and set/delete secrets.
• roles is shorthand for { access: { roles } } and is mutually exclusive with access.
• { access: { openToAll: { reason } } } lets any authenticated tenant user read secret previews and write/delete secrets. reason is required and names why no role check is needed.

openToAll is a large blast radius, every tenant member becomes a writer and gets preview access. Only use it when the product truly requires it; otherwise keep the default or set an explicit roles list.

Example

import { runDevApp } from "@cosmicdrift/kumiko-dev-server";
import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";

await runDevApp({
  secrets: createSecretsFeature({ access: { roles: ["TenantAdmin"] } }),
});

See also

• feature-reference/secrets for the command surface and dependencies
• custom-fields, the sibling feature with role-scoped write options