---
name: bijection-convex-secret-store
description: "Evaluate and integrate the Convex Secret Store component with Bijection."
---

# Convex Secret Store

Encrypted, namespace-scoped secret storage for Convex with key rotation, expiry, and audit logs.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-secret-store
- Source: https://github.com/gaganref/convex-secret-store
- npm: https://www.npmjs.com/package/convex-secret-store
- Directory: https://bijection.com/components/convex-secret-store

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-secret-store. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex Secret Store. Follow the installation and configuration steps exactly.

# Convex Secret Store

## Instructions

A Convex component that provides encrypted secret storage with envelope encryption, versioned key rotation, and audit logging. It encrypts secrets using per-secret DEKs wrapped with versioned KEKs, allowing key rotation without rewriting encrypted data. The component includes expiry management, namespace-scoped organization, and a typed SecretStore class for use in Convex functions.

### Installation

```bash
npm install convex-secret-store
```

Current npm version: `convex-secret-store@0.2.0`

## Use cases

- **Store API keys per workspace** - Keep OpenAI, Stripe, or other service credentials encrypted and isolated by namespace like `acme:production` vs `acme:testing`
- **Rotate encryption keys without downtime** - Update your master encryption keys and gradually rewrap existing secrets without touching the encrypted payloads
- **Audit secret access patterns** - Track all create, update, delete, and rotate operations with append-only audit events for compliance
- **Expire sensitive credentials automatically** - Set TTL values on secrets and clean up expired data with configurable retention windows
- **Type-safe secret management** - Define TypeScript types for your namespace patterns and metadata schemas to catch errors at compile time

## How it works

The component uses envelope encryption where each secret gets a fresh data encryption key (DEK) that encrypts the plaintext value, then wraps that DEK with a longer-lived key encryption key (KEK) from your configuration. You configure the SecretStore class with your base64-encoded AES keys and use it in Convex queries, mutations, and actions.

The main API methods include `put()` for storing encrypted secrets, `get()` for decrypting them, and `rotateKeys()` for rewrapping DEKs under newer KEKs without touching the encrypted payloads. The component maintains audit events for all operations and supports namespace-scoped organization with optional expiry timestamps.

Key rotation works by keeping multiple key versions in your configuration - the first key encrypts new secrets while older keys remain available for decryption. You run `rotateKeys()` to gradually rewrap existing secrets under the newer key version, then remove the old keys from your config once rotation completes.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Secret Store is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-secret-store)
- [GitHub repository](https://github.com/gaganref/convex-secret-store)
- [Live demo](https://secret-store.convex-toolkit.com)
- [Convex Components Directory](https://www.convex.dev/components/convex-secret-store)
- [Convex documentation](https://docs.convex.dev)