feat: introduce worker mode for signing with AES-256-GCM key sealing

- Added support for a new signing mode ("worker") that uses AES-256-GCM encryption for private keys.
- Updated README.md to reflect changes in key management and deployment instructions for worker mode.
- Modified API to handle identity creation and signing in both enclave and worker modes.
- Implemented workerSigner module for key generation and signing in worker mode.
- Enhanced error handling for identity restoration and signing processes.
- Updated deployment scripts to support worker mode deployment.
- Adjusted runbook documentation to include details on switching between enclave and worker modes.

Author: tiero

README.md

@@ -4,7 +4,7 @@
 
 Bitcoin for AI Agents.
 
-Agents hold Bitcoin — the only money they can cryptographically verify. When they need to pay for something (APIs, stablecoins, inference), they swap BTC on the fly. Private keys live in hardware enclaves. One CLI for BTC, Lightning, Ark, and stablecoins.
+Agents hold Bitcoin — the only money they can cryptographically verify. When they need to pay for something (APIs, stablecoins, inference), they swap BTC on the fly. Private keys are managed by the API in one of two modes: a hardware-isolated Evervault Enclave (operator cannot read keys), or a pure Cloudflare Worker using AES-256-GCM encryption (cheaper, operator-trusted). One CLI for BTC, Lightning, Ark, and stablecoins.
 
 Works with any agent harness — [OpenClaw](https://openclaw.ai), Claude Code, or your own. Give your agent a wallet it can actually verify.
 
@@ -18,17 +18,17 @@ The swap infrastructure (LendaSwap + Boltz) and ECDSA signing are already in pla
 
 ## How it works
 
-```
+```text
 Agent ──► cash CLI ──► skills/ ──► sdk/ ──► clw.cash API ──► Enclave (secp256k1)
                                                 │
                                                 └── audit log, rate limits, 2FA via Telegram
 ```
 
 ## Layout
 
-```
-api/          Public-facing REST API (auth, identities, signing)
-enclave/      Signer service (runs inside Evervault Enclave)
+```text
+api/          Public-facing REST API (auth, identities, signing, worker-mode signer)
+enclave/      Signer service (runs inside Evervault Enclave — enclave mode only)
 sdk/          TypeScript SDK — RemoteSignerIdentity, API client, signing utils
 skills/       Bitcoin, Lightning, and Stablecoin skills (Ark, Boltz, LendaSwap)
 cli/          Agent-friendly CLI ("cash") — send, receive, balance
@@ -136,7 +136,7 @@ pnpm typecheck
 
 clw.cash acts as a **factory bot** — a backend service that other Telegram bots use to give their users Bitcoin wallets. Your bot authenticates with a shared API key and gets per-user sessions without any user-facing auth flow.
 
-### How it works
+### Factory bot flow
 
 ```text
 User (Telegram)           Your Bot                    clw.cash API          Enclave
@@ -206,19 +206,42 @@ const result = await bitcoin.send({ address: "ark1q...", amount: 1000 });
 | **Bot session** | Bot API key + `telegram_user_id` → instant JWT | Telegram bot serving many users |
 | **Test mode** | No `TELEGRAM_BOT_TOKEN` → auto-resolves | Local dev, CI |
 
-## Deploy to Evervault
+## Deploy
+
+See [docs/runbook.md](docs/runbook.md) for the full operator guide.
+
+### Worker mode (Cloudflare-only, no enclave)
+
+```bash
+# Generate a 32-byte AES-256 key for encrypting private keys at rest
+openssl rand -hex 32 | wrangler secret put WORKER_SEALING_KEY --env production
+
+# Set SIGNER_MODE = "worker" in api/wrangler.toml [env.production.vars], then:
+cd api && pnpm deploy:prod
+```
+
+### Enclave mode (Evervault, hardware-isolated)
 
 Install the [Evervault CLI](https://docs.evervault.com/cli), then:
 
 ```bash
 # one-time: generate signing certs
 ev enclave cert new --output ./infra
 
-# build enclave image
+# build and deploy
 ev enclave build -v --output . -c ./infra/enclave.toml ./enclave
-
-# deploy
 ev enclave deploy -v --eif-path ./enclave.eif -c ./infra/enclave.toml
+
+# then deploy the API worker (SIGNER_MODE = "enclave")
+cd api && pnpm deploy:prod
+```
+
+Or use the deploy script:
+
+```bash
+./scripts/deploy.sh generate-secrets
+./scripts/deploy.sh enclave    # enclave mode: build + deploy enclave + API
+./scripts/deploy.sh worker-api # worker mode: deploy API only (no enclave needed)
 ```
 
 ## Roadmap

api/package.json

@@ -12,6 +12,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@noble/hashes": "^1.6.0",
+    "@noble/secp256k1": "3.0.0",
     "hono": "^4.7.0",
     "jose": "^6.0.0",
     "zod": "^3.24.2"

api/src/bindings.ts

@@ -18,6 +18,10 @@ export interface Env {
   // Variables
   ALLOW_TEST_AUTH: string;
   ENCLAVE_BASE_URL: string;
+  SIGNER_MODE: string; // "enclave" (default) | "worker"
+
+  // Secrets (worker mode only)
+  WORKER_SEALING_KEY: string; // 32-byte hex AES-256 master key for encrypting private keys
   TICKET_TTL_SECONDS: string;
   SESSION_TTL_SECONDS: string;
   CHALLENGE_TTL_SECONDS: string;

api/src/index.ts

@@ -6,6 +6,7 @@ import type { Env } from "./bindings.js";
 import { CloudflareStore } from "./store.js";
 import { KVRateLimiter } from "./rateLimit.js";
 import { EnclaveClient, EnclaveClientError } from "./enclaveClient.js";
+import * as workerSigner from "./workerSigner.js";
 import { signSessionToken, signTicketToken, verifySessionToken, verifyTicketToken } from "./auth.js";
 import {
   challengeRequestSchema,
@@ -52,6 +53,21 @@ function getEnclave(env: Env): EnclaveClient {
   return new EnclaveClient(env.ENCLAVE_BASE_URL, env.INTERNAL_API_KEY, env.EV_API_KEY || undefined);
 }
 
+function isWorkerMode(env: Env): boolean {
+  return env.SIGNER_MODE === "worker";
+}
+
+function requireMasterKey(env: Env): string {
+  if (!env.WORKER_SEALING_KEY) throw new HTTPException(500, { message: "WORKER_SEALING_KEY secret not configured for worker mode" });
+  return env.WORKER_SEALING_KEY;
+}
+
+// Worker sealed keys are "{24 hex iv}:{variable hex ciphertext+tag}".
+// Enclave (Evervault) keys are opaque blobs that don't match this pattern.
+function isWorkerSealedKey(sealedKey: string): boolean {
+  return /^[0-9a-f]{24}:[0-9a-f]+$/.test(sealedKey);
+}
+
 async function currentUser(store: CloudflareStore, userId: string) {
   const user = await store.getUserById(userId);
   if (!user) throw new HTTPException(401, { message: "Session user no longer exists" });
@@ -210,7 +226,6 @@ app.post("/v1/identities", requireAuth, async (c) => {
   const auth = c.get("auth");
   const store = getStore(c.env);
   const limiter = getLimiter(c.env);
-  const enclave = getEnclave(c.env);
 
   const user = await currentUser(store, auth.sub);
   await enforceRate(limiter, `user:${user.id}:identity_create`, c.env);
@@ -219,11 +234,21 @@ app.post("/v1/identities", requireAuth, async (c) => {
   const identityId = crypto.randomUUID();
   const alg: SupportedAlg = body.alg ?? "secp256k1";
 
-  const generated = await enclave.generate(identityId, alg);
-  const exported = await enclave.exportKey(identityId);
-  await store.putBackup({ identity_id: identityId, alg: exported.alg, sealed_key: exported.sealed_key });
+  let publicKey: string;
+  if (isWorkerMode(c.env)) {
+    const masterKey = requireMasterKey(c.env);
+    const generated = await workerSigner.generateKey(masterKey);
+    await store.putBackup({ identity_id: identityId, alg, sealed_key: generated.sealedKey });
+    publicKey = generated.publicKey;
+  } else {
+    const enclave = getEnclave(c.env);
+    const generated = await enclave.generate(identityId, alg);
+    const exported = await enclave.exportKey(identityId);
+    await store.putBackup({ identity_id: identityId, alg: exported.alg, sealed_key: exported.sealed_key });
+    publicKey = generated.public_key;
+  }
 
-  const identity = await store.createIdentity({ id: identityId, user_id: user.id, alg, public_key: generated.public_key });
+  const identity = await store.createIdentity({ id: identityId, user_id: user.id, alg, public_key: publicKey });
   await store.addAuditEvent({ user_id: user.id, identity_id: identity.id, action: "identity.create", metadata: { alg: identity.alg } });
 
   return c.json(identity, 201);
@@ -233,21 +258,35 @@ app.post("/v1/identities/:id/restore", requireAuth, async (c) => {
   const auth = c.get("auth");
   const identityId = c.req.param("id");
   const store = getStore(c.env);
-  const enclave = getEnclave(c.env);
 
   const user = await currentUser(store, auth.sub);
 
   const existing = await store.getIdentity(identityId);
   if (existing) {
     if (existing.user_id !== user.id) throw new HTTPException(403, { message: "Identity does not belong to session user" });
-    await restoreBackup(store, enclave, identityId);
+    if (isWorkerMode(c.env)) {
+      const backup = await store.getBackup(identityId);
+      if (backup && !isWorkerSealedKey(backup.sealed_key)) {
+        throw new HTTPException(409, { message: "Identity was created in enclave mode and cannot be used in worker mode. Please create a new identity." });
+      }
+    } else {
+      const enclave = getEnclave(c.env);
+      await restoreBackup(store, enclave, identityId);
+    }
     return c.json(existing);
   }
 
   const backup = await store.getBackup(identityId);
   if (!backup) throw new HTTPException(404, { message: "No backup found for this identity" });
 
-  await enclave.importKey(identityId, backup.alg, stripWrappingQuotes(backup.sealed_key));
+  if (isWorkerMode(c.env)) {
+    if (!isWorkerSealedKey(backup.sealed_key)) {
+      throw new HTTPException(409, { message: "Identity was created in enclave mode and cannot be used in worker mode. Please create a new identity." });
+    }
+  } else {
+    const enclave = getEnclave(c.env);
+    await enclave.importKey(identityId, backup.alg, stripWrappingQuotes(backup.sealed_key));
+  }
 
   const body = (await c.req.json()) as { public_key?: string };
   if (!body.public_key) throw new HTTPException(400, { message: "Missing public_key in request body" });
@@ -292,7 +331,6 @@ app.post("/v1/identities/:id/sign", requireAuth, async (c) => {
   const identityId = c.req.param("id");
   const store = getStore(c.env);
   const limiter = getLimiter(c.env);
-  const enclave = getEnclave(c.env);
 
   const user = await currentUser(store, auth.sub);
   const identity = await ownedActiveIdentity(store, identityId, user.id);
@@ -314,14 +352,22 @@ app.post("/v1/identities/:id/sign", requireAuth, async (c) => {
   if (new Date(ticket.expires_at).getTime() <= Date.now()) throw new HTTPException(410, { message: "Ticket expired" });
 
   let signature: string;
-  try {
-    signature = (await enclave.sign(identity.id, digest, body.ticket)).signature;
-  } catch (error) {
-    if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
-    if (!(await restoreBackup(store, enclave, identity.id))) {
-      throw new HTTPException(409, { message: "Key not present in enclave and no backup available" });
+  if (isWorkerMode(c.env)) {
+    const masterKey = requireMasterKey(c.env);
+    const backup = await store.getBackup(identity.id);
+    if (!backup) throw new HTTPException(409, { message: "No key backup found" });
+    signature = await workerSigner.signDigest(backup.sealed_key, masterKey, digest);
+  } else {
+    const enclave = getEnclave(c.env);
+    try {
+      signature = (await enclave.sign(identity.id, digest, body.ticket)).signature;
+    } catch (error) {
+      if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
+      if (!(await restoreBackup(store, enclave, identity.id))) {
+        throw new HTTPException(409, { message: "Key not present in enclave and no backup available" });
+      }
+      signature = (await enclave.sign(identity.id, digest, body.ticket)).signature;
     }
-    signature = (await enclave.sign(identity.id, digest, body.ticket)).signature;
   }
 
   await store.markTicketUsed(ticket.id);
@@ -335,7 +381,6 @@ app.post("/v1/identities/:id/sign-batch", requireAuth, async (c) => {
   const identityId = c.req.param("id");
   const store = getStore(c.env);
   const limiter = getLimiter(c.env);
-  const enclave = getEnclave(c.env);
 
   const user = await currentUser(store, auth.sub);
   const identity = await ownedActiveIdentity(store, identityId, user.id);
@@ -345,34 +390,55 @@ app.post("/v1/identities/:id/sign-batch", requireAuth, async (c) => {
   const ticketTtl = parseInt(c.env.TICKET_TTL_SECONDS, 10);
   const signatures: string[] = [];
 
-  for (const item of body.digests) {
-    const digest = normalizeDigestHex(item.digest);
-    const digestHash = await CloudflareStore.digestHash(digest);
-    const nonce = crypto.randomUUID();
-    const ticketId = crypto.randomUUID();
-
-    const ticket = await signTicketToken(
-      { jti: ticketId, sub: user.id, identity_id: identity.id, digest_hash: digestHash, scope: "sign", nonce },
-      c.env.TICKET_SIGNING_SECRET,
-      ticketTtl,
-    );
-
-    const expiresAt = new Date(Date.now() + ticketTtl * 1000).toISOString();
-    await store.createTicket({ id: ticketId, identity_id: identity.id, digest_hash: digestHash, scope: "sign", expires_at: expiresAt, nonce }, ticketTtl);
-
-    let signature: string;
-    try {
-      signature = (await enclave.sign(identity.id, digest, ticket)).signature;
-    } catch (error) {
-      if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
-      if (!(await restoreBackup(store, enclave, identity.id))) {
-        throw new HTTPException(409, { message: "Key not present in enclave and no backup available" });
-      }
-      signature = (await enclave.sign(identity.id, digest, ticket)).signature;
+  // Worker mode: fetch backup once for all digests
+  let workerBackupSealedKey: string | null = null;
+  if (isWorkerMode(c.env)) {
+    const masterKey = requireMasterKey(c.env);
+    const backup = await store.getBackup(identity.id);
+    if (!backup) throw new HTTPException(409, { message: "No key backup found" });
+    workerBackupSealedKey = backup.sealed_key;
+    // masterKey captured in closure below
+    for (const item of body.digests) {
+      const digest = normalizeDigestHex(item.digest);
+      const digestHash = await CloudflareStore.digestHash(digest);
+      const ticketId = crypto.randomUUID();
+      const expiresAt = new Date(Date.now() + ticketTtl * 1000).toISOString();
+      await store.createTicket({ id: ticketId, identity_id: identity.id, digest_hash: digestHash, scope: "sign", expires_at: expiresAt, nonce: crypto.randomUUID() }, ticketTtl);
+      const signature = await workerSigner.signDigest(workerBackupSealedKey, masterKey, digest);
+      await store.markTicketUsed(ticketId);
+      signatures.push(signature);
     }
+  } else {
+    const enclave = getEnclave(c.env);
+    for (const item of body.digests) {
+      const digest = normalizeDigestHex(item.digest);
+      const digestHash = await CloudflareStore.digestHash(digest);
+      const nonce = crypto.randomUUID();
+      const ticketId = crypto.randomUUID();
+
+      const ticket = await signTicketToken(
+        { jti: ticketId, sub: user.id, identity_id: identity.id, digest_hash: digestHash, scope: "sign", nonce },
+        c.env.TICKET_SIGNING_SECRET,
+        ticketTtl,
+      );
+
+      const expiresAt = new Date(Date.now() + ticketTtl * 1000).toISOString();
+      await store.createTicket({ id: ticketId, identity_id: identity.id, digest_hash: digestHash, scope: "sign", expires_at: expiresAt, nonce }, ticketTtl);
+
+      let signature: string;
+      try {
+        signature = (await enclave.sign(identity.id, digest, ticket)).signature;
+      } catch (error) {
+        if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
+        if (!(await restoreBackup(store, enclave, identity.id))) {
+          throw new HTTPException(409, { message: "Key not present in enclave and no backup available" });
+        }
+        signature = (await enclave.sign(identity.id, digest, ticket)).signature;
+      }
 
-    await store.markTicketUsed(ticketId);
-    signatures.push(signature);
+      await store.markTicketUsed(ticketId);
+      signatures.push(signature);
+    }
   }
 
   await store.addAuditEvent({ user_id: user.id, identity_id: identity.id, action: "identity.sign", metadata: { batch_size: body.digests.length } });
@@ -385,18 +451,20 @@ app.delete("/v1/identities/:id", requireAuth, async (c) => {
   const identityId = c.req.param("id");
   const store = getStore(c.env);
   const limiter = getLimiter(c.env);
-  const enclave = getEnclave(c.env);
 
   const user = await currentUser(store, auth.sub);
   const identity = await ownedActiveIdentity(store, identityId, user.id);
   await enforceRate(limiter, `identity:${identity.id}:destroy`, c.env);
 
-  try {
-    await enclave.destroy(identity.id);
-  } catch (error) {
-    if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
-    if (await restoreBackup(store, enclave, identity.id)) {
+  if (!isWorkerMode(c.env)) {
+    const enclave = getEnclave(c.env);
+    try {
       await enclave.destroy(identity.id);
+    } catch (error) {
+      if (!(error instanceof EnclaveClientError) || error.statusCode !== 404) throw error;
+      if (await restoreBackup(store, enclave, identity.id)) {
+        await enclave.destroy(identity.id);
+      }
     }
   }