codexkit 1.0.0

package/.codex/skills/cloudflare/references/secrets-store/api.md

@@ -0,0 +1,182 @@
+# API Reference
+
+## Binding API
+
+### Basic Access
+
+**CRITICAL**: Async `.get()` required - secrets NOT directly available.
+
+```typescript
+interface Env {
+  API_KEY: { get(): Promise<string> };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiKey = await env.API_KEY.get();
+    return fetch("https://api.example.com", {
+      headers: { "Authorization": `Bearer ${apiKey}` }
+    });
+  }
+}
+```
+
+### Multiple Secrets
+
+```typescript
+const [stripeKey, sendgridKey] = await Promise.all([
+  env.STRIPE_KEY.get(),
+  env.SENDGRID_KEY.get()
+]);
+```
+
+### Anti-Patterns
+
+```typescript
+// ❌ Missing .get()
+const key = env.API_KEY;
+
+// ❌ Module-level cache
+const CACHED_KEY = await env.API_KEY.get(); // Fails
+
+// ✅ Request-scope cache
+export default {
+  async fetch(request: Request, env: Env) {
+    const key = await env.API_KEY.get(); // OK - reuse in request
+    const r1 = await fetchWithAuth(key, "/ep1");
+    const r2 = await fetchWithAuth(key, "/ep2");
+    return Response.json({ r1, r2 });
+  }
+}
+```
+
+## REST API
+
+Base: `https://api.cloudflare.com/client/v4`
+
+### Auth
+
+```bash
+curl -H "Authorization: Bearer $CF_TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores
+```
+
+### Store Operations
+
+```bash
+# List
+GET /accounts/{account_id}/secrets_store/stores
+
+# Create
+POST /accounts/{account_id}/secrets_store/stores
+{"name": "my-store"}
+
+# Delete
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}
+```
+
+### Secret Operations
+
+```bash
+# List
+GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+
+# Create (single)
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+{
+  "name": "my_secret",
+  "value": "secret_value",
+  "scopes": ["workers"],
+  "comment": "Optional"
+}
+
+# Create (batch)
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+[
+  {"name": "secret_one", "value": "val1", "scopes": ["workers"]},
+  {"name": "secret_two", "value": "val2", "scopes": ["workers", "ai-gateway"]}
+]
+
+# Get metadata
+GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+
+# Update
+PATCH /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+{"value": "new_value", "comment": "Updated"}
+
+# Delete (single)
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+
+# Delete (batch)
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+{"secret_ids": ["id-1", "id-2"]}
+
+# Duplicate
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}/duplicate
+{"name": "new_name"}
+
+# Quota
+GET /accounts/{account_id}/secrets_store/quota
+```
+
+### Responses
+
+Success:
+```json
+{
+  "success": true,
+  "result": {
+    "id": "secret-id-123",
+    "name": "my_secret",
+    "created": "2025-01-11T12:00:00Z",
+    "scopes": ["workers"]
+  }
+}
+```
+
+Error:
+```json
+{
+  "success": false,
+  "errors": [{"code": 10000, "message": "Name exists"}]
+}
+```
+
+## TypeScript Helpers
+
+```typescript
+interface SecretsStoreBinding {
+  get(): Promise<string>;
+}
+
+interface Env {
+  STRIPE_API_KEY: SecretsStoreBinding;
+  DATABASE_URL: SecretsStoreBinding;
+  WORKER_SECRET: string; // Regular Worker secret (direct access)
+}
+
+// Fallback helper
+async function getSecretWithFallback(
+  primary: SecretsStoreBinding,
+  fallback?: SecretsStoreBinding
+): Promise<string> {
+  try {
+    return await primary.get();
+  } catch (error) {
+    if (fallback) return await fallback.get();
+    throw error;
+  }
+}
+
+// Batch helper
+async function getAllSecrets(
+  secrets: Record<string, SecretsStoreBinding>
+): Promise<Record<string, string>> {
+  const entries = await Promise.all(
+    Object.entries(secrets).map(async ([k, v]) => [k, await v.get()])
+  );
+  return Object.fromEntries(entries);
+}
+```
+
+See: [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/.codex/skills/cloudflare/references/secrets-store/configuration.md

@@ -0,0 +1,140 @@
+# Configuration
+
+## Wrangler Config
+
+### Basic Binding
+
+```toml
+# wrangler.toml
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "abc123", secret_name = "stripe_api_key" }
+]
+```
+
+```jsonc
+// wrangler.jsonc
+"secrets_store_secrets": [
+  { "binding": "API_KEY", "store_id": "abc123", "secret_name": "stripe_api_key" }
+]
+```
+
+Fields:
+- `binding`: Variable name for `env` access
+- `store_id`: From `wrangler secrets-store store list`
+- `secret_name`: Identifier (no spaces)
+
+### Environment-Specific
+
+```toml
+[env.production]
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "prod-store", secret_name = "prod_api_key" }
+]
+
+[env.staging]
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "staging-store", secret_name = "staging_api_key" }
+]
+```
+
+## Wrangler Commands
+
+### Store Management
+
+```bash
+wrangler secrets-store store list
+wrangler secrets-store store create my-store --remote
+wrangler secrets-store store delete <store-id> --remote
+```
+
+### Secret Management (Production)
+
+```bash
+# Create (interactive)
+wrangler secrets-store secret create <store-id> \
+  --name MY_SECRET --scopes workers --remote
+
+# Create (piped)
+cat secret.txt | wrangler secrets-store secret create <store-id> \
+  --name MY_SECRET --scopes workers --remote
+
+# List/get/update/delete
+wrangler secrets-store secret list <store-id> --remote
+wrangler secrets-store secret get <store-id> --name MY_SECRET --remote
+wrangler secrets-store secret update <store-id> --name MY_SECRET --new-value "val" --remote
+wrangler secrets-store secret delete <store-id> --name MY_SECRET --remote
+
+# Duplicate
+wrangler secrets-store secret duplicate <store-id> \
+  --name ORIG --new-name COPY --remote
+```
+
+### Local Development
+
+**CRITICAL**: Production secrets (`--remote`) NOT accessible in local dev.
+
+```bash
+# Create local-only (no --remote)
+wrangler secrets-store secret create <store-id> --name DEV_KEY --scopes workers
+
+wrangler dev    # Uses local secrets
+wrangler deploy # Uses production secrets
+```
+
+Best practice: Separate names for local/prod:
+
+```toml
+[env.development]
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "store", secret_name = "dev_api_key" }
+]
+
+[env.production]
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "store", secret_name = "prod_api_key" }
+]
+```
+
+## Dashboard
+
+### Creating Secrets
+
+1. **Secrets Store** → **Create secret**
+2. Fill: Name (no spaces), Value, Scope (`Workers`), Comment
+3. **Save** (value hidden after)
+
+### Adding Bindings
+
+**Method 1**: Worker → Settings → Bindings → Add → Secrets Store
+**Method 2**: Create secret directly from Worker settings dropdown
+
+Deploy options:
+- **Deploy**: Immediate 100%
+- **Save version**: Gradual rollout
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+- name: Create secret
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}
+  run: |
+    echo "${{ secrets.API_KEY }}" | \
+    npx wrangler secrets-store secret create $STORE_ID \
+      --name API_KEY --scopes workers --remote
+
+- name: Deploy
+  run: npx wrangler deploy
+```
+
+### GitLab CI
+
+```yaml
+script:
+  - echo "$API_KEY_VALUE" | npx wrangler secrets-store secret create $STORE_ID --name API_KEY --scopes workers --remote
+  - npx wrangler deploy
+```
+
+See: [api.md](./api.md), [patterns.md](./patterns.md)

package/.codex/skills/cloudflare/references/secrets-store/gotchas.md

@@ -0,0 +1,129 @@
+# Gotchas
+
+## Security
+
+### Never Log Secret Values
+
+```typescript
+// ❌ Logs secret
+const secret = await env.API_KEY.get();
+console.log(`Using secret: ${secret}`);
+
+// ✅ Log metadata only
+console.log("Retrieved API_KEY from Secrets Store");
+```
+
+### No Module-Level Caching
+
+```typescript
+// ❌ Fails - secrets unavailable during module init
+import { env } from "cloudflare:workers";
+const CACHED = await env.API_KEY.get();
+
+// ✅ Cache in request scope
+export default {
+  async fetch(request: Request, env: Env) {
+    const key = await env.API_KEY.get(); // Reuse in request
+    // ...
+  }
+}
+```
+
+## Troubleshooting
+
+### "Secret not found"
+
+```
+Error: Secret 'my_secret' not found in store
+```
+
+Fix:
+1. `wrangler secrets-store secret list <store-id> --remote`
+2. Check `secret_name` matches exactly (case-sensitive)
+3. Ensure secret has `workers` scope
+4. Verify `store_id` correct
+
+### Local Dev: Production Secrets Inaccessible
+
+```
+Error: Cannot access secret 'API_KEY' in local dev
+```
+
+Fix:
+```bash
+# Create local-only (no --remote)
+wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers
+```
+
+Keep prod/local secrets separate.
+
+### Type Errors
+
+```typescript
+// Error: Property 'get' does not exist
+const key = await env.API_KEY.get();
+```
+
+Fix:
+```typescript
+interface Env {
+  API_KEY: { get(): Promise<string> };
+}
+```
+
+### "Binding already exists"
+
+```
+Error: Binding 'API_KEY' already exists
+```
+
+Fix:
+1. Remove duplicate from dashboard Settings → Bindings
+2. Check `wrangler.toml` vs dashboard conflicts
+3. Delete old Worker secret: `wrangler secret delete API_KEY`
+
+### Quota Exceeded
+
+```
+Error: Account secret quota exceeded (100/100)
+```
+
+Fix:
+1. `wrangler secrets-store quota --remote`
+2. Delete unused secrets
+3. Consolidate duplicates
+4. Contact Cloudflare for increase
+
+## Limits
+
+- 100 secrets/account (beta)
+- 1 store/account (beta)
+- 1024 bytes max/secret
+- Production secrets count toward limit (local don't)
+
+## Comparison Table
+
+| Feature | Secrets Store | Worker Secrets |
+|---------|---------------|----------------|
+| Scope | Account-level | Per-Worker |
+| Reusability | Multi-Worker | Single Worker |
+| Access | `await env.BINDING.get()` | `env.SECRET_NAME` |
+| Management | Centralized | Per-Worker |
+| Commands | `secrets-store` | `secret` |
+| Local dev | Separate local secrets | `.dev.vars`/`.env` |
+| Limits | 100/account | Per-Worker |
+
+## Best Practices
+
+1. **Always async**: `await env.BINDING.get()`
+2. **Local vs prod**: Separate secrets (no `--remote` for local)
+3. **Type safety**: Define `{ get(): Promise<string> }`
+4. **Never log values**: Metadata only
+5. **Design for rotation**: Use fallback bindings
+6. **Scopes**: Set `workers` scope
+7. **Request-scope caching**: OK to cache within request, not module-level
+8. **Separate names**: Different names for dev/staging/prod
+9. **Quota awareness**: Monitor 100-secret limit
+10. **No direct access**: Values never returned after creation
+
+See: [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)

package/.codex/skills/cloudflare/references/secrets-store/patterns.md

@@ -0,0 +1,218 @@
+# Patterns
+
+## Secret Rotation
+
+Design for rotation with fallback:
+
+```typescript
+interface Env {
+  PRIMARY_KEY: { get(): Promise<string> };
+  FALLBACK_KEY?: { get(): Promise<string> };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    let key = await env.PRIMARY_KEY.get();
+    let resp = await fetch("https://api.example.com", {
+      headers: { "Authorization": `Bearer ${key}` }
+    });
+    
+    // Fallback during rotation
+    if (!resp.ok && env.FALLBACK_KEY) {
+      key = await env.FALLBACK_KEY.get();
+      resp = await fetch("https://api.example.com", {
+        headers: { "Authorization": `Bearer ${key}` }
+      });
+    }
+    
+    return resp;
+  }
+}
+```
+
+Rotation workflow:
+1. Create new secret (`api_key_v2`)
+2. Add fallback binding
+3. Deploy & verify
+4. Update primary binding
+5. Deploy
+6. Remove old secret
+
+## Encryption with KV
+
+```typescript
+interface Env {
+  CACHE: KVNamespace;
+  ENCRYPTION_KEY: { get(): Promise<string> };
+}
+
+async function encryptValue(value: string, key: string): Promise<string> {
+  const enc = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw", enc.encode(key), { name: "AES-GCM" }, false, ["encrypt"]
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encrypted = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv }, keyMaterial, enc.encode(value)
+  );
+  
+  const combined = new Uint8Array(iv.length + encrypted.byteLength);
+  combined.set(iv);
+  combined.set(new Uint8Array(encrypted), iv.length);
+  return btoa(String.fromCharCode(...combined));
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const key = await env.ENCRYPTION_KEY.get();
+    const encrypted = await encryptValue("sensitive-data", key);
+    await env.CACHE.put("user:123:data", encrypted);
+    return Response.json({ ok: true });
+  }
+}
+```
+
+## HMAC Signing
+
+```typescript
+interface Env {
+  HMAC_SECRET: { get(): Promise<string> };
+}
+
+async function signRequest(data: string, secret: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(data));
+  return btoa(String.fromCharCode(...new Uint8Array(sig)));
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const secret = await env.HMAC_SECRET.get();
+    const payload = await request.text();
+    const signature = await signRequest(payload, secret);
+    return Response.json({ signature });
+  }
+}
+```
+
+## Audit & Monitoring
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const startTime = Date.now();
+    try {
+      const apiKey = await env.API_KEY.get();
+      const resp = await fetch("https://api.example.com", {
+        headers: { "Authorization": `Bearer ${apiKey}` }
+      });
+      
+      ctx.waitUntil(
+        fetch("https://log.example.com/log", {
+          method: "POST",
+          body: JSON.stringify({
+            event: "secret_used",
+            secret_name: "API_KEY",
+            timestamp: new Date().toISOString(),
+            duration_ms: Date.now() - startTime,
+            success: resp.ok
+          })
+        })
+      );
+      return resp;
+    } catch (error) {
+      ctx.waitUntil(
+        fetch("https://log.example.com/log", {
+          method: "POST",
+          body: JSON.stringify({
+            event: "secret_access_failed",
+            secret_name: "API_KEY",
+            error: error instanceof Error ? error.message : "Unknown"
+          })
+        })
+      );
+      return new Response("Error", { status: 500 });
+    }
+  }
+}
+```
+
+## Migration
+
+### From Worker Secrets
+
+Before:
+```typescript
+// wrangler secret put API_KEY
+const key = env.API_KEY; // Direct access
+```
+
+After:
+```toml
+secrets_store_secrets = [
+  { binding = "API_KEY", store_id = "abc123", secret_name = "shared_key" }
+]
+```
+```typescript
+const key = await env.API_KEY.get(); // Async access
+```
+
+Steps:
+1. Create secret in Secrets Store
+2. Add `secrets_store_secrets` binding
+3. Update code to `await env.BINDING.get()`
+4. Test staging
+5. Deploy
+6. Delete old: `wrangler secret delete API_KEY`
+
+### Sharing Across Workers
+
+```toml
+# worker-1/wrangler.toml
+secrets_store_secrets = [
+  { binding = "SHARED_DB", store_id = "abc123", secret_name = "postgres_url" }
+]
+
+# worker-2/wrangler.toml
+secrets_store_secrets = [
+  { binding = "DB_CONN", store_id = "abc123", secret_name = "postgres_url" }
+]
+```
+
+Both access same secret, different binding names.
+
+## Integration
+
+### D1 Database
+
+```typescript
+interface Env {
+  DB: D1Database;
+  DB_CREDENTIALS: { get(): Promise<string> };
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const creds = await env.DB_CREDENTIALS.get();
+    const { username, password } = JSON.parse(creds);
+    // Use with D1
+    return Response.json({ ok: true });
+  }
+}
+```
+
+### Service Bindings
+
+```typescript
+// auth-worker: Signs JWT with Secrets Store
+interface Env { JWT_SECRET: { get(): Promise<string> }; }
+
+// api-worker: Calls auth service
+interface Env { AUTH: Fetcher; }
+const authResp = await env.AUTH.fetch(new Request("https://auth/verify"));
+```
+
+See: [api.md](./api.md), [gotchas.md](./gotchas.md)