Convex Secret Store

Copy codeconst saved = await secrets.put(ctx, {
  namespace: "acme:production",
  name: "openai",
  value: process.env.OPENAI_API_KEY!,
  metadata: { owner: "platform" },
});

const loaded = await secrets.get(ctx, {
  namespace: "acme:production",
  name: "openai",
});

if (loaded.ok) {
  // loaded.value -> plaintext in memory
  // loaded.metadata -> plaintext metadata
}

Copy codenpm install convex-secret-store

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import secretStore from "convex-secret-store/convex.config.js";

const app = defineApp();
app.use(secretStore);

export default app;

Copy code// convex/secrets.ts
import { SecretStore } from "convex-secret-store";
import { components } from "./_generated/api.js";

export const secrets = new SecretStore<{
  namespace: `${string}:${"production" | "testing"}`;
  metadata: { owner?: string; label?: string; notes?: string };
}>(components.secretStore, {
  keys: [
    { version: 2, value: process.env.SECRET_STORE_KEY_V2! },
    { version: 1, value: process.env.SECRET_STORE_KEY_V1! },
  ],
});

Copy code// convex/integrations.ts
import { mutation, action } from "./_generated/server.js";
import { v } from "convex/values";
import { secrets } from "./secrets.js";

export const putOpenAIKey = mutation({
  args: {
    workspace: v.string(),
    value: v.string(),
  },
  handler: async (ctx, args) => {
    return await secrets.put(ctx, {
      namespace: `${args.workspace}:production`,
      name: "openai",
      value: args.value,
      metadata: { owner: "platform" },
    });
  },
});

export const callProvider = action({
  args: { workspace: v.string() },
  handler: async (ctx, args) => {
    const secret = await secrets.get(ctx, {
      namespace: `${args.workspace}:production`,
      name: "openai",
    });

    if (!secret.ok) {
      throw new Error(`Secret unavailable: ${secret.reason}`);
    }

    return {
      authHeaderPreview: `Bearer ${secret.value.slice(0, 4)}...`,
    };
  },
});

Copy codeopenssl rand -base64 32

Copy codeexport const secrets = new SecretStore<{
  namespace: `${string}:${"production" | "testing"}`;
  metadata: {
    owner?: string;
    label?: string;
    notes?: string;
  };
}>(components.secretStore, {
  keys: [{ version: 1, value: process.env.SECRET_STORE_KEY_V1! }],
  defaults: {
    ttlMs: 30 * 24 * 60 * 60 * 1000,
  },
  logLevel: "warn",
});

Copy codeconst result = await secrets.put(ctx, {
  namespace: "acme:production",
  name: "stripe",
  value: "sk_live_...",
  metadata: { owner: "billing" },
  ttlMs: 90 * 24 * 60 * 60 * 1000,
});

Copy codeconst result = await secrets.get(ctx, {
  namespace: "acme:production",
  name: "stripe",
});

Copy codeconst exists = await secrets.has(ctx, {
  namespace: "acme:production",
  name: "stripe",
});

Copy codeawait secrets.update(ctx, {
  namespace: "acme:production",
  name: "stripe",
  metadata: { owner: "finance", label: "primary" },
  expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
});

Copy codeawait secrets.remove(ctx, {
  namespace: "acme:production",
  name: "stripe",
});

Copy codeconst page = await secrets.list(ctx, {
  namespace: "acme:production",
  order: "desc",
  paginationOpts: { numItems: 20, cursor: null },
});

Copy codeconst events = await secrets.listEvents(ctx, {
  namespace: "acme:production",
  paginationOpts: { numItems: 50, cursor: null },
});

Copy codeconst result = await secrets.rotateKeys(ctx, {
  fromVersion: 1,
  batchSize: 100,
  cursor: null,
});

Copy codeconst result = await secrets.cleanupSecrets(ctx, {
  retentionMs: 30 * 24 * 60 * 60 * 1000,
});

Copy codeconst result = await secrets.cleanupEvents(ctx, {
  retentionMs: 180 * 24 * 60 * 60 * 1000,
});

Copy code// convex/cleanup.ts
import { internalMutation } from "./_generated/server";
import { secrets } from "./secrets";

export const cleanupSecrets = internalMutation({
  handler: (ctx) =>
    secrets.cleanupSecrets(ctx, {
      retentionMs: 30 * 24 * 60 * 60 * 1000,
    }),
});

export const cleanupEvents = internalMutation({
  handler: (ctx) =>
    secrets.cleanupEvents(ctx, {
      retentionMs: 180 * 24 * 60 * 60 * 1000,
    }),
});

Copy code// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

crons.interval(
  "cleanup expired secrets",
  { hours: 24 },
  internal.cleanup.cleanupSecrets,
);
crons.interval(
  "cleanup secret audit events",
  { hours: 24 },
  internal.cleanup.cleanupEvents,
);

export default crons;

Copy codekeys: [
  { version: 3, value: process.env.SECRET_STORE_KEY_V3! }, // active
  { version: 2, value: process.env.SECRET_STORE_KEY_V2! }, // decrypt-only
  { version: 1, value: process.env.SECRET_STORE_KEY_V1! }, // decrypt-only
];

Copy code// convex/rotate.ts
import { v } from "convex/values";
import { internalAction, type ActionCtx } from "./_generated/server";
import { secrets } from "./secrets";

async function rotateVersion(ctx: ActionCtx, fromVersion: number) {
  let cursor: string | null = null;

  while (true) {
    const result = await secrets.rotateKeys(ctx, {
      fromVersion,
      batchSize: 100,
      cursor,
    });

    if (result.isDone) {
      return result;
    }

    cursor = result.continueCursor ?? null;
  }
}

export const rotateSecretStoreVersion = internalAction({
  args: { fromVersion: v.number() },
  handler: async (ctx, args) => {
    return await rotateVersion(ctx, args.fromVersion);
  },
});

export const rotateSecretStoreToLatest = internalAction({
  handler: async (ctx) => {
    for (const fromVersion of [2, 1]) {
      await rotateVersion(ctx, fromVersion);
    }
  },
});

Copy code// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

crons.interval(
  "drain secret-store old keys",
  { minutes: 10 },
  internal.rotate.rotateSecretStoreToLa

[README truncated for prompt length]