convex-secret-store 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +604 -0
- package/dist/client/_generated/_ignore.d.ts +1 -0
- package/dist/client/_generated/_ignore.d.ts.map +1 -0
- package/dist/client/_generated/_ignore.js +3 -0
- package/dist/client/_generated/_ignore.js.map +1 -0
- package/dist/client/base64.d.ts +3 -0
- package/dist/client/base64.d.ts.map +1 -0
- package/dist/client/base64.js +32 -0
- package/dist/client/base64.js.map +1 -0
- package/dist/client/crypto.d.ts +43 -0
- package/dist/client/crypto.d.ts.map +1 -0
- package/dist/client/crypto.js +133 -0
- package/dist/client/crypto.js.map +1 -0
- package/dist/client/errors.d.ts +14 -0
- package/dist/client/errors.d.ts.map +1 -0
- package/dist/client/errors.js +29 -0
- package/dist/client/errors.js.map +1 -0
- package/dist/client/index.d.ts +6 -0
- package/dist/client/index.d.ts.map +1 -0
- package/dist/client/index.js +3 -0
- package/dist/client/index.js.map +1 -0
- package/dist/client/operations.d.ts +88 -0
- package/dist/client/operations.d.ts.map +1 -0
- package/dist/client/operations.js +388 -0
- package/dist/client/operations.js.map +1 -0
- package/dist/client/options.d.ts +27 -0
- package/dist/client/options.d.ts.map +1 -0
- package/dist/client/options.js +66 -0
- package/dist/client/options.js.map +1 -0
- package/dist/client/types.d.ts +133 -0
- package/dist/client/types.d.ts.map +1 -0
- package/dist/client/types.js +2 -0
- package/dist/client/types.js.map +1 -0
- package/dist/component/_generated/api.d.ts +36 -0
- package/dist/component/_generated/api.d.ts.map +1 -0
- package/dist/component/_generated/api.js +31 -0
- package/dist/component/_generated/api.js.map +1 -0
- package/dist/component/_generated/component.d.ts +187 -0
- package/dist/component/_generated/component.d.ts.map +1 -0
- package/dist/component/_generated/component.js +11 -0
- package/dist/component/_generated/component.js.map +1 -0
- package/dist/component/_generated/dataModel.d.ts +46 -0
- package/dist/component/_generated/dataModel.d.ts.map +1 -0
- package/dist/component/_generated/dataModel.js +11 -0
- package/dist/component/_generated/dataModel.js.map +1 -0
- package/dist/component/_generated/server.d.ts +121 -0
- package/dist/component/_generated/server.d.ts.map +1 -0
- package/dist/component/_generated/server.js +78 -0
- package/dist/component/_generated/server.js.map +1 -0
- package/dist/component/cleanup.d.ts +27 -0
- package/dist/component/cleanup.d.ts.map +1 -0
- package/dist/component/cleanup.js +96 -0
- package/dist/component/cleanup.js.map +1 -0
- package/dist/component/convex.config.d.ts +3 -0
- package/dist/component/convex.config.d.ts.map +1 -0
- package/dist/component/convex.config.js +3 -0
- package/dist/component/convex.config.js.map +1 -0
- package/dist/component/lib.d.ts +177 -0
- package/dist/component/lib.d.ts.map +1 -0
- package/dist/component/lib.js +531 -0
- package/dist/component/lib.js.map +1 -0
- package/dist/component/schema.d.ts +73 -0
- package/dist/component/schema.d.ts.map +1 -0
- package/dist/component/schema.js +45 -0
- package/dist/component/schema.js.map +1 -0
- package/dist/shared.d.ts +7 -0
- package/dist/shared.d.ts.map +1 -0
- package/dist/shared.js +12 -0
- package/dist/shared.js.map +1 -0
- package/package.json +115 -0
- package/src/client/_generated/_ignore.ts +1 -0
- package/src/client/base64.ts +37 -0
- package/src/client/crypto.ts +229 -0
- package/src/client/errors.ts +64 -0
- package/src/client/index.test.ts +480 -0
- package/src/client/index.ts +34 -0
- package/src/client/operations.ts +513 -0
- package/src/client/options.ts +110 -0
- package/src/client/setup.test.ts +26 -0
- package/src/client/types.ts +213 -0
- package/src/component/_generated/api.ts +52 -0
- package/src/component/_generated/component.ts +222 -0
- package/src/component/_generated/dataModel.ts +60 -0
- package/src/component/_generated/server.ts +156 -0
- package/src/component/cleanup.test.ts +91 -0
- package/src/component/cleanup.ts +124 -0
- package/src/component/convex.config.ts +3 -0
- package/src/component/lib.test.ts +202 -0
- package/src/component/lib.ts +659 -0
- package/src/component/schema.ts +48 -0
- package/src/component/setup.test.ts +11 -0
- package/src/shared.ts +28 -0
- package/src/test.ts +18 -0
package/README.md
ADDED
|
@@ -0,0 +1,604 @@
|
|
|
1
|
+
# Convex Secret Store
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/js/convex-secret-store)
|
|
4
|
+
|
|
5
|
+
<!-- START: Include on https://convex.dev/components -->
|
|
6
|
+
|
|
7
|
+
A [Convex](https://convex.dev) component for encrypted secret storage with
|
|
8
|
+
versioned key rotation, expiry, audit logging, and a typed server-side client.
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
const saved = await secrets.put(ctx, {
|
|
12
|
+
namespace: "acme:production",
|
|
13
|
+
name: "openai",
|
|
14
|
+
value: process.env.OPENAI_API_KEY!,
|
|
15
|
+
metadata: { owner: "platform" },
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
const loaded = await secrets.get(ctx, {
|
|
19
|
+
namespace: "acme:production",
|
|
20
|
+
name: "openai",
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
if (loaded.ok) {
|
|
24
|
+
// loaded.value -> plaintext in memory
|
|
25
|
+
// loaded.metadata -> plaintext metadata
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
What this component gives you:
|
|
30
|
+
|
|
31
|
+
- envelope encryption with a per-secret DEK and versioned KEKs
|
|
32
|
+
- explicit key rotation without rewriting secret plaintext
|
|
33
|
+
- expiry-aware reads and cleanup
|
|
34
|
+
- append-only audit events for create, update, delete, and rotate operations
|
|
35
|
+
- a typed `SecretStore` class for use in Convex queries, mutations, and actions
|
|
36
|
+
|
|
37
|
+
Found a bug? Feature request?
|
|
38
|
+
[File it here](https://github.com/gaganref/convex-secret-store/issues).
|
|
39
|
+
|
|
40
|
+
## Pre-requisite: Convex
|
|
41
|
+
|
|
42
|
+
You'll need an existing Convex project to use this component. Convex is a hosted
|
|
43
|
+
backend platform, including a database, serverless functions, and the generated
|
|
44
|
+
component wiring this package expects. If you haven't used Convex before, the
|
|
45
|
+
[Convex tutorial](https://docs.convex.dev/get-started) is a good place to start.
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
npm install convex-secret-store
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Install the component in your app's `convex.config.ts`:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
// convex/convex.config.ts
|
|
57
|
+
import { defineApp } from "convex/server";
|
|
58
|
+
import secretStore from "convex-secret-store/convex.config.js";
|
|
59
|
+
|
|
60
|
+
const app = defineApp();
|
|
61
|
+
app.use(secretStore);
|
|
62
|
+
|
|
63
|
+
export default app;
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Quick Start
|
|
67
|
+
|
|
68
|
+
Create a shared `SecretStore` instance:
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
// convex/secrets.ts
|
|
72
|
+
import { SecretStore } from "convex-secret-store";
|
|
73
|
+
import { components } from "./_generated/api.js";
|
|
74
|
+
|
|
75
|
+
export const secrets = new SecretStore<{
|
|
76
|
+
namespace: `${string}:${"production" | "testing"}`;
|
|
77
|
+
metadata: { owner?: string; label?: string; notes?: string };
|
|
78
|
+
}>(components.secretStore, {
|
|
79
|
+
keys: [
|
|
80
|
+
{ version: 2, value: process.env.SECRET_STORE_KEY_V2! },
|
|
81
|
+
{ version: 1, value: process.env.SECRET_STORE_KEY_V1! },
|
|
82
|
+
],
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Use it inside your Convex functions:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
// convex/integrations.ts
|
|
90
|
+
import { mutation, action } from "./_generated/server.js";
|
|
91
|
+
import { v } from "convex/values";
|
|
92
|
+
import { secrets } from "./secrets.js";
|
|
93
|
+
|
|
94
|
+
export const putOpenAIKey = mutation({
|
|
95
|
+
args: {
|
|
96
|
+
workspace: v.string(),
|
|
97
|
+
value: v.string(),
|
|
98
|
+
},
|
|
99
|
+
handler: async (ctx, args) => {
|
|
100
|
+
return await secrets.put(ctx, {
|
|
101
|
+
namespace: `${args.workspace}:production`,
|
|
102
|
+
name: "openai",
|
|
103
|
+
value: args.value,
|
|
104
|
+
metadata: { owner: "platform" },
|
|
105
|
+
});
|
|
106
|
+
},
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
export const callProvider = action({
|
|
110
|
+
args: { workspace: v.string() },
|
|
111
|
+
handler: async (ctx, args) => {
|
|
112
|
+
const secret = await secrets.get(ctx, {
|
|
113
|
+
namespace: `${args.workspace}:production`,
|
|
114
|
+
name: "openai",
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
if (!secret.ok) {
|
|
118
|
+
throw new Error(`Secret unavailable: ${secret.reason}`);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
authHeaderPreview: `Bearer ${secret.value.slice(0, 4)}...`,
|
|
123
|
+
};
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## How It Works
|
|
129
|
+
|
|
130
|
+
Each stored secret uses two encryption layers:
|
|
131
|
+
|
|
132
|
+
- **DEK**: a fresh random data-encryption key generated per secret value
|
|
133
|
+
- **KEK**: a longer-lived key-encryption key from your configured `keys`
|
|
134
|
+
|
|
135
|
+
When you call `put`:
|
|
136
|
+
|
|
137
|
+
1. the plaintext value is encrypted with a fresh DEK
|
|
138
|
+
2. that DEK is wrapped with the active KEK
|
|
139
|
+
3. Convex stores:
|
|
140
|
+
- `encryptedValue`
|
|
141
|
+
- `iv`
|
|
142
|
+
- `wrappedDEK`
|
|
143
|
+
- `dekIv`
|
|
144
|
+
- `keyVersion`
|
|
145
|
+
|
|
146
|
+
When you call `get`:
|
|
147
|
+
|
|
148
|
+
1. the row is loaded from Convex
|
|
149
|
+
2. the stored `keyVersion` selects the correct KEK
|
|
150
|
+
3. the DEK is unwrapped
|
|
151
|
+
4. the secret value is decrypted in memory
|
|
152
|
+
|
|
153
|
+
When you rotate keys:
|
|
154
|
+
|
|
155
|
+
- the encrypted secret value does **not** change
|
|
156
|
+
- only the wrapped DEK layer is re-encrypted under a newer KEK
|
|
157
|
+
|
|
158
|
+
This is standard envelope-encryption behavior and keeps key rotation cheaper
|
|
159
|
+
than full plaintext re-encryption.
|
|
160
|
+
|
|
161
|
+
## Key Material
|
|
162
|
+
|
|
163
|
+
`keys` must contain base64-encoded 32-byte AES keys.
|
|
164
|
+
|
|
165
|
+
Generate one with:
|
|
166
|
+
|
|
167
|
+
```sh
|
|
168
|
+
openssl rand -base64 32
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Rules:
|
|
172
|
+
|
|
173
|
+
- the first entry is the active key used for new writes
|
|
174
|
+
- later entries are decrypt-only keys used for old rows
|
|
175
|
+
- versions must be unique non-negative integers
|
|
176
|
+
- empty-string namespaces are rejected
|
|
177
|
+
|
|
178
|
+
## Typed Options
|
|
179
|
+
|
|
180
|
+
The `SecretStore` class accepts a generic parameter for type-safe namespaces and
|
|
181
|
+
metadata:
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
export const secrets = new SecretStore<{
|
|
185
|
+
namespace: `${string}:${"production" | "testing"}`;
|
|
186
|
+
metadata: {
|
|
187
|
+
owner?: string;
|
|
188
|
+
label?: string;
|
|
189
|
+
notes?: string;
|
|
190
|
+
};
|
|
191
|
+
}>(components.secretStore, {
|
|
192
|
+
keys: [{ version: 1, value: process.env.SECRET_STORE_KEY_V1! }],
|
|
193
|
+
defaults: {
|
|
194
|
+
ttlMs: 30 * 24 * 60 * 60 * 1000,
|
|
195
|
+
},
|
|
196
|
+
logLevel: "warn",
|
|
197
|
+
});
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Type options:
|
|
201
|
+
|
|
202
|
+
- `namespace` — any `string` subtype. When set, `namespace` becomes required on
|
|
203
|
+
normal read/write/list operations.
|
|
204
|
+
- `metadata` — shape of the plaintext metadata object stored with each secret.
|
|
205
|
+
|
|
206
|
+
> **Note:** These are compile-time type constraints only. Runtime storage is
|
|
207
|
+
> still flexible:
|
|
208
|
+
>
|
|
209
|
+
> - `namespace` → `v.optional(v.string())`
|
|
210
|
+
> - `metadata` → `v.optional(v.record(v.string(), v.any()))`
|
|
211
|
+
>
|
|
212
|
+
> Existing stored rows are not migrated if you later change your TypeScript
|
|
213
|
+
> types.
|
|
214
|
+
|
|
215
|
+
## Usage
|
|
216
|
+
|
|
217
|
+
### Put
|
|
218
|
+
|
|
219
|
+
Encrypt and store a secret value:
|
|
220
|
+
|
|
221
|
+
```ts
|
|
222
|
+
const result = await secrets.put(ctx, {
|
|
223
|
+
namespace: "acme:production",
|
|
224
|
+
name: "stripe",
|
|
225
|
+
value: "sk_live_...",
|
|
226
|
+
metadata: { owner: "billing" },
|
|
227
|
+
ttlMs: 90 * 24 * 60 * 60 * 1000,
|
|
228
|
+
});
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Notes:
|
|
232
|
+
|
|
233
|
+
- `ttlMs` is converted to an absolute `expiresAt`
|
|
234
|
+
- when overwriting and omitting `metadata` or `ttlMs`, existing metadata and
|
|
235
|
+
expiry are preserved
|
|
236
|
+
- use `update(..., { metadata: null, expiresAt: null })` to clear optional
|
|
237
|
+
fields
|
|
238
|
+
|
|
239
|
+
### Get
|
|
240
|
+
|
|
241
|
+
Load and decrypt a secret:
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
const result = await secrets.get(ctx, {
|
|
245
|
+
namespace: "acme:production",
|
|
246
|
+
name: "stripe",
|
|
247
|
+
});
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
`get` returns:
|
|
251
|
+
|
|
252
|
+
- `{ ok: true, value, metadata, expiresAt, updatedAt }`
|
|
253
|
+
- `{ ok: false, reason: "not_found" | "expired" | "key_version_unavailable" }`
|
|
254
|
+
|
|
255
|
+
`key_version_unavailable` means the row exists, but the runtime no longer has
|
|
256
|
+
the KEK version needed to unwrap it.
|
|
257
|
+
|
|
258
|
+
### Has
|
|
259
|
+
|
|
260
|
+
Check whether a usable secret exists:
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
const exists = await secrets.has(ctx, {
|
|
264
|
+
namespace: "acme:production",
|
|
265
|
+
name: "stripe",
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Expired secrets return `false`.
|
|
270
|
+
|
|
271
|
+
### Update
|
|
272
|
+
|
|
273
|
+
Update plaintext metadata or expiry without rewriting the encrypted value:
|
|
274
|
+
|
|
275
|
+
```ts
|
|
276
|
+
await secrets.update(ctx, {
|
|
277
|
+
namespace: "acme:production",
|
|
278
|
+
name: "stripe",
|
|
279
|
+
metadata: { owner: "finance", label: "primary" },
|
|
280
|
+
expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
|
|
281
|
+
});
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Pass `null` to clear metadata or expiry entirely.
|
|
285
|
+
|
|
286
|
+
### Remove
|
|
287
|
+
|
|
288
|
+
Delete a secret and append a matching audit event:
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
await secrets.remove(ctx, {
|
|
292
|
+
namespace: "acme:production",
|
|
293
|
+
name: "stripe",
|
|
294
|
+
});
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
### List
|
|
298
|
+
|
|
299
|
+
Paginate secrets in one namespace:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
const page = await secrets.list(ctx, {
|
|
303
|
+
namespace: "acme:production",
|
|
304
|
+
order: "desc",
|
|
305
|
+
paginationOpts: { numItems: 20, cursor: null },
|
|
306
|
+
});
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Notes:
|
|
310
|
+
|
|
311
|
+
- rows are ordered by `updatedAt`
|
|
312
|
+
- expired rows are still listed
|
|
313
|
+
- each row includes `effectiveState: "active" | "expired"`
|
|
314
|
+
|
|
315
|
+
### List Events
|
|
316
|
+
|
|
317
|
+
Paginate audit events:
|
|
318
|
+
|
|
319
|
+
```ts
|
|
320
|
+
const events = await secrets.listEvents(ctx, {
|
|
321
|
+
namespace: "acme:production",
|
|
322
|
+
paginationOpts: { numItems: 50, cursor: null },
|
|
323
|
+
});
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
You can also filter by `name`, `type`, or by `secretId`.
|
|
327
|
+
|
|
328
|
+
V1 restrictions:
|
|
329
|
+
|
|
330
|
+
- `name` and `type` cannot be combined
|
|
331
|
+
- when filtering by `name` or `type`, `namespace` is required
|
|
332
|
+
- `secretId` cannot be combined with `namespace`, `name`, or `type`
|
|
333
|
+
|
|
334
|
+
### Rotate Keys
|
|
335
|
+
|
|
336
|
+
Rewrap old rows from one key version to the active version:
|
|
337
|
+
|
|
338
|
+
```ts
|
|
339
|
+
const result = await secrets.rotateKeys(ctx, {
|
|
340
|
+
fromVersion: 1,
|
|
341
|
+
batchSize: 100,
|
|
342
|
+
cursor: null,
|
|
343
|
+
});
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Result fields:
|
|
347
|
+
|
|
348
|
+
- `fromVersion`
|
|
349
|
+
- `toVersion`
|
|
350
|
+
- `processed`
|
|
351
|
+
- `rotated`
|
|
352
|
+
- `skipped`
|
|
353
|
+
- `isDone`
|
|
354
|
+
- `continueCursor`
|
|
355
|
+
|
|
356
|
+
Important semantics:
|
|
357
|
+
|
|
358
|
+
- rotation rewraps DEKs only
|
|
359
|
+
- the encrypted secret plaintext is not rewritten
|
|
360
|
+
- concurrent writes are protected with compare-and-swap checks
|
|
361
|
+
- stale rows are skipped safely and can be retried in a later batch
|
|
362
|
+
- do not remove an old KEK until rotation is fully drained
|
|
363
|
+
|
|
364
|
+
### Cleanup Expired Secrets
|
|
365
|
+
|
|
366
|
+
Hard-delete secrets that have remained expired past the retention window:
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
const result = await secrets.cleanupSecrets(ctx, {
|
|
370
|
+
retentionMs: 30 * 24 * 60 * 60 * 1000,
|
|
371
|
+
});
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
What `cleanupSecrets` does:
|
|
375
|
+
|
|
376
|
+
- deletes expired secret rows once they are older than the retention window
|
|
377
|
+
- writes a final `deleted` audit event with `deletedReason: "expired_cleanup"`
|
|
378
|
+
- processes up to 100 rows per run and automatically reschedules itself while
|
|
379
|
+
backlog remains
|
|
380
|
+
|
|
381
|
+
### Cleanup Audit Events
|
|
382
|
+
|
|
383
|
+
Hard-delete audit events older than the retention window:
|
|
384
|
+
|
|
385
|
+
```ts
|
|
386
|
+
const result = await secrets.cleanupEvents(ctx, {
|
|
387
|
+
retentionMs: 180 * 24 * 60 * 60 * 1000,
|
|
388
|
+
});
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
What `cleanupEvents` does:
|
|
392
|
+
|
|
393
|
+
- deletes audit rows independently from secret cleanup
|
|
394
|
+
- lets audit history outlive expired secrets when you want longer retention
|
|
395
|
+
- processes up to 100 rows per run and automatically reschedules itself while
|
|
396
|
+
backlog remains
|
|
397
|
+
|
|
398
|
+
Recommended host-app pattern:
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
// convex/cleanup.ts
|
|
402
|
+
import { internalMutation } from "./_generated/server";
|
|
403
|
+
import { secrets } from "./secrets";
|
|
404
|
+
|
|
405
|
+
export const cleanupSecrets = internalMutation({
|
|
406
|
+
handler: (ctx) =>
|
|
407
|
+
secrets.cleanupSecrets(ctx, {
|
|
408
|
+
retentionMs: 30 * 24 * 60 * 60 * 1000,
|
|
409
|
+
}),
|
|
410
|
+
});
|
|
411
|
+
|
|
412
|
+
export const cleanupEvents = internalMutation({
|
|
413
|
+
handler: (ctx) =>
|
|
414
|
+
secrets.cleanupEvents(ctx, {
|
|
415
|
+
retentionMs: 180 * 24 * 60 * 60 * 1000,
|
|
416
|
+
}),
|
|
417
|
+
});
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
```ts
|
|
421
|
+
// convex/crons.ts
|
|
422
|
+
import { cronJobs } from "convex/server";
|
|
423
|
+
import { internal } from "./_generated/api";
|
|
424
|
+
|
|
425
|
+
const crons = cronJobs();
|
|
426
|
+
|
|
427
|
+
crons.interval(
|
|
428
|
+
"cleanup expired secrets",
|
|
429
|
+
{ hours: 24 },
|
|
430
|
+
internal.cleanup.cleanupSecrets,
|
|
431
|
+
);
|
|
432
|
+
crons.interval(
|
|
433
|
+
"cleanup secret audit events",
|
|
434
|
+
{ hours: 24 },
|
|
435
|
+
internal.cleanup.cleanupEvents,
|
|
436
|
+
);
|
|
437
|
+
|
|
438
|
+
export default crons;
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
## Rotation Workflow
|
|
442
|
+
|
|
443
|
+
`keys[0]` is the active write key. Any remaining entries are older decrypt-only
|
|
444
|
+
keys.
|
|
445
|
+
|
|
446
|
+
```ts
|
|
447
|
+
keys: [
|
|
448
|
+
{ version: 3, value: process.env.SECRET_STORE_KEY_V3! }, // active
|
|
449
|
+
{ version: 2, value: process.env.SECRET_STORE_KEY_V2! }, // decrypt-only
|
|
450
|
+
{ version: 1, value: process.env.SECRET_STORE_KEY_V1! }, // decrypt-only
|
|
451
|
+
];
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
Recommended flow:
|
|
455
|
+
|
|
456
|
+
1. prepend a new key version to `keys`
|
|
457
|
+
2. deploy so new writes start using that version
|
|
458
|
+
3. run rotation for each older version you want to drain
|
|
459
|
+
4. keep old keys configured until those rows are fully rotated
|
|
460
|
+
5. deploy again with drained old versions removed
|
|
461
|
+
|
|
462
|
+
Recommended host-app wrappers:
|
|
463
|
+
|
|
464
|
+
See [`example/convex/rotate.ts`](./example/convex/rotate.ts) for a working
|
|
465
|
+
version of this pattern.
|
|
466
|
+
|
|
467
|
+
```ts
|
|
468
|
+
// convex/rotate.ts
|
|
469
|
+
import { v } from "convex/values";
|
|
470
|
+
import { internalAction, type ActionCtx } from "./_generated/server";
|
|
471
|
+
import { secrets } from "./secrets";
|
|
472
|
+
|
|
473
|
+
async function rotateVersion(ctx: ActionCtx, fromVersion: number) {
|
|
474
|
+
let cursor: string | null = null;
|
|
475
|
+
|
|
476
|
+
while (true) {
|
|
477
|
+
const result = await secrets.rotateKeys(ctx, {
|
|
478
|
+
fromVersion,
|
|
479
|
+
batchSize: 100,
|
|
480
|
+
cursor,
|
|
481
|
+
});
|
|
482
|
+
|
|
483
|
+
if (result.isDone) {
|
|
484
|
+
return result;
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
cursor = result.continueCursor ?? null;
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
export const rotateSecretStoreVersion = internalAction({
|
|
492
|
+
args: { fromVersion: v.number() },
|
|
493
|
+
handler: async (ctx, args) => {
|
|
494
|
+
return await rotateVersion(ctx, args.fromVersion);
|
|
495
|
+
},
|
|
496
|
+
});
|
|
497
|
+
|
|
498
|
+
export const rotateSecretStoreToLatest = internalAction({
|
|
499
|
+
handler: async (ctx) => {
|
|
500
|
+
for (const fromVersion of [2, 1]) {
|
|
501
|
+
await rotateVersion(ctx, fromVersion);
|
|
502
|
+
}
|
|
503
|
+
},
|
|
504
|
+
});
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Optional temporary cron during a rotation window:
|
|
508
|
+
|
|
509
|
+
```ts
|
|
510
|
+
// convex/crons.ts
|
|
511
|
+
import { cronJobs } from "convex/server";
|
|
512
|
+
import { internal } from "./_generated/api";
|
|
513
|
+
|
|
514
|
+
const crons = cronJobs();
|
|
515
|
+
|
|
516
|
+
crons.interval(
|
|
517
|
+
"drain secret-store old keys",
|
|
518
|
+
{ minutes: 10 },
|
|
519
|
+
internal.rotate.rotateSecretStoreToLatest,
|
|
520
|
+
);
|
|
521
|
+
|
|
522
|
+
export default crons;
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
Cleanup is a good permanent cron. Rotation is usually a temporary cron or a
|
|
526
|
+
manual admin action during a migration window.
|
|
527
|
+
|
|
528
|
+
This component does not use explicit locks during rotation. Instead, it uses
|
|
529
|
+
optimistic concurrency checks so concurrent writes do not corrupt rows. If a row
|
|
530
|
+
changes while rotation is in flight, the rewrap attempt is skipped safely and
|
|
531
|
+
retried by a later pass. A restart scan may return `continueCursor: null`; keep
|
|
532
|
+
looping until `isDone === true`.
|
|
533
|
+
|
|
534
|
+
## Security Model
|
|
535
|
+
|
|
536
|
+
- **Envelope encryption** — each secret gets its own random DEK, wrapped by a
|
|
537
|
+
configured KEK.
|
|
538
|
+
- **Exact key version lookup** — reads use the stored `keyVersion`; they do not
|
|
539
|
+
probe multiple keys.
|
|
540
|
+
- **AAD binding** — ciphertext is bound to `namespace`, `name`, and
|
|
541
|
+
`keyVersion`, so moving ciphertext between rows should fail authentication.
|
|
542
|
+
- **No backend KEKs** — the Convex component stores ciphertext only. KEKs live
|
|
543
|
+
in the host app runtime using the `SecretStore` client.
|
|
544
|
+
- **Plaintext metadata** — `metadata`, `namespace`, `name`, expiry, and audit
|
|
545
|
+
metadata are not encrypted.
|
|
546
|
+
|
|
547
|
+
Important limitations:
|
|
548
|
+
|
|
549
|
+
- this protects secrets at rest in Convex, not against a compromised app runtime
|
|
550
|
+
- any code with access to your configured KEKs can decrypt secrets
|
|
551
|
+
- plaintext exists in memory while your server-side code uses it
|
|
552
|
+
- do not store sensitive data in metadata fields
|
|
553
|
+
|
|
554
|
+
## Configuration Options
|
|
555
|
+
|
|
556
|
+
Pass options when constructing the client:
|
|
557
|
+
|
|
558
|
+
```ts
|
|
559
|
+
new SecretStore(components.secretStore, {
|
|
560
|
+
keys: [{ version: 1, value: process.env.SECRET_STORE_KEY_V1! }],
|
|
561
|
+
defaults: {
|
|
562
|
+
ttlMs: null,
|
|
563
|
+
},
|
|
564
|
+
logLevel: "warn",
|
|
565
|
+
});
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
Options:
|
|
569
|
+
|
|
570
|
+
- `keys` — required versioned KEKs
|
|
571
|
+
- `defaults.ttlMs` — default secret TTL in milliseconds
|
|
572
|
+
- `logLevel` — `"debug" | "warn" | "error" | "none"`
|
|
573
|
+
|
|
574
|
+
## Example App
|
|
575
|
+
|
|
576
|
+
See the [example/](./example) directory for a full reference app called **Secret
|
|
577
|
+
Store**.
|
|
578
|
+
|
|
579
|
+
It demonstrates:
|
|
580
|
+
|
|
581
|
+
- `Secrets` — store, replace, preview, and remove environment secrets
|
|
582
|
+
- `Activity` — audit history
|
|
583
|
+
- `Settings` — key rotation, cleanup, and demo seeding flows
|
|
584
|
+
|
|
585
|
+
> **Security note:** The example app keeps secret management intentionally
|
|
586
|
+
> simple. In a real app, gate secret write/read flows behind your authentication
|
|
587
|
+
> and authorization layer before exposing them to operators.
|
|
588
|
+
|
|
589
|
+
## Development
|
|
590
|
+
|
|
591
|
+
```sh
|
|
592
|
+
npm i
|
|
593
|
+
npm run dev
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
Useful commands:
|
|
597
|
+
|
|
598
|
+
```sh
|
|
599
|
+
npm run typecheck
|
|
600
|
+
npm run lint
|
|
601
|
+
npm test
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
<!-- END: Include on https://convex.dev/components -->
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
//# sourceMappingURL=_ignore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"_ignore.d.ts","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"_ignore.js","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":";AAAA,kEAAkE"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/client/base64.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAoBtD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYtD"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { invalidArgumentError, runtimeUnavailableError } from "./errors.js";
|
|
2
|
+
export function decodeBase64(input) {
|
|
3
|
+
const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
|
|
4
|
+
const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4 || 4)) % 4), "=");
|
|
5
|
+
try {
|
|
6
|
+
if (typeof atob === "function") {
|
|
7
|
+
const decoded = atob(padded);
|
|
8
|
+
return Uint8Array.from(decoded, (char) => char.charCodeAt(0));
|
|
9
|
+
}
|
|
10
|
+
if (typeof Buffer !== "undefined") {
|
|
11
|
+
return Uint8Array.from(Buffer.from(padded, "base64"));
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
catch (error) {
|
|
15
|
+
throw invalidArgumentError(`invalid base64 data: ${String(error)}`);
|
|
16
|
+
}
|
|
17
|
+
throw runtimeUnavailableError("base64 decoding is unavailable");
|
|
18
|
+
}
|
|
19
|
+
export function encodeBase64(bytes) {
|
|
20
|
+
if (typeof btoa === "function") {
|
|
21
|
+
let binary = "";
|
|
22
|
+
for (const byte of bytes) {
|
|
23
|
+
binary += String.fromCharCode(byte);
|
|
24
|
+
}
|
|
25
|
+
return btoa(binary);
|
|
26
|
+
}
|
|
27
|
+
if (typeof Buffer !== "undefined") {
|
|
28
|
+
return Buffer.from(bytes).toString("base64");
|
|
29
|
+
}
|
|
30
|
+
throw runtimeUnavailableError("base64 encoding is unavailable");
|
|
31
|
+
}
|
|
32
|
+
//# sourceMappingURL=base64.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base64.js","sourceRoot":"","sources":["../../src/client/base64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE5E,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAC9B,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAC5D,GAAG,CACJ,CAAC;IAEF,IAAI,CAAC;QACH,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,oBAAoB,CAAC,wBAAwB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,uBAAuB,CAAC,gCAAgC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,uBAAuB,CAAC,gCAAgC,CAAC,CAAC;AAClE,CAAC"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export declare function base64UrlEncode(bytes: Uint8Array): string;
|
|
2
|
+
export declare function base64UrlDecode(input: string): Uint8Array;
|
|
3
|
+
export declare function buildValueAAD(namespace: string | undefined, name: string): Uint8Array;
|
|
4
|
+
export declare function buildDekAAD(namespace: string | undefined, name: string, keyVersion: number): Uint8Array;
|
|
5
|
+
export declare function importKey(rawKeyBase64: string): Promise<CryptoKey>;
|
|
6
|
+
export declare function generateDEK(): Uint8Array;
|
|
7
|
+
export declare function generateIV(): Uint8Array;
|
|
8
|
+
export declare function encryptSecret(params: {
|
|
9
|
+
value: string;
|
|
10
|
+
namespace: string | undefined;
|
|
11
|
+
name: string;
|
|
12
|
+
keyVersion: number;
|
|
13
|
+
kek: CryptoKey;
|
|
14
|
+
}): Promise<{
|
|
15
|
+
encryptedValue: string;
|
|
16
|
+
iv: string;
|
|
17
|
+
wrappedDEK: string;
|
|
18
|
+
dekIv: string;
|
|
19
|
+
}>;
|
|
20
|
+
export declare function decryptSecret(params: {
|
|
21
|
+
encryptedValue: string;
|
|
22
|
+
iv: string;
|
|
23
|
+
wrappedDEK: string;
|
|
24
|
+
dekIv: string;
|
|
25
|
+
namespace: string | undefined;
|
|
26
|
+
name: string;
|
|
27
|
+
keyVersion: number;
|
|
28
|
+
kek: CryptoKey;
|
|
29
|
+
}): Promise<string>;
|
|
30
|
+
export declare function rewrapDEK(params: {
|
|
31
|
+
wrappedDEK: string;
|
|
32
|
+
dekIv: string;
|
|
33
|
+
namespace: string | undefined;
|
|
34
|
+
name: string;
|
|
35
|
+
fromVersion: number;
|
|
36
|
+
toVersion: number;
|
|
37
|
+
fromKek: CryptoKey;
|
|
38
|
+
toKek: CryptoKey;
|
|
39
|
+
}): Promise<{
|
|
40
|
+
wrappedDEK: string;
|
|
41
|
+
dekIv: string;
|
|
42
|
+
}>;
|
|
43
|
+
//# sourceMappingURL=crypto.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/client/crypto.ts"],"names":[],"mappings":"AAsBA,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKzD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAEzD;AAUD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,GACX,UAAU,CAIZ;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,UAAU,CAIZ;AAED,wBAAsB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAYxE;AAED,wBAAgB,WAAW,IAAI,UAAU,CAIxC;AAED,wBAAgB,UAAU,IAAI,UAAU,CAIvC;AAgDD,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CA0BD;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlB;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBjD"}
|