lakebed 0.0.4 → 0.0.6

package/README.md

@@ -86,6 +86,26 @@ mutations: {
 }
 ```
 
+## Server Env
+
+Server handlers can read capsule-specific environment variables through `ctx.env`.
+
+```txt
+# .env.lakebed.server
+OPENAI_API_KEY=sk-...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+```ts
+queries: {
+  settings: query((ctx) => ({
+    hasOpenAiKey: Boolean(ctx.env.OPENAI_API_KEY)
+  }));
+}
+```
+
+`lakebed dev` loads `.env.lakebed.server` locally. For hosted apps, claim the deploy, then run `lakebed deploy` to replace the deploy's server env with the file contents. Env values are not included in anonymous artifacts or source manifests.
+
 ## Commands
 
 ```sh
@@ -109,6 +129,7 @@ lakebed logs [deploy-id-or-url] [--port 3000]
 - Tailwind classes in JSX are the only styling path in v0.
 - Guest auth works by default. Google sign-in is built in through Shoo and exposes verified identity on `ctx.auth`.
 - Anonymous deploys disable outbound `fetch`.
+- Non-empty `.env.lakebed.server` files require a claimed deploy before they can sync to hosted server code.
 
 ## Hosted Deploys
 
@@ -142,9 +163,10 @@ Deploy responses include a claim URL. Configure GitHub OAuth on the runner, then
 LAKEBED_GITHUB_CLIENT_ID=...
 LAKEBED_GITHUB_CLIENT_SECRET=...
 LAKEBED_SESSION_SECRET=...
+LAKEBED_SERVER_ENV_SECRET=...
 ```
 
-Claimed deploys are listed at `/deploys` on the deploy API origin. They keep the same resource limits as anonymous deploys. Anonymous deploys cannot use outbound `fetch`; after a deploy is claimed, `lakebed deploy` can update it with a source-backed server artifact that supports async handlers and server-side fetch.
+Claimed deploys are listed at `/deploys` on the deploy API origin. They keep the same resource limits as anonymous deploys. Anonymous deploys cannot use outbound `fetch` or hosted server env; after a deploy is claimed, `lakebed deploy` can update it with a source-backed server artifact that supports async handlers, server-side fetch, and `.env.lakebed.server` sync. If the first deploy already needs server-side `fetch` or server env, `lakebed deploy` creates a claim-required preview, saves its claim metadata, and prints the claim URL. Open that URL, then run `lakebed deploy` again to publish the real source-backed app. Set `LAKEBED_SERVER_ENV_SECRET` on Postgres-backed runners to encrypt stored server env values.
 
 ## Admin Dashboard
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lakebed",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Agent-native CLI and runtime for building and deploying Lakebed capsules.",
   "license": "UNLICENSED",
   "type": "module",
@@ -29,7 +29,8 @@
     "src/runtime.js",
     "src/server.d.ts",
     "src/server.js",
-    "src/source-store.js"
+    "src/source-store.js",
+    "src/version.js"
   ],
   "exports": {
     "./package.json": "./package.json",
@@ -48,6 +49,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "check": "node --check src/cli.js && node --check src/runtime.js && node --check src/server.js && node --check src/client.js && node --check src/source-store.js && node --check src/anonymous.js && node --check src/anonymous-server.js && node --check src/auth.js && node --check src/version.js"
+  },
   "dependencies": {
     "esbuild": "^0.27.1",
     "pg": "^8.16.3",
@@ -56,8 +60,5 @@
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"
-  },
-  "scripts": {
-    "check": "node --check src/cli.js && node --check src/runtime.js && node --check src/server.js && node --check src/client.js && node --check src/source-store.js && node --check src/anonymous.js && node --check src/anonymous-server.js && node --check src/auth.js"
   }
-}
+}

package/src/anonymous-server.js

@@ -1,4 +1,4 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import {
   createClaimToken,
@@ -22,6 +22,46 @@ function dayWindowStart() {
   return `${new Date().toISOString().slice(0, 10)}T00:00:00.000Z`;
 }
 
+function serverEnvSecretFromEnv(env = process.env) {
+  return env.LAKEBED_SERVER_ENV_SECRET ?? env.LAKEBED_SESSION_SECRET ?? env.SPAN_SESSION_SECRET ?? "";
+}
+
+function serverEnvEncryptionKey(secret) {
+  return createHash("sha256").update(String(secret)).digest();
+}
+
+function encryptServerEnvValue(value, secret) {
+  if (!secret) {
+    return `plain:${Buffer.from(value, "utf8").toString("base64")}`;
+  }
+
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", serverEnvEncryptionKey(secret), iv);
+  const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `v1:${iv.toString("base64url")}:${tag.toString("base64url")}:${ciphertext.toString("base64url")}`;
+}
+
+function decryptServerEnvValue(value, secret) {
+  const stored = String(value ?? "");
+  if (stored.startsWith("plain:")) {
+    return Buffer.from(stored.slice("plain:".length), "base64").toString("utf8");
+  }
+
+  if (!stored.startsWith("v1:")) {
+    return stored;
+  }
+
+  if (!secret) {
+    throw new Error("LAKEBED_SERVER_ENV_SECRET is required to decrypt hosted server env.");
+  }
+
+  const [, ivBase64, tagBase64, ciphertextBase64] = stored.split(":");
+  const decipher = createDecipheriv("aes-256-gcm", serverEnvEncryptionKey(secret), Buffer.from(ivBase64, "base64url"));
+  decipher.setAuthTag(Buffer.from(tagBase64, "base64url"));
+  return Buffer.concat([decipher.update(Buffer.from(ciphertextBase64, "base64url")), decipher.final()]).toString("utf8");
+}
+
 function html(title, basePath, { shooBaseUrl } = {}) {
   return `<!doctype html>
 <html lang="en">
@@ -1434,6 +1474,7 @@ export class MemoryAnonymousStore {
     this.quotaEvents = new Map();
     this.queues = new Map();
     this.rows = new Map();
+    this.serverEnv = new Map();
   }
 
   async initialize() {}
@@ -1451,7 +1492,7 @@ export class MemoryAnonymousStore {
     });
   }
 
-  async createDeploy({ appBaseDomain, artifact, artifactHash, clientBundleBase64, clientBundleHash, publicRootUrl, requestedTtlSeconds }) {
+  async createDeploy({ appBaseDomain, artifact, artifactHash, clientBundleBase64, clientBundleHash, publicRootUrl, requestedTtlSeconds, serverEnv }) {
     const deployId = createDeployId();
     const normalizedAppBaseDomain = normalizeAppBaseDomain(appBaseDomain);
     let slug = createSlug();
@@ -1492,6 +1533,9 @@ export class MemoryAnonymousStore {
     };
     this.deploys.set(deployId, deploy);
     this.deploysBySlug.set(slug, deployId);
+    if (serverEnv !== undefined) {
+      this.serverEnv.set(deployId, { ...serverEnv });
+    }
     return { deploy, token };
   }
 
@@ -1503,7 +1547,8 @@ export class MemoryAnonymousStore {
     clientBundleHash,
     deployId,
     publicRootUrl,
-    requestedTtlSeconds
+    requestedTtlSeconds,
+    serverEnv
   }) {
     const currentDeploy = await this.getDeployById(deployId);
     if (!currentDeploy) {
@@ -1533,6 +1578,9 @@ export class MemoryAnonymousStore {
       createdAt
     });
     this.deploys.set(deployId, deploy);
+    if (serverEnv !== undefined) {
+      this.serverEnv.set(deployId, { ...serverEnv });
+    }
     return deploy;
   }
 
@@ -1624,6 +1672,14 @@ export class MemoryAnonymousStore {
     this.tableRows(deployId, tableName).delete(rowId);
   }
 
+  async replaceServerEnv(deployId, serverEnv) {
+    this.serverEnv.set(deployId, { ...serverEnv });
+  }
+
+  async getServerEnv(deployId) {
+    return { ...(this.serverEnv.get(deployId) ?? {}) };
+  }
+
   async transaction(deployId, handler) {
     const run = () => handler(this);
     const next = (this.queues.get(deployId) ?? Promise.resolve()).then(run, run);
@@ -1768,10 +1824,11 @@ export class MemoryAnonymousStore {
 }
 
 export class PostgresAnonymousStore {
-  constructor({ connectionString }) {
+  constructor({ connectionString, serverEnvSecret = "" }) {
     this.connectionString = connectionString;
     this.pool = null;
     this.queues = new Map();
+    this.serverEnvSecret = serverEnvSecret;
   }
 
   async initialize() {
@@ -1841,6 +1898,15 @@ export class PostgresAnonymousStore {
         primary key (deploy_id, bucket, window_start)
       )
     `);
+    await this.query(`
+      create table if not exists deploy_server_env(
+        deploy_id text not null references deploys(id) on delete cascade,
+        env_key text not null,
+        env_value text not null,
+        updated_at timestamptz not null,
+        primary key (deploy_id, env_key)
+      )
+    `);
   }
 
   async query(sql, params = []) {
@@ -1862,7 +1928,7 @@ export class PostgresAnonymousStore {
     );
   }
 
-  async createDeploy({ appBaseDomain, artifact, artifactHash, clientBundleBase64, clientBundleHash, publicRootUrl, requestedTtlSeconds }) {
+  async createDeploy({ appBaseDomain, artifact, artifactHash, clientBundleBase64, clientBundleHash, publicRootUrl, requestedTtlSeconds, serverEnv }) {
     const createdAt = now();
     const normalizedAppBaseDomain = normalizeAppBaseDomain(appBaseDomain);
     const ttlSeconds = parseTtlSeconds(requestedTtlSeconds);
@@ -1917,6 +1983,9 @@ export class PostgresAnonymousStore {
             deploy.url
           ]
         );
+        if (serverEnv !== undefined) {
+          await this.replaceServerEnv(deploy.id, serverEnv, createdAt);
+        }
         return { deploy, token };
       } catch (error) {
         if (error?.code !== "23505" || attempt === 7) {
@@ -1936,7 +2005,8 @@ export class PostgresAnonymousStore {
     clientBundleHash,
     deployId,
     publicRootUrl,
-    requestedTtlSeconds
+    requestedTtlSeconds,
+    serverEnv
   }) {
     const currentDeploy = await this.getDeployById(deployId);
     if (!currentDeploy) {
@@ -1966,6 +2036,9 @@ export class PostgresAnonymousStore {
       `,
       [deployId, artifactHash, clientBundleHash, expiresAt, nextPublicRootUrl, nextAppBaseDomain || null, url]
     );
+    if (serverEnv !== undefined) {
+      await this.replaceServerEnv(deployId, serverEnv, createdAt);
+    }
     return this.rowToDeploy(result.rows[0]);
   }
 
@@ -2107,6 +2180,24 @@ export class PostgresAnonymousStore {
     await this.query("delete from state_rows where deploy_id = $1 and table_name = $2 and row_id = $3", [deployId, tableName, rowId]);
   }
 
+  async replaceServerEnv(deployId, serverEnv, updatedAt = now()) {
+    await this.query("delete from deploy_server_env where deploy_id = $1", [deployId]);
+    for (const [key, value] of Object.entries(serverEnv)) {
+      await this.query(
+        `
+        insert into deploy_server_env(deploy_id, env_key, env_value, updated_at)
+        values($1, $2, $3, $4)
+        `,
+        [deployId, key, encryptServerEnvValue(value, this.serverEnvSecret), updatedAt]
+      );
+    }
+  }
+
+  async getServerEnv(deployId) {
+    const result = await this.query("select env_key, env_value from deploy_server_env where deploy_id = $1", [deployId]);
+    return Object.fromEntries(result.rows.map((row) => [row.env_key, decryptServerEnvValue(row.env_value, this.serverEnvSecret)]));
+  }
+
   async transaction(deployId, handler) {
     const run = () => handler(this);
     const next = (this.queues.get(deployId) ?? Promise.resolve()).then(run, run);
@@ -2301,7 +2392,10 @@ export class PostgresAnonymousStore {
 
 export async function createAnonymousStoreFromEnv(env = process.env) {
   if (env.DATABASE_URL) {
-    const store = new PostgresAnonymousStore({ connectionString: env.DATABASE_URL });
+    const store = new PostgresAnonymousStore({
+      connectionString: env.DATABASE_URL,
+      serverEnvSecret: serverEnvSecretFromEnv(env)
+    });
     await store.initialize();
     return store;
   }
@@ -2766,6 +2860,10 @@ export async function startAnonymousServer({
       if (req.method === "POST" && requestUrl.pathname === "/v1/anonymous-deploys") {
         const body = await readJsonBody(req);
         const payload = validateAnonymousDeployPayload(body);
+        if (payload.serverEnv !== undefined && Object.keys(payload.serverEnv).length > 0) {
+          sendJson(res, 400, { error: "Server env requires a claimed deploy." });
+          return;
+        }
         const { deploy, token } = await resolvedStore.createDeploy({
           appBaseDomain: resolvedAppBaseDomain,
           artifact: payload.artifact,
@@ -2773,7 +2871,8 @@ export async function startAnonymousServer({
           clientBundleBase64: payload.clientBundleBase64,
           clientBundleHash: payload.clientBundleHash,
           publicRootUrl: resolvedPublicRootUrl,
-          requestedTtlSeconds: body.requestedTtlSeconds ?? requestUrl.searchParams.get("ttl") ?? undefined
+          requestedTtlSeconds: body.requestedTtlSeconds ?? requestUrl.searchParams.get("ttl") ?? undefined,
+          serverEnv: payload.serverEnv
         });
         await resolvedStore.appendLog(deploy.id, "info", "anonymous deploy created", { artifactHash: deploy.artifactHash });
         sendJson(res, 201, responseForDeploy({ deploy, token }));
@@ -2795,6 +2894,10 @@ export async function startAnonymousServer({
 
         const body = await readJsonBody(req);
         const payload = validateAnonymousDeployPayload(body, { allowClaimedSource: Boolean(currentDeploy.ownerId) });
+        if (payload.serverEnv !== undefined && !currentDeploy.ownerId) {
+          sendJson(res, 400, { error: "Server env requires a claimed deploy." });
+          return;
+        }
         const deploy = await resolvedStore.updateDeploy({
           appBaseDomain: resolvedAppBaseDomain,
           artifact: payload.artifact,
@@ -2803,7 +2906,8 @@ export async function startAnonymousServer({
           clientBundleHash: payload.clientBundleHash,
           deployId,
           publicRootUrl: resolvedPublicRootUrl,
-          requestedTtlSeconds: body.requestedTtlSeconds ?? requestUrl.searchParams.get("ttl") ?? undefined
+          requestedTtlSeconds: body.requestedTtlSeconds ?? requestUrl.searchParams.get("ttl") ?? undefined,
+          serverEnv: payload.serverEnv
         });
         if (!deploy) {
           sendJson(res, 404, { error: "Unknown deploy." });

package/src/anonymous.js

@@ -1,8 +1,18 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { LAKEBED_VERSION } from "./version.js";
 
 export const ANONYMOUS_ARTIFACT_FORMAT = "lakebed.capsule.artifact.v1";
 export const ANONYMOUS_ARTIFACT_MEDIA_TYPE = "application/vnd.lakebed.artifact+json";
+export { LAKEBED_VERSION };
+
+export const SERVER_ENV_FILE = ".env.lakebed.server";
+export const SERVER_ENV_LIMITS = {
+  maxKeyBytes: 128,
+  maxKeys: 64,
+  maxTotalBytes: 64 * 1024,
+  maxValueBytes: 16 * 1024
+};
 
 export const DEFAULT_ANONYMOUS_LIMITS = {
   artifactBytes: 1024 * 1024,
@@ -65,6 +75,65 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
 }
 
+export function validateServerEnvValues(values, path = "serverEnv.values") {
+  if (!isPlainObject(values)) {
+    throw new Error(`${path} must be a JSON object.`);
+  }
+
+  const entries = Object.entries(values).sort(([left], [right]) => left.localeCompare(right));
+  if (entries.length > SERVER_ENV_LIMITS.maxKeys) {
+    throw new Error(`${path} may include at most ${SERVER_ENV_LIMITS.maxKeys} keys.`);
+  }
+
+  const env = {};
+  let totalBytes = 0;
+  for (const [key, value] of entries) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(`${path}.${key} is not a valid server env key.`);
+    }
+    if (key.startsWith("LAKEBED_")) {
+      throw new Error(`${path}.${key} uses the reserved LAKEBED_ prefix.`);
+    }
+    if (typeof value !== "string") {
+      throw new Error(`${path}.${key} must be a string.`);
+    }
+
+    const keyBytes = byteLength(key);
+    const valueBytes = byteLength(value);
+    if (keyBytes > SERVER_ENV_LIMITS.maxKeyBytes) {
+      throw new Error(`${path}.${key} exceeds ${SERVER_ENV_LIMITS.maxKeyBytes} bytes.`);
+    }
+    if (valueBytes > SERVER_ENV_LIMITS.maxValueBytes) {
+      throw new Error(`${path}.${key} exceeds ${SERVER_ENV_LIMITS.maxValueBytes} bytes.`);
+    }
+
+    totalBytes += keyBytes + valueBytes;
+    env[key] = value;
+  }
+
+  if (totalBytes > SERVER_ENV_LIMITS.maxTotalBytes) {
+    throw new Error(`${path} exceeds ${SERVER_ENV_LIMITS.maxTotalBytes} bytes.`);
+  }
+
+  return env;
+}
+
+export function validateServerEnvPayload(payload) {
+  if (payload === undefined) {
+    return undefined;
+  }
+
+  if (!isPlainObject(payload)) {
+    throw new Error("serverEnv must be a JSON object.");
+  }
+
+  if (payload.mode !== "replace") {
+    throw new Error("serverEnv.mode must be replace.");
+  }
+
+  return validateServerEnvValues(payload.values);
+}
+
 function isExpression(value) {
   return Array.isArray(value) && expressionOps.has(value[0]);
 }
@@ -315,7 +384,7 @@ function diagnostic(file, message) {
 }
 
 async function readSourceFiles(sourceStore) {
-  const paths = (await sourceStore.listFiles()).filter((path) => !path.startsWith("__lakebed/"));
+  const paths = (await sourceStore.listFiles()).filter((path) => !path.startsWith("__lakebed/") && path !== SERVER_ENV_FILE);
   const files = [];
 
   for (const path of paths) {
@@ -494,7 +563,7 @@ function compileServerToIr(app, schema) {
   return { diagnostics, mutations, queries };
 }
 
-export async function createAnonymousArtifact({ app, clientOut, sourceStore, version = "0.0.3" }) {
+export async function createAnonymousArtifact({ app, clientOut, sourceStore, version = LAKEBED_VERSION }) {
   const sourceFiles = await readSourceFiles(sourceStore);
   const diagnostics = forbiddenSourceDiagnostics(sourceFiles);
   const { diagnostics: schemaDiagnostics, schema } = serializeSchema(app.schema);
@@ -556,7 +625,7 @@ export async function createAnonymousArtifact({ app, clientOut, sourceStore, ver
   };
 }
 
-export async function createClaimedArtifact({ app, clientOut, serverOut, sourceStore, version = "0.0.3" }) {
+export async function createClaimedArtifact({ app, clientOut, serverOut, sourceStore, version = LAKEBED_VERSION }) {
   if (!serverOut) {
     throw new AnonymousCompilerError([diagnostic("server/index.ts", "Claimed deploys require a bundled server module.")]);
   }
@@ -841,12 +910,14 @@ export function validateAnonymousDeployPayload(payload, options = {}) {
   }
 
   const artifactHash = sha256(stableStringify(payload.artifact));
+  const serverEnv = validateServerEnvPayload(payload.serverEnv);
   return {
     artifact: cloneJson(payload.artifact),
     artifactHash,
     clientBundle,
     clientBundleBase64: clientBundle.toString("base64"),
-    clientBundleHash
+    clientBundleHash,
+    serverEnv
   };
 }
 
@@ -1100,6 +1171,7 @@ function createSourceQuery(rows, tableName) {
 async function createSourceContext({ artifact, auth, deployId, state }) {
   const rows = {};
   const operations = [];
+  const env = typeof state.getServerEnv === "function" ? await state.getServerEnv(deployId) : {};
   for (const tableName of Object.keys(artifact.server.schema ?? {})) {
     rows[tableName] = await state.listRows(deployId, tableName);
   }
@@ -1141,7 +1213,7 @@ async function createSourceContext({ artifact, auth, deployId, state }) {
     ctx: {
       auth,
       db,
-      env: {},
+      env,
       log: {
         error() {},
         info() {},

package/src/cli.js

@@ -9,15 +9,18 @@ import { WebSocketServer } from "ws";
 import {
   ANONYMOUS_ARTIFACT_MEDIA_TYPE,
   AnonymousCompilerError,
+  LAKEBED_VERSION,
+  SERVER_ENV_FILE,
   createAnonymousArtifact,
   createClaimedArtifact,
   parseTtlSeconds,
-  stableStringify
+  stableStringify,
+  validateServerEnvValues
 } from "./anonymous.js";
 import { startAnonymousServer } from "./anonymous-server.js";
 import { authFromUrl as resolveAuthFromUrl, createGuestAuth, requestOrigin, shooBaseUrlFromEnv } from "./auth.js";
 import { LogBuffer, StateCell } from "./runtime.js";
-import { createMemorySourceStoreFromDirectory, sourcePathDirname, sourcePathJoin } from "./source-store.js";
+import { MemorySourceStore, createMemorySourceStoreFromDirectory, sourcePathDirname, sourcePathJoin } from "./source-store.js";
 
 const root = process.cwd();
 const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -220,29 +223,45 @@ function createSourcePlugin(sourceStore, target) {
   };
 }
 
-async function readServerEnv(sourceStore) {
-  const env = { ...process.env };
-  if (!sourceStore.hasFile(".env.lakebed.server")) {
-    return env;
+function unquoteServerEnvValue(value) {
+  if (value.length < 2) {
+    return value;
   }
 
-  const contents = await sourceStore.readFile(".env.lakebed.server");
-  for (const rawLine of contents.split(/\r?\n/)) {
+  const quote = value[0];
+  if ((quote !== `"` && quote !== `'`) || value[value.length - 1] !== quote) {
+    return value;
+  }
+
+  return value.slice(1, -1);
+}
+
+function parseServerEnvFile(contents) {
+  const env = {};
+  for (const [index, rawLine] of contents.split(/\r?\n/).entries()) {
     const line = rawLine.trim();
     if (!line || line.startsWith("#")) {
       continue;
     }
 
-    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
     if (!match) {
-      continue;
+      throw new Error(`Invalid ${SERVER_ENV_FILE} line ${index + 1}. Use KEY=value.`);
     }
 
     const [, key, rawValue] = match;
-    env[key] = rawValue.replace(/^['"]|['"]$/g, "");
+    env[key] = unquoteServerEnvValue(rawValue.trim());
   }
 
-  return env;
+  return validateServerEnvValues(env, SERVER_ENV_FILE);
+}
+
+async function readCapsuleServerEnv(sourceStore) {
+  if (!sourceStore.hasFile(SERVER_ENV_FILE)) {
+    return {};
+  }
+
+  return parseServerEnvFile(await sourceStore.readFile(SERVER_ENV_FILE));
 }
 
 export async function buildCapsule({ capsuleDir, sourceStore, capsuleId = "dev" } = {}) {
@@ -300,7 +319,7 @@ export async function buildCapsule({ capsuleDir, sourceStore, capsuleId = "dev"
     app: capsuleModule.default,
     buildDir,
     clientOut,
-    env: await readServerEnv(workingStore),
+    env: await readCapsuleServerEnv(workingStore),
     serverOut,
     sourceStore: workingStore
   };
@@ -578,9 +597,9 @@ async function dev(args) {
   });
 }
 
-async function buildAnonymousEnvelope(capsuleArg) {
+async function buildAnonymousEnvelope(capsuleArg, sourceStore) {
   const capsuleDir = resolveCapsuleDir(capsuleArg);
-  const sourceStore = await createMemorySourceStoreFromDirectory(capsuleDir);
+  sourceStore ??= await createMemorySourceStoreFromDirectory(capsuleDir);
   const built = await buildCapsule({
     capsuleDir,
     capsuleId: `anonymous-${Date.now()}`,
@@ -601,9 +620,74 @@ async function buildAnonymousEnvelope(capsuleArg) {
   };
 }
 
-async function buildClaimedEnvelope(capsuleArg) {
+const claimRequiredDiagnosticMessages = new Set([
+  "Outbound fetch is disabled for anonymous deploys.",
+  "Async server handlers are not part of the anonymous IR yet. Use synchronous Lakebed database operations."
+]);
+
+function canDeployAfterClaim(error) {
+  return (
+    error instanceof AnonymousCompilerError &&
+    error.diagnostics.length > 0 &&
+    error.diagnostics.every((entry) => claimRequiredDiagnosticMessages.has(entry.message))
+  );
+}
+
+async function buildClaimRequiredEnvelope({ capsuleDir, feature = "claimed server features" }) {
+  const sourceStore = new MemorySourceStore();
+  await sourceStore.writeFile(
+    "server/index.ts",
+    `import { capsule } from "lakebed/server";
+
+export default capsule({
+  name: "Claim Required",
+  schema: {},
+  queries: {},
+  mutations: {}
+});
+`
+  );
+  await sourceStore.writeFile(
+    "client/index.tsx",
+    `export function App() {
+  return (
+    <main className="min-h-screen bg-neutral-950 px-6 py-12 text-neutral-100">
+      <section className="mx-auto max-w-2xl rounded-lg border border-neutral-800 bg-neutral-900 p-8 shadow-2xl">
+        <p className="text-sm font-semibold uppercase tracking-wide text-cyan-300">Lakebed deploy</p>
+        <h1 className="mt-3 text-3xl font-semibold">Claim required</h1>
+        <p className="mt-4 text-neutral-300">
+          This capsule uses ${feature}. Claim this deploy, then run lakebed deploy again to publish the app.
+        </p>
+      </section>
+    </main>
+  );
+}
+`
+  );
+  const built = await buildCapsule({
+    capsuleDir,
+    capsuleId: `claim-required-${Date.now()}`,
+    sourceStore
+  });
+  const artifact = await createAnonymousArtifact({
+    app: built.app,
+    clientOut: built.clientOut,
+    sourceStore
+  });
+
+  return {
+    artifact: artifact.artifact,
+    artifactHash: artifact.artifactHash,
+    clientBundle: artifact.clientBundle,
+    clientBundleHash: artifact.clientBundleHash,
+    claimRequired: true,
+    mediaType: ANONYMOUS_ARTIFACT_MEDIA_TYPE
+  };
+}
+
+async function buildClaimedEnvelope(capsuleArg, sourceStore) {
   const capsuleDir = resolveCapsuleDir(capsuleArg);
-  const sourceStore = await createMemorySourceStoreFromDirectory(capsuleDir);
+  sourceStore ??= await createMemorySourceStoreFromDirectory(capsuleDir);
   const built = await buildCapsule({
     capsuleDir,
     capsuleId: `claimed-${Date.now()}`,
@@ -677,13 +761,21 @@ function claimUrlFromDeployMetadata(metadata) {
   return `${String(metadata.api).replace(/\/+$/g, "")}/claim/${encodeURIComponent(metadata.deployId)}/${encodeURIComponent(metadata.claimToken)}`;
 }
 
-function deployRequestBody(envelope, ttl) {
-  return JSON.stringify({
+function deployRequestBody(envelope, ttl, { serverEnv } = {}) {
+  const body = {
     artifact: envelope.artifact,
     clientBundle: envelope.clientBundle,
-    clientVersion: "0.0.3",
+    clientVersion: LAKEBED_VERSION,
     requestedTtlSeconds: ttl
-  });
+  };
+  if (serverEnv !== undefined) {
+    body.serverEnv = {
+      mode: "replace",
+      values: serverEnv
+    };
+  }
+
+  return JSON.stringify(body);
 }
 
 async function buildCommand(args) {
@@ -735,6 +827,11 @@ async function readResponseJson(response) {
 async function deployCommand(args) {
   const [capsuleArg] = positionals(args);
   const capsuleDir = capsuleArg ? resolveCapsuleDir(capsuleArg) : root;
+  const sourceStore = await createMemorySourceStoreFromDirectory(capsuleDir);
+  const serverEnvFileExists = sourceStore.hasFile(SERVER_ENV_FILE);
+  const serverEnv = await readCapsuleServerEnv(sourceStore);
+  const serverEnvKeys = Object.keys(serverEnv).sort();
+  const hasServerEnvValues = serverEnvKeys.length > 0;
   const ttl = parseTtlSeconds(readArg(args, "--ttl", "7d"));
   const api = deployApiUrl(args);
   const metadata = await readDeployMetadata(capsuleDir);
@@ -749,23 +846,45 @@ async function deployCommand(args) {
   }
 
   let envelope;
-  try {
-    envelope = currentDeploy?.claimed ? await buildClaimedEnvelope(capsuleDir) : await buildAnonymousEnvelope(capsuleDir);
-  } catch (error) {
-    if (error instanceof AnonymousCompilerError && canUpdate && !currentDeploy?.claimed) {
+  if (!currentDeploy?.claimed && hasServerEnvValues) {
+    if (canUpdate && currentDeploy) {
       throw new Error(
-        `${error.message}\n\nThis deploy is still anonymous. Claim it first, then run lakebed deploy again to use server-side fetch.`
+        `This capsule defines server env in ${SERVER_ENV_FILE}.\n\nThis deploy is still anonymous. Claim it first, then run lakebed deploy again to sync server env.`
       );
     }
-    throw error;
+    try {
+      await buildAnonymousEnvelope(capsuleDir, sourceStore);
+    } catch (error) {
+      if (!canDeployAfterClaim(error)) {
+        throw error;
+      }
+    }
+    envelope = await buildClaimRequiredEnvelope({ capsuleDir, feature: "server env" });
+  } else {
+    try {
+      envelope = currentDeploy?.claimed ? await buildClaimedEnvelope(capsuleDir, sourceStore) : await buildAnonymousEnvelope(capsuleDir, sourceStore);
+    } catch (error) {
+      if (error instanceof AnonymousCompilerError && canUpdate && currentDeploy && !currentDeploy.claimed) {
+        throw new Error(
+          `${error.message}\n\nThis deploy is still anonymous. Claim it first, then run lakebed deploy again to use server-side fetch.`
+        );
+      }
+      if ((!canUpdate || !currentDeploy) && canDeployAfterClaim(error)) {
+        envelope = await buildClaimRequiredEnvelope({ capsuleDir, feature: "server-side fetch" });
+      } else {
+        throw error;
+      }
+    }
   }
-  const body = deployRequestBody(envelope, ttl);
+  const syncServerEnv = Boolean(currentDeploy?.claimed && serverEnvFileExists);
+  const serverEnvForUpdate = syncServerEnv ? serverEnv : undefined;
+  let serverEnvSynced = false;
   let mode = "created";
   let response;
 
   if (canUpdate) {
     response = await fetch(`${api}/v1/deploys/${encodeURIComponent(metadata.deployId)}`, {
-      body,
+      body: deployRequestBody(envelope, ttl, { serverEnv: serverEnvForUpdate }),
       headers: {
         "Authorization": `Bearer ${metadata.claimToken}`,
         "Content-Type": "application/json"
@@ -776,13 +895,17 @@ async function deployCommand(args) {
     if (response.status === 404 || response.status === 410) {
       mode = "created";
       response = null;
+      if (serverEnvForUpdate !== undefined && hasServerEnvValues) {
+        envelope = await buildClaimRequiredEnvelope({ capsuleDir, feature: "server env" });
+      }
     } else {
       mode = "updated";
+      serverEnvSynced = serverEnvForUpdate !== undefined;
     }
   }
 
   response ??= await fetch(`${api}/v1/anonymous-deploys`, {
-    body,
+    body: deployRequestBody(envelope, ttl),
     headers: {
       "Content-Type": "application/json"
     },
@@ -801,11 +924,24 @@ async function deployCommand(args) {
   }
 
   if (hasFlag(args, "--json")) {
-    console.log(JSON.stringify(deployed, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          ...(envelope.claimRequired ? { ...deployed, claimRequired: true } : deployed),
+          ...(serverEnvSynced ? { serverEnv: { keys: serverEnvKeys, mode: "replace", synced: true } } : {})
+        },
+        null,
+        2
+      )
+    );
     return;
   }
 
-  console.log(`${mode === "updated" ? "Updated" : "Created"} anonymous preview.\n`);
+  if (envelope.claimRequired && mode !== "updated") {
+    console.log("Created claim-required preview.\n");
+  } else {
+    console.log(`${mode === "updated" ? "Updated" : "Created"} anonymous preview.\n`);
+  }
   console.log(`App:        ${deployed.url}`);
   console.log(`Expires:    ${deployed.expiresAt}`);
   if (deployed.claimUrl) {
@@ -818,6 +954,16 @@ async function deployCommand(args) {
   console.log(`  requests:        ${deployed.limits.requestsPerDay} / day`);
   console.log(`  mutations:       ${deployed.limits.mutationsPerDay} / day`);
   console.log(`  outbound fetch:  ${envelope.artifact.deployTarget === "claimed-source" ? "enabled" : "disabled"}`);
+  if (serverEnvSynced) {
+    console.log(`\nServer env: ${serverEnvKeys.length} synced`);
+    for (const key of serverEnvKeys) {
+      console.log(`  ${key}`);
+    }
+  }
+  if (envelope.claimRequired) {
+    console.log("\nThis app needs a claimed deploy before server-side fetch or server env can run.");
+    console.log("Open the claim URL, then run lakebed deploy again.");
+  }
 }
 
 async function claimCommand(args) {
@@ -1028,6 +1174,7 @@ lakebed logs --port 3000
 - Use Tailwind classes directly in JSX.
 - Do not add a CSS, PostCSS, or Tailwind build pipeline.
 - Use auth through \`ctx.auth\` on the server and \`useAuth()\` on the client.
+- Read server-only environment variables through \`ctx.env\`; define them in \`.env.lakebed.server\`.
 - Add Google sign-in with \`<SignInWithGoogle />\` or \`signInWithGoogle()\` from \`lakebed/client\`.
 - Keep \`shared/\` free of DOM, Node, env, and Lakebed runtime imports.
 
@@ -1038,6 +1185,7 @@ lakebed logs --port 3000
 - Guest auth locally, with built-in Google sign-in through Shoo.
 - No file storage.
 - No outbound fetch in anonymous deploys. Claim the deploy before using server-side fetch.
+- Non-empty \`.env.lakebed.server\` files sync only after a deploy is claimed.
 - Local state resets when \`lakebed dev\` restarts.
 `;
 }
@@ -1145,6 +1293,7 @@ export function cleanTodoText(value: string): string {
 }
 `,
     ".gitignore": `.lakebed/
+.env.lakebed.server
 `,
     "README.md": `# ${title}
 

package/src/version.js

@@ -0,0 +1 @@
+export const LAKEBED_VERSION = "0.0.6";