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.
Files changed (94) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +604 -0
  3. package/dist/client/_generated/_ignore.d.ts +1 -0
  4. package/dist/client/_generated/_ignore.d.ts.map +1 -0
  5. package/dist/client/_generated/_ignore.js +3 -0
  6. package/dist/client/_generated/_ignore.js.map +1 -0
  7. package/dist/client/base64.d.ts +3 -0
  8. package/dist/client/base64.d.ts.map +1 -0
  9. package/dist/client/base64.js +32 -0
  10. package/dist/client/base64.js.map +1 -0
  11. package/dist/client/crypto.d.ts +43 -0
  12. package/dist/client/crypto.d.ts.map +1 -0
  13. package/dist/client/crypto.js +133 -0
  14. package/dist/client/crypto.js.map +1 -0
  15. package/dist/client/errors.d.ts +14 -0
  16. package/dist/client/errors.d.ts.map +1 -0
  17. package/dist/client/errors.js +29 -0
  18. package/dist/client/errors.js.map +1 -0
  19. package/dist/client/index.d.ts +6 -0
  20. package/dist/client/index.d.ts.map +1 -0
  21. package/dist/client/index.js +3 -0
  22. package/dist/client/index.js.map +1 -0
  23. package/dist/client/operations.d.ts +88 -0
  24. package/dist/client/operations.d.ts.map +1 -0
  25. package/dist/client/operations.js +388 -0
  26. package/dist/client/operations.js.map +1 -0
  27. package/dist/client/options.d.ts +27 -0
  28. package/dist/client/options.d.ts.map +1 -0
  29. package/dist/client/options.js +66 -0
  30. package/dist/client/options.js.map +1 -0
  31. package/dist/client/types.d.ts +133 -0
  32. package/dist/client/types.d.ts.map +1 -0
  33. package/dist/client/types.js +2 -0
  34. package/dist/client/types.js.map +1 -0
  35. package/dist/component/_generated/api.d.ts +36 -0
  36. package/dist/component/_generated/api.d.ts.map +1 -0
  37. package/dist/component/_generated/api.js +31 -0
  38. package/dist/component/_generated/api.js.map +1 -0
  39. package/dist/component/_generated/component.d.ts +187 -0
  40. package/dist/component/_generated/component.d.ts.map +1 -0
  41. package/dist/component/_generated/component.js +11 -0
  42. package/dist/component/_generated/component.js.map +1 -0
  43. package/dist/component/_generated/dataModel.d.ts +46 -0
  44. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  45. package/dist/component/_generated/dataModel.js +11 -0
  46. package/dist/component/_generated/dataModel.js.map +1 -0
  47. package/dist/component/_generated/server.d.ts +121 -0
  48. package/dist/component/_generated/server.d.ts.map +1 -0
  49. package/dist/component/_generated/server.js +78 -0
  50. package/dist/component/_generated/server.js.map +1 -0
  51. package/dist/component/cleanup.d.ts +27 -0
  52. package/dist/component/cleanup.d.ts.map +1 -0
  53. package/dist/component/cleanup.js +96 -0
  54. package/dist/component/cleanup.js.map +1 -0
  55. package/dist/component/convex.config.d.ts +3 -0
  56. package/dist/component/convex.config.d.ts.map +1 -0
  57. package/dist/component/convex.config.js +3 -0
  58. package/dist/component/convex.config.js.map +1 -0
  59. package/dist/component/lib.d.ts +177 -0
  60. package/dist/component/lib.d.ts.map +1 -0
  61. package/dist/component/lib.js +531 -0
  62. package/dist/component/lib.js.map +1 -0
  63. package/dist/component/schema.d.ts +73 -0
  64. package/dist/component/schema.d.ts.map +1 -0
  65. package/dist/component/schema.js +45 -0
  66. package/dist/component/schema.js.map +1 -0
  67. package/dist/shared.d.ts +7 -0
  68. package/dist/shared.d.ts.map +1 -0
  69. package/dist/shared.js +12 -0
  70. package/dist/shared.js.map +1 -0
  71. package/package.json +115 -0
  72. package/src/client/_generated/_ignore.ts +1 -0
  73. package/src/client/base64.ts +37 -0
  74. package/src/client/crypto.ts +229 -0
  75. package/src/client/errors.ts +64 -0
  76. package/src/client/index.test.ts +480 -0
  77. package/src/client/index.ts +34 -0
  78. package/src/client/operations.ts +513 -0
  79. package/src/client/options.ts +110 -0
  80. package/src/client/setup.test.ts +26 -0
  81. package/src/client/types.ts +213 -0
  82. package/src/component/_generated/api.ts +52 -0
  83. package/src/component/_generated/component.ts +222 -0
  84. package/src/component/_generated/dataModel.ts +60 -0
  85. package/src/component/_generated/server.ts +156 -0
  86. package/src/component/cleanup.test.ts +91 -0
  87. package/src/component/cleanup.ts +124 -0
  88. package/src/component/convex.config.ts +3 -0
  89. package/src/component/lib.test.ts +202 -0
  90. package/src/component/lib.ts +659 -0
  91. package/src/component/schema.ts +48 -0
  92. package/src/component/setup.test.ts +11 -0
  93. package/src/shared.ts +28 -0
  94. package/src/test.ts +18 -0
package/README.md ADDED
@@ -0,0 +1,604 @@
1
+ # Convex Secret Store
2
+
3
+ [![npm version](https://badge.fury.io/js/convex-secret-store.svg)](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,3 @@
1
+ "use strict";
2
+ // This is only here so convex-test can detect a _generated folder
3
+ //# sourceMappingURL=_ignore.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"_ignore.js","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":";AAAA,kEAAkE"}
@@ -0,0 +1,3 @@
1
+ export declare function decodeBase64(input: string): Uint8Array;
2
+ export declare function encodeBase64(bytes: Uint8Array): string;
3
+ //# sourceMappingURL=base64.d.ts.map
@@ -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"}