1# Patterns
2 
3## Secret Rotation
4 
5Zero-downtime rotation with versioned naming (`api_key_v1`, `api_key_v2`):
6 
7```typescript
8interface Env {
9  PRIMARY_KEY: { get(): Promise<string> };
10  FALLBACK_KEY?: { get(): Promise<string> };
11}
12 
13async function fetchWithAuth(url: string, key: string) {
14  return fetch(url, { headers: { "Authorization": `Bearer ${key}` } });
15}
16 
17export default {
18  async fetch(request: Request, env: Env): Promise<Response> {
19    let resp = await fetchWithAuth("https://api.example.com", await env.PRIMARY_KEY.get());
20    
21    // Fallback during rotation
22    if (!resp.ok && env.FALLBACK_KEY) {
23      resp = await fetchWithAuth("https://api.example.com", await env.FALLBACK_KEY.get());
24    }
25    
26    return resp;
27  }
28}
29```
30 
31Workflow: Create `api_key_v2` → add fallback binding → deploy → swap primary → deploy → remove `v1`
32 
33## Encryption with KV
34 
35```typescript
36interface Env {
37  CACHE: KVNamespace;
38  ENCRYPTION_KEY: { get(): Promise<string> };
39}
40 
41async function encryptValue(value: string, key: string): Promise<string> {
42  const enc = new TextEncoder();
43  const keyMaterial = await crypto.subtle.importKey(
44    "raw", enc.encode(key), { name: "AES-GCM" }, false, ["encrypt"]
45  );
46  const iv = crypto.getRandomValues(new Uint8Array(12));
47  const encrypted = await crypto.subtle.encrypt(
48    { name: "AES-GCM", iv }, keyMaterial, enc.encode(value)
49  );
50  
51  const combined = new Uint8Array(iv.length + encrypted.byteLength);
52  combined.set(iv);
53  combined.set(new Uint8Array(encrypted), iv.length);
54  return btoa(String.fromCharCode(...combined));
55}
56 
57export default {
58  async fetch(request: Request, env: Env): Promise<Response> {
59    const key = await env.ENCRYPTION_KEY.get();
60    const encrypted = await encryptValue("sensitive-data", key);
61    await env.CACHE.put("user:123:data", encrypted);
62    return Response.json({ ok: true });
63  }
64}
65```
66 
67## HMAC Signing
68 
69```typescript
70interface Env {
71  HMAC_SECRET: { get(): Promise<string> };
72}
73 
74async function signRequest(data: string, secret: string): Promise<string> {
75  const enc = new TextEncoder();
76  const key = await crypto.subtle.importKey(
77    "raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
78  );
79  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(data));
80  return btoa(String.fromCharCode(...new Uint8Array(sig)));
81}
82 
83export default {
84  async fetch(request: Request, env: Env): Promise<Response> {
85    const secret = await env.HMAC_SECRET.get();
86    const payload = await request.text();
87    const signature = await signRequest(payload, secret);
88    return Response.json({ signature });
89  }
90}
91```
92 
93## Audit & Monitoring
94 
95```typescript
96export default {
97  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
98    const startTime = Date.now();
99    try {
100      const apiKey = await env.API_KEY.get();
101      const resp = await fetch("https://api.example.com", {
102        headers: { "Authorization": `Bearer ${apiKey}` }
103      });
104      
105      ctx.waitUntil(
106        fetch("https://log.example.com/log", {
107          method: "POST",
108          body: JSON.stringify({
109            event: "secret_used",
110            secret_name: "API_KEY",
111            timestamp: new Date().toISOString(),
112            duration_ms: Date.now() - startTime,
113            success: resp.ok
114          })
115        })
116      );
117      return resp;
118    } catch (error) {
119      ctx.waitUntil(
120        fetch("https://log.example.com/log", {
121          method: "POST",
122          body: JSON.stringify({
123            event: "secret_access_failed",
124            secret_name: "API_KEY",
125            error: error instanceof Error ? error.message : "Unknown"
126          })
127        })
128      );
129      return new Response("Error", { status: 500 });
130    }
131  }
132}
133```
134 
135## Migration from Worker Secrets
136 
137Change `env.SECRET` (direct) to `await env.SECRET.get()` (async).
138 
139Steps:
1401. Create in Secrets Store: `wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers --remote`
1412. Add binding to `wrangler.jsonc`: `{"binding": "API_KEY", "store_id": "abc123", "secret_name": "api_key"}`
1423. Update code: `const key = await env.API_KEY.get();`
1434. Test staging, deploy
1445. Remove old: `wrangler secret delete API_KEY`
145 
146## Sharing Across Workers
147 
148Same secret, different binding names:
149 
150```jsonc
151// worker-1: binding="SHARED_DB", secret_name="postgres_url"
152// worker-2: binding="DB_CONN", secret_name="postgres_url"
153```
154 
155## JSON Secret Parsing
156 
157Store structured config as JSON secrets:
158 
159```typescript
160interface Env {
161  DB_CONFIG: { get(): Promise<string> };
162}
163 
164interface DbConfig {
165  host: string;
166  port: number;
167  username: string;
168  password: string;
169}
170 
171export default {
172  async fetch(request: Request, env: Env): Promise<Response> {
173    try {
174      const configStr = await env.DB_CONFIG.get();
175      const config: DbConfig = JSON.parse(configStr);
176      
177      // Use parsed config
178      const dbUrl = `postgres://${config.username}:${config.password}@${config.host}:${config.port}`;
179      
180      return Response.json({ connected: true });
181    } catch (error) {
182      if (error instanceof SyntaxError) {
183        return new Response("Invalid config JSON", { status: 500 });
184      }
185      throw error;
186    }
187  }
188}
189```
190 
191Store JSON secret:
192 
193```bash
194echo '{"host":"db.example.com","port":5432,"username":"app","password":"secret"}' | \
195  wrangler secrets-store secret create <store-id> \
196    --name DB_CONFIG --scopes workers --remote
197```
198 
199## Integration
200 
201### Service Bindings
202 
203Auth Worker signs JWT with Secrets Store; API Worker verifies via service binding.
204 
205See: [workers](../workers/) for service binding patterns.
206 
207See: [api.md](./api.md), [gotchas.md](./gotchas.md)
208