The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 144 lines 4.16 KB
Raw
1 ---
2 title: Secret Manager & KMS
3 description: Keep API keys in Secret Manager and read them per request, encrypt data with Cloud KMS, and pass plain config through env.
4 ---
5
6 Plain config goes in `env`. Credentials go in Secret Manager, which the
7 service reads while it runs. Data you need to encrypt goes through
8 Cloud KMS, so your code never holds a key.
9
10 ## Plain config
11
12 Values that aren't secret go on the service as environment variables:
13
14 ```typescript
15 { main: import.meta.url, env: { LOG_LEVEL: "info" } }
16 ```
17
18 The service reads `process.env.LOG_LEVEL`.
19
20 ## Create a secret
21
22 ```typescript
23 // src/resources.ts
24 import * as GCP from "@alchemy.run/gcp";
25
26 export const ApiKey = GCP.SecretManager.Secret("ApiKey", {});
27 ```
28
29 Alchemy creates the secret, not its value. Add the value yourself, so
30 it never passes through your Stack or deploy logs:
31
32 ```sh
33 printf 'my-key' | gcloud secrets versions add "$SECRET_ID" --data-file=-
34 ```
35
36 Return `ApiKey.secretId` from your Stack to get `$SECRET_ID`.
37
38 ## Read it per request
39
40 `ReadSecret` returns `access()`, which reads the latest version as a
41 string:
42
43 ```typescript
44 // src/Api.ts
45 import * as GCP from "@alchemy.run/gcp";
46 import * as Effect from "effect/Effect";
47 import { HttpServerRequest } from "effect/http/HttpServerRequest";
48 import * as HttpServerResponse from "effect/http/HttpServerResponse";
49 import { ApiKey } from "./resources.ts";
50
51 export default class Api extends GCP.Function<Api>()(
52 "Api",
53 { main: import.meta.url, invokerIamDisabled: true },
54 Effect.gen(function* () {
55 const key = yield* GCP.SecretManager.ReadSecret(ApiKey);
56
57 return {
58 fetch: Effect.gen(function* () {
59 const request = yield* HttpServerRequest;
60 const expected = yield* key.access();
61
62 if (expected === undefined) {
63 return yield* HttpServerResponse.json({ error: "not configured" }, { status: 503 });
64 }
65 if (request.headers["x-api-key"] !== expected) {
66 return yield* HttpServerResponse.json({ error: "denied" }, { status: 401 });
67 }
68 return HttpServerResponse.text("welcome");
69 }).pipe(Effect.orDie),
70 };
71 }).pipe(Effect.provide(GCP.SecretManager.ReadSecretHttp)),
72 ) {}
73 ```
74
75 `access()` returns `undefined` until a version exists, so the service
76 can refuse requests instead of letting everyone in. Reading per
77 request means a new version takes effect without a redeploy.
78
79 `ReadSecret` grants `roles/secretmanager.secretAccessor` on this secret
80 only.
81
82 ## Write versions from code
83
84 `WriteSecret` adds, disables, and destroys versions. Use it to rotate a
85 value from a job:
86
87 ```typescript
88 const secret = yield* GCP.SecretManager.WriteSecret(ApiKey);
89 // inside run:
90 yield* secret.addVersion(crypto.randomUUID());
91 ```
92
93 `ReadWriteSecret` does both.
94
95 ## Encrypt with Cloud KMS
96
97 Create a key ring and a key:
98
99 ```typescript
100 // src/resources.ts
101 export const Keys = GCP.KMS.KeyRing("Keys", {});
102
103 export const DataKey = Effect.gen(function* () {
104 const keys = yield* Keys;
105 return yield* GCP.KMS.CryptoKey("DataKey", {
106 keyRing: keys.name,
107 purpose: "ENCRYPT_DECRYPT",
108 });
109 });
110 ```
111
112 Bind `Encrypt` and `Decrypt`. The key material never leaves KMS:
113
114 ```typescript
115 const encrypt = yield* GCP.KMS.Encrypt(yield* DataKey);
116 const decrypt = yield* GCP.KMS.Decrypt(yield* DataKey);
117
118 // inside fetch:
119 const { ciphertext } = yield* encrypt({ body: { plaintext: btoa("hello") } });
120 const { plaintext } = yield* decrypt({ body: { ciphertext } });
121 ```
122
123 Provide `GCP.KMS.EncryptHttp` and `GCP.KMS.DecryptHttp`. Each grants
124 the matching `cryptoKeyEncrypter` or `cryptoKeyDecrypter` role on this
125 key only.
126
127 ## Destroying keys
128
129 Cloud KMS has no delete. `alchemy destroy` schedules every key version
130 for destruction and leaves the empty key ring, which costs nothing.
131 Deploying a key with the same id again reuses it with a fresh version.
132
133 ## Example
134
135 [`examples/gcp-secrets-kms`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-secrets-kms)
136 is an encryption API gated by a Secret Manager key.
137
138 ## Where next
139
140 - [IAM & bindings](/gcp/security/iam) — exactly which role each binding
141 grants.
142 - [Secrets](/environments/secrets) — `.env` values and Config.
143 - [SecretManager reference](/providers/gcp/secretmanager#secret) —
144 every prop.