Secret Manager
Convex component for encrypted secret vaults and issued API key lifecycle
git clone https://github.com/phantasy-bot/convex-secret-manager.git
cd convex-secret-managerThis upstream package has not been adapted or qualified for Bijection. Read the original documentation before adopting it.
Description
Convex component for encrypted secret vaults and issued API key lifecycle
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: phantasy-bot/convex-secret-manager. License: See repository. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Convex component for encrypted secret vaults and issued API key lifecycle
Explore the demo ↗Upstream overview
From the upstream package documentation.
Secret Manager is a Convex component that combines encrypted secret vaults and issued API key lifecycle management into a single package with per-ownerId tenancy. The vault module stores third-party credentials encrypted at rest using envelope encryption with KEK rotation support, while the issued keys module handles machine token creation, validation, refresh, revocation, and audit trails. It targets multi-tenant backends where a single owner entity needs to hold both external credentials and issued machine tokens.
Use cases
From the upstream package documentation.
- Storing per-organization API keys (OpenAI, Venice, webhook secrets) encrypted at rest with KEK rotation support for a SaaS multi-tenant backend
- Issuing and managing machine tokens with hash-only storage, grace-period rotation, and idle/expiry sweeps for agent or service-to-service authentication
- Building a unified secrets layer for a multi-tenant app where each tenant (org, user, or deployment) needs isolated credential namespaces
- Auditing access and lifecycle events for both stored secrets and issued keys via a paginated audit trail
- Replacing two separate gaganref packages (convex-secret-store and convex-api-keys) when one owner must hold both third-party credentials and issued tokens
How it works
From the upstream package documentation.
Configuration starts in convex/convex.config.ts where you call defineKeys to supply versioned key-encryption-key (KEK) material via environment variables, then attach the component with app.use(secretManager, ...). A SecretManager instance is constructed in your Convex module file by passing components.secretManager, giving you access to both the vault and issued keys APIs.
The vault module exposes vault.putPlaintext for envelope-encrypted writes with additional authenticated data (AAD), vault.getResult for safe reads returning a { ok, value } discriminated union, vault.update for metadata and TTL changes without re-encryption, and vaultRotate.rotate with isRotationComplete for draining KEK rotations. Secrets are scoped by a three-part path: ownerId, namespace, and name.
The issued keys module provides issued.create, issued.validate (a side-effect-free query), issued.touch, issued.revoke, issued.revokeAll, and issued.refresh for grace-period token rotation. Keys use sm_ prefixed tokens with hash-only storage. Both modules include built-in hourly cron sweeps for expired and idle records, plus cleanupKeys, cleanupEvents, and auditEvents.listEvents for operational maintenance and audit review.
Upstream package FAQ
What is the difference between convex-secret-manager and the gaganref convex-secret-store and convex-api-keys packages?
convex-secret-manager combines both gaganref packages into one component and adds per-ownerId tenancy so that vault secrets and issued machine tokens share the same owner scope. The gaganref packages use a namespace plus name path model, while convex-secret-manager uses an ownerId plus namespace plus name path. Use convex-secret-manager when a single owner entity needs to hold both third-party credentials and issued API keys.
How does convex-secret-manager handle encryption for stored secrets?
convex-secret-manager uses envelope encryption with versioned Key Encryption Keys (KEKs) defined via the defineKeys helper in your convex.config.ts. Secrets are encrypted at rest with Additional Authenticated Data (AAD). KEK rotation is supported through vaultRotate.rotate and isRotationComplete, allowing you to drain and re-encrypt secrets under a new key version without downtime. A legacy single-key mode is also supported via the SECRET_MANAGER_ENCRYPTION_KEY environment variable.
How are issued API keys stored and validated in convex-secret-manager?
convex-secret-manager stores only the hash of issued sm_ prefixed tokens, never the plaintext. Validation is performed via a query function (side-effect free), which means it can be called without triggering mutations. The issued keys module also supports token refresh with a grace period, individual and bulk revocation, and paginated listing with effectiveStatus.
Does convex-secret-manager handle cleanup of expired secrets and keys automatically?
Yes. convex-secret-manager includes built-in hourly cron jobs that sweep for expired and idle issued keys, as well as expired vault secrets. Internal jobs cleanupKeys and cleanupEvents handle token and audit event cleanup respectively, and vaultCleanup.cleanupSecrets handles expired secret removal. These crons are registered automatically when you install the component.
How do I set up convex-secret-manager in an existing Convex app?
Install the package with npm install convex-secret-manager, then import and register the component in your convex/convex.config.ts using app.use(secretManager) with your KEK material passed via defineKeys. Instantiate SecretManager in a Convex module file by passing components.secretManager, then set the SECRET_MANAGER_KEYS environment variable on your Convex deployment in the format 1:<kek-material>. See the example directory in the GitHub repository for a minimal Convex plus Vite dashboard walkthrough.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Secret Manager with Bijection.
Read: https://bijection.com/components/convex-secret-manager/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from phantasy-bot/convex-secret-manager, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
convex-secret-manager
Convex component for encrypted secret vaults and issued API key lifecycle.
Combines the roles of gaganref/convex-secret-store and gaganref/convex-api-keys into one package with per-ownerId tenancy. Any Convex app can use it (SaaS orgs, agents, multi-tenant backends).
Two modules
| Module | Use |
|---|---|
| Vault | Store user-supplied credentials (OpenAI, Venice, webhooks) encrypted at rest |
| Issued keys | Issue sm_ machine tokens with hash-only storage, refresh, revoke, and audit |
vs gaganref
| gaganref (2 packages) | convex-secret-manager | |
|---|---|---|
| Path model | namespace + name | ownerId + namespace + name |
| Use case | Generic apps | Multi-tenant backends that issue keys too |
| Install | Two components | One component |
| Vault crypto | Envelope + KEK rotation | Envelope (defineKeys) + legacy single-key |
| Issued validate | Query (side-effect free) | Query |
| Sweeps | Hourly crons | Hourly crons (built-in) |
Use gaganref when you need only one concern. Use this package when one owner should hold both third-party credentials and issued machine tokens.
Install
npm install convex-secret-manager
// convex/convex.config.ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import { defineKeys } from "convex-secret-manager";
import secretManager from "convex-secret-manager/convex.config.js";
const app = defineApp({
env: {
MY_APP_KEK_V1: v.string(),
},
});
app.use(secretManager, {
env: {
SECRET_MANAGER_KEYS: defineKeys({
1: process.env.MY_APP_KEK_V1!,
}),
},
});
export default app;
// convex/secrets.ts
import { SecretManager } from "convex-secret-manager";
import { components } from "./_generated/api.js";
export const secretManager = new SecretManager(components.secretManager);
Set on the Convex deployment:
SECRET_MANAGER_KEYS=1:<kek-material>
# or legacy single key:
SECRET_MANAGER_ENCRYPTION_KEY=...
Vault paths
ownerId = orgId | userId | deployment
namespace = providers | integrations | webhooks
name = openai.apiKey
Issued keys API (parity highlights)
issued.create/validate(query) /touch/revoke/revokeAllissued.refresh— rotate with grace periodissued.update/getKey/list(paginated +effectiveStatus)- Hourly sweep crons for expired and idle keys
cleanupKeys/cleanupEventsinternal jobs
Vault API (parity highlights)
vault.putPlaintext— component-side envelope encryption with AADvault.getResult—{ ok, value } | { ok: false, reason }vault.update— metadata/TTL without re-encryptvault.list— paginated witheffectiveStateauditEvents.listEvents— paginated audit trailvaultRotate.rotate/isRotationComplete— KEK rotation drainvaultCleanup.cleanupSecrets— expired secret cleanup
Example
See example/ for a minimal Convex + Vite dashboard.
License
MIT