@robodev-ai/runtime 0.3.0 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.3.0",
-  "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, and Robodev Auth. Shared by hosted Starbase and `robodev dev`.",
+  "version": "0.4.1",
+  "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, and local file storage. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -2,7 +2,7 @@
  * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
  * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
  * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
- * and the offline `robodev dev` jobs engine.
+ * the socket engine, local file storage, and the offline `robodev dev` jobs engine.
  */
 
 export {
@@ -218,6 +218,7 @@ export {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
   type LocalJobStatus,
   type LocalJobsEngine,
@@ -225,6 +226,59 @@ export {
   type LocalJobsGeneration,
 } from "./local-jobs.js";
 
+export {
+  MAX_PROJECT_SOCKETS,
+  MAX_SOCKET_PAYLOAD_BYTES,
+  SOCKET_CLOSE_INVALID,
+  SOCKET_CLOSE_POLICY,
+  SOCKET_CLOSE_RESTART,
+  SOCKET_CLOSE_TOO_BIG,
+  SOCKET_IDLE_PING_MS,
+  assertKnownSocket,
+  attachProjectSocket,
+  bindSocketSession,
+  closeProjectSockets,
+  createProjectSocketsClient,
+  detachProjectSocket,
+  dispatchSocketsSend,
+  joinSocketRoom,
+  leaveSocketRoom,
+  parseSocketMessage,
+  projectSocketCount,
+  sendToSocketName,
+  sendToSocketRoom,
+  setProjectSocketNames,
+  socketAuthDisplay,
+  stringifySocketPayload,
+  type BindSocketSessionInput,
+  type LiveConn,
+  type SocketSessionHelpers,
+  type SocketWire,
+} from "./sockets.js";
+
+export {
+  DEFAULT_LIST_LIMIT,
+  MAX_LIST_LIMIT,
+  MAX_OBJECT_BYTES,
+  PRESIGN_GET_DEFAULT,
+  PRESIGN_GET_MAX,
+  assertObjectSize,
+  clampStorageExpiresIn,
+  mintStorageServeToken,
+  parseLogicalKey,
+  storageListQuerySchema,
+  verifyStorageServeToken,
+} from "./storage-rules.js";
+
+export {
+  createLocalStorageClient,
+  ensureStorageSchema,
+  resolveLocalObject,
+  type LocalObjectRow,
+  type LocalStorageClientOptions,
+  type StorageQueryable,
+} from "./local-storage.js";
+
 export {
   LOCAL_DEV_IDENTITY_AUD,
   LOCAL_DEV_IDENTITY_TYP,

package/src/local-jobs.test.ts

@@ -10,7 +10,9 @@ import {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
+  type LocalJobsEngineOptions,
   type LocalJobsGeneration,
 } from "./local-jobs.js";
 
@@ -21,8 +23,8 @@ function jobDef(
   return { _kind: JOB_KIND, handler, ...extras };
 }
 
-function unavailable(feature: string): never {
-  throw new Error(`ctx.${feature} needs hosted Starbase. Run robodev deploy to use it.`);
+function notConfigured(code: string): never {
+  throw Object.assign(new Error(code), { statusCode: 400, code });
 }
 
 function mockClients(): RouteClients {
@@ -32,26 +34,45 @@ function mockClients(): RouteClients {
         return { id: "local_mail", status: "sent" };
       },
     },
-    llm: { complete: () => unavailable("llm"), stream: () => unavailable("llm") },
+    llm: {
+      complete: () => notConfigured("llm_not_configured"),
+      stream: () => notConfigured("llm_not_configured"),
+    },
     agent: {
-      createSession: () => unavailable("agent"),
-      start: () => unavailable("agent"),
-      events: () => unavailable("agent"),
-      subscribe: () => unavailable("agent"),
-      destroy: () => unavailable("agent"),
+      createSession: () => notConfigured("llm_not_configured"),
+      start: () => notConfigured("llm_not_configured"),
+      events: () => notConfigured("llm_not_configured"),
+      subscribe: () => notConfigured("llm_not_configured"),
+      destroy: () => notConfigured("llm_not_configured"),
     },
     storage: {
-      upload: () => unavailable("storage"),
-      get: () => unavailable("storage"),
-      getUrl: () => unavailable("storage"),
-      delete: () => unavailable("storage"),
-      list: () => unavailable("storage"),
+      async upload() {
+        return {
+          key: "x",
+          public: false,
+          size: 0,
+          contentType: "application/octet-stream",
+          url: "",
+        };
+      },
+      async get() {
+        return { body: Buffer.alloc(0), contentType: "application/octet-stream", public: false };
+      },
+      async getUrl() {
+        return "";
+      },
+      async delete() {
+        return undefined;
+      },
+      async list() {
+        return { objects: [], total: 0 };
+      },
     },
-    push: { send: () => unavailable("push") },
+    push: { send: () => notConfigured("push_not_configured") },
     jobs: { enqueue: async () => ({ id: "nested" }) },
     sockets: {
-      send: () => unavailable("sockets"),
-      broadcast: () => unavailable("sockets"),
+      send: () => undefined,
+      broadcast: () => undefined,
     },
     env: {},
   };
@@ -189,6 +210,7 @@ function engineFor(
   store: ReturnType<typeof memoryJobs>,
   jobs: LocalJobsGeneration["jobs"],
   logs: string[] = [],
+  onJobFinished?: LocalJobsEngineOptions["onJobFinished"],
 ) {
   const generation: LocalJobsGeneration = { db: {} as RobodevDb, jobs };
   return createLocalJobsEngine({
@@ -196,6 +218,7 @@ function engineFor(
     getGeneration: () => generation,
     log: (line) => logs.push(line),
     clients: mockClients,
+    onJobFinished,
   });
 }
 
@@ -418,7 +441,7 @@ test("hosted-only clients still throw in job handlers; email is real", async ()
   await engine.tickJobs();
   await waitUntil(() => store.jobs[0]?.status === "succeeded");
   assert.equal(seen[0], "email");
-  assert.match(seen[1] ?? "", /ctx\.llm needs hosted Starbase/);
+  assert.equal(seen[1], "llm_not_configured");
 });
 
 test("start resets running rows; stop clears timers", async () => {
@@ -446,3 +469,73 @@ test("start resets running rows; stop clears timers", async () => {
   assert.equal(engine.running, false);
   await engine.stop();
 });
+
+test("onJobFinished fires once per finishJob for succeeded, failed-retry, and dead", async () => {
+  const succeeded: LocalJobFinishedEvent[] = [];
+  const okStore = memoryJobs();
+  const ok = engineFor(okStore, [{ name: "digest", def: jobDef(() => undefined) }], [], (event) =>
+    succeeded.push(event),
+  );
+  await ok.enqueue({ name: "digest", payload: { n: 1 } });
+  await ok.tickJobs();
+  await waitUntil(() => succeeded.length === 1);
+  assert.equal(succeeded.length, 1);
+  assert.equal(succeeded[0]?.outcome, "succeeded");
+  assert.equal(succeeded[0]?.engineStatus, "succeeded");
+  assert.equal(succeeded[0]?.error, null);
+  assert.equal(succeeded[0]?.name, "digest");
+  assert.deepEqual(succeeded[0]?.payload, { n: 1 });
+
+  const retried: LocalJobFinishedEvent[] = [];
+  const retryStore = memoryJobs();
+  const retry = engineFor(
+    retryStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => retried.push(event),
+  );
+  await retry.enqueue({ name: "digest", payload: { n: 2 } });
+  await retry.tickJobs();
+  await waitUntil(() => retried.length === 1);
+  assert.equal(retried.length, 1);
+  assert.equal(retried[0]?.outcome, "failed");
+  assert.equal(retried[0]?.engineStatus, "queued");
+  assert.equal(retried[0]?.error, "boom");
+  assert.equal(retried[0]?.attempts, 1);
+  assert.deepEqual(retried[0]?.payload, { n: 2 });
+
+  const finished: LocalJobFinishedEvent[] = [];
+  const deadStore = memoryJobs();
+  const dying = engineFor(
+    deadStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => finished.push(event),
+  );
+  await dying.enqueue({ name: "digest" });
+  for (let attempt = 1; attempt <= JOB_MAX_ATTEMPTS; attempt++) {
+    deadStore.jobs[0]!.run_at = new Date(0);
+    deadStore.jobs[0]!.status = "queued";
+    await dying.tickJobs();
+    await waitUntil(() => finished.length === attempt);
+  }
+  assert.equal(finished.length, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.outcome, "failed");
+  assert.equal(finished.at(-1)?.engineStatus, "dead");
+  assert.equal(finished.at(-1)?.attempts, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.error, "boom");
+});

package/src/local-jobs.ts

@@ -49,11 +49,23 @@ export type LocalJobsGeneration = {
   jobs: readonly { name: string; file?: string; def: JobDefinition }[];
 };
 
+export type LocalJobFinishedEvent = {
+  id: string;
+  name: string;
+  payload: unknown;
+  outcome: "succeeded" | "failed";
+  engineStatus: "succeeded" | "queued" | "dead";
+  attempts: number;
+  error: string | null;
+};
+
 export type LocalJobsEngineOptions = {
   query: JobsQueryable["query"];
   getGeneration: () => LocalJobsGeneration | null;
   log?: (line: string) => void;
   clients: () => RouteClients;
+  /** Invoked after the job row UPDATE. Failed-retry (`queued`) and `dead` both report `failed`. */
+  onJobFinished?: (event: LocalJobFinishedEvent) => void;
 };
 
 export type LocalJobsEngine = {
@@ -221,6 +233,8 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
   }
 
   async function finishJob(row: LocalJobRow, error: string | null): Promise<void> {
+    let engineStatus: LocalJobFinishedEvent["engineStatus"];
+    let attempts = row.attempts;
     if (!error) {
       await query(
         `UPDATE robodev_jobs.jobs
@@ -229,21 +243,38 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
         [row.id],
       );
       log(`  ${row.name} succeeded`);
-      return;
-    }
-    const attempts = row.attempts + 1;
-    const next = nextJobFailureState(attempts);
-    await query(
-      `UPDATE robodev_jobs.jobs
-       SET status = $2, attempts = $3, last_error = $4, run_at = COALESCE($5, run_at), updated_at = now()
-       WHERE id = $1`,
-      [row.id, next.status, attempts, error, next.runAt],
-    );
-    if (next.status === "dead") {
-      log(`  ${row.name} dead: ${shortError(error)}`);
+      engineStatus = "succeeded";
     } else {
-      log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      attempts = row.attempts + 1;
+      const next = nextJobFailureState(attempts);
+      await query(
+        `UPDATE robodev_jobs.jobs
+         SET status = $2, attempts = $3, last_error = $4, run_at = COALESCE($5, run_at), updated_at = now()
+         WHERE id = $1`,
+        [row.id, next.status, attempts, error, next.runAt],
+      );
+      engineStatus = next.status;
+      if (next.status === "dead") {
+        log(`  ${row.name} dead: ${shortError(error)}`);
+      } else {
+        log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      }
+    }
+    let payload: unknown = null;
+    try {
+      payload = JSON.parse(row.payload_json) as unknown;
+    } catch {
+      payload = null;
     }
+    options.onJobFinished?.({
+      id: row.id,
+      name: row.name,
+      payload,
+      outcome: error ? "failed" : "succeeded",
+      engineStatus,
+      attempts,
+      error,
+    });
   }
 
   async function runClaimedJob(

package/src/local-storage.test.ts

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  createLocalStorageClient,
+  ensureStorageSchema,
+  resolveLocalObject,
+  type LocalObjectRow,
+  type StorageQueryable,
+} from "./local-storage.js";
+import { MAX_OBJECT_BYTES, verifyStorageServeToken } from "./storage-rules.js";
+
+const SECRET = "robodev-dev-local-secret";
+const PROJECT_ID = "prj-local";
+const BASE = "http://localhost:4000";
+
+function memoryStorage() {
+  const objects: LocalObjectRow[] = [];
+
+  const query: StorageQueryable["query"] = async (text, values = []) => {
+    const sql = text.replace(/\s+/g, " ").trim();
+    if (/^(CREATE SCHEMA|CREATE TABLE)/.test(sql)) return { rows: [] };
+
+    if (sql.includes("INSERT INTO robodev_storage.objects")) {
+      const key = String(values[0]);
+      const existing = objects.find((row) => row.key === key);
+      const created = existing?.created_at ?? new Date();
+      const row: LocalObjectRow = {
+        key,
+        public: Boolean(values[1]),
+        size_bytes: Number(values[2]),
+        content_type: String(values[3]),
+        created_at: created,
+      };
+      if (existing) {
+        existing.public = row.public;
+        existing.size_bytes = row.size_bytes;
+        existing.content_type = row.content_type;
+        return { rows: [existing] };
+      }
+      objects.push(row);
+      return { rows: [row] };
+    }
+
+    if (sql.includes("FROM robodev_storage.objects WHERE key =")) {
+      const row = objects.find((entry) => entry.key === values[0]);
+      return { rows: row ? [row] : [] };
+    }
+
+    if (sql.includes("DELETE FROM robodev_storage.objects")) {
+      const index = objects.findIndex((entry) => entry.key === values[0]);
+      if (index >= 0) objects.splice(index, 1);
+      return { rows: [] };
+    }
+
+    if (sql.includes("SELECT count(*)")) {
+      const like = String(values[0]).replace(/%$/, "");
+      const prefix = like.replace(/\\([\\%_])/g, "$1");
+      const matched = objects.filter((row) => row.key.startsWith(prefix));
+      return { rows: [{ count: String(matched.length) }] };
+    }
+
+    if (sql.includes("FROM robodev_storage.objects") && sql.includes("ORDER BY created_at")) {
+      const like = String(values[0]).replace(/%$/, "");
+      const prefix = like.replace(/\\([\\%_])/g, "$1");
+      const limit = Number(values[1]);
+      const offset = Number(values[2]);
+      const matched = objects
+        .filter((row) => row.key.startsWith(prefix))
+        .sort((a, b) => b.created_at.getTime() - a.created_at.getTime())
+        .slice(offset, offset + limit);
+      return { rows: matched };
+    }
+
+    throw new Error(`unhandled sql: ${sql}`);
+  };
+
+  return { objects, query };
+}
+
+async function withClient(
+  run: (
+    client: ReturnType<typeof createLocalStorageClient>,
+    objectsDir: string,
+    query: StorageQueryable["query"],
+  ) => Promise<void>,
+) {
+  const objectsDir = await mkdtemp(join(tmpdir(), "robodev-storage-"));
+  const store = memoryStorage();
+  const client = createLocalStorageClient({
+    query: store.query,
+    objectsDir,
+    publicBaseUrl: BASE,
+    projectId: PROJECT_ID,
+    jwtSecret: SECRET,
+  });
+  try {
+    await ensureStorageSchema({ query: store.query });
+    await run(client, objectsDir, store.query);
+  } finally {
+    await rm(objectsDir, { recursive: true, force: true });
+  }
+}
+
+test("upload get getUrl delete and list", async () => {
+  await withClient(async (client) => {
+    const uploaded = await client.upload("notes/hello.txt", "hello", {
+      public: true,
+      contentType: "text/plain",
+    });
+    assert.equal(uploaded.key, "notes/hello.txt");
+    assert.equal(uploaded.public, true);
+    assert.equal(uploaded.size, 5);
+    assert.equal(uploaded.contentType, "text/plain");
+    assert.equal(uploaded.url, `${BASE}/storage/objects/notes/hello.txt`);
+
+    const got = await client.get("notes/hello.txt");
+    assert.equal(got.body.toString("utf8"), "hello");
+    assert.equal(got.contentType, "text/plain");
+    assert.equal(got.public, true);
+
+    const listed = await client.list({ prefix: "notes/" });
+    assert.equal(listed.total, 1);
+    assert.equal(listed.objects[0]?.key, "notes/hello.txt");
+
+    await client.delete("notes/hello.txt");
+    await assert.rejects(
+      () => client.get("notes/hello.txt"),
+      (err: Error) => err.message === "Storage object not found: notes/hello.txt",
+    );
+  });
+});
+
+test("public URL has no query; private URL has exp and sig", async () => {
+  await withClient(async (client) => {
+    await client.upload("pub.bin", "a", { public: true });
+    await client.upload("priv.bin", "b", { public: false });
+    const publicUrl = await client.getUrl("pub.bin");
+    const privateUrl = await client.getUrl("priv.bin");
+    assert.equal(publicUrl, `${BASE}/storage/objects/pub.bin`);
+    assert.equal(publicUrl.includes("?"), false);
+    const parsed = new URL(privateUrl);
+    assert.equal(parsed.origin + parsed.pathname, `${BASE}/storage/objects/priv.bin`);
+    assert.ok(parsed.searchParams.get("exp"));
+    assert.ok(parsed.searchParams.get("sig"));
+    assert.equal(
+      verifyStorageServeToken(SECRET, PROJECT_ID, "priv.bin", {
+        exp: parsed.searchParams.get("exp"),
+        sig: parsed.searchParams.get("sig"),
+      }),
+      true,
+    );
+  });
+});
+
+test("overwrite updates metadata and keeps created_at", async () => {
+  await withClient(async (client, objectsDir, query) => {
+    await client.upload("same.txt", "one", { public: false, contentType: "text/plain" });
+    const first = await resolveLocalObject({ query, objectsDir, key: "same.txt" });
+    assert.ok(first);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const second = await client.upload("same.txt", "two-two", {
+      public: true,
+      contentType: "text/html",
+    });
+    assert.equal(second.public, true);
+    assert.equal(second.size, 7);
+    assert.equal(second.contentType, "text/html");
+    const after = await resolveLocalObject({ query, objectsDir, key: "same.txt" });
+    assert.ok(after);
+    assert.equal(after.row.created_at.getTime(), first.row.created_at.getTime());
+    assert.equal(after.body.toString("utf8"), "two-two");
+  });
+});
+
+test("missing key throws Storage object not found", async () => {
+  await withClient(async (client) => {
+    await assert.rejects(
+      () => client.get("missing.txt"),
+      (err: Error & { code?: string; statusCode?: number }) =>
+        err.message === "Storage object not found: missing.txt" &&
+        err.code === "not_found" &&
+        err.statusCode === 404,
+    );
+    await assert.rejects(
+      () => client.delete("missing.txt"),
+      (err: Error) => err.message === "Storage object not found: missing.txt",
+    );
+    await assert.rejects(
+      () => client.getUrl("missing.txt"),
+      (err: Error) => err.message === "Storage object not found: missing.txt",
+    );
+  });
+});
+
+test("object over 25MB is rejected", async () => {
+  await withClient(async (client) => {
+    await assert.rejects(
+      () => client.upload("big.bin", Buffer.alloc(MAX_OBJECT_BYTES + 1)),
+      (err: { code?: string; statusCode?: number }) =>
+        err.code === "object_too_large" && err.statusCode === 400,
+    );
+  });
+});
+
+test("list defaults to 50", async () => {
+  await withClient(async (client) => {
+    for (let i = 0; i < 52; i++) {
+      await client.upload(`n${String(i).padStart(2, "0")}.txt`, "x");
+    }
+    const listed = await client.list();
+    assert.equal(listed.objects.length, 50);
+    assert.equal(listed.total, 52);
+  });
+});

package/src/local-storage.ts

@@ -0,0 +1,213 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { StorageClient, StorageObject, StorageUploadOptions } from "@robodev-ai/sdk";
+import {
+  assertObjectSize,
+  mintStorageServeToken,
+  parseLogicalKey,
+  storageListQuerySchema,
+} from "./storage-rules.js";
+
+export type StorageQueryable = {
+  query: <T extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    values?: unknown[],
+  ) => Promise<{ rows: T[] }>;
+};
+
+export type LocalObjectRow = {
+  key: string;
+  public: boolean;
+  size_bytes: string | number;
+  content_type: string;
+  created_at: Date;
+};
+
+export type LocalStorageClientOptions = {
+  query: StorageQueryable["query"];
+  objectsDir: string;
+  publicBaseUrl: string;
+  projectId: string;
+  jwtSecret: string;
+};
+
+function notFound(key: string): never {
+  throw Object.assign(new Error(`Storage object not found: ${key}`), {
+    statusCode: 404,
+    code: "not_found",
+  });
+}
+
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
+
+function objectPath(objectsDir: string, key: string): string {
+  return join(objectsDir, ...key.split("/"));
+}
+
+function stableObjectUrl(publicBaseUrl: string, key: string): string {
+  return `${publicBaseUrl.replace(/\/$/, "")}/storage/objects/${key}`;
+}
+
+function toStorageObject(publicBaseUrl: string, row: LocalObjectRow): StorageObject {
+  return {
+    key: row.key,
+    public: row.public,
+    size: Number(row.size_bytes),
+    contentType: row.content_type,
+    url: stableObjectUrl(publicBaseUrl, row.key),
+  };
+}
+
+async function loadRow(
+  query: StorageQueryable["query"],
+  key: string,
+): Promise<LocalObjectRow | null> {
+  const result = await query<LocalObjectRow>(
+    `SELECT key, public, size_bytes, content_type, created_at
+     FROM robodev_storage.objects WHERE key = $1`,
+    [key],
+  );
+  return result.rows[0] ?? null;
+}
+
+async function readObjectFile(objectsDir: string, key: string): Promise<Buffer | null> {
+  try {
+    return await readFile(objectPath(objectsDir, key));
+  } catch {
+    return null;
+  }
+}
+
+/** Creates the reserved `robodev_storage` schema. Idempotent, not drizzle, not public. */
+export async function ensureStorageSchema(db: StorageQueryable): Promise<void> {
+  await db.query(`CREATE SCHEMA IF NOT EXISTS robodev_storage`);
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS robodev_storage.objects (
+      key TEXT PRIMARY KEY,
+      public BOOLEAN NOT NULL,
+      size_bytes INTEGER NOT NULL,
+      content_type TEXT NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+}
+
+export async function resolveLocalObject(input: {
+  query: StorageQueryable["query"];
+  objectsDir: string;
+  key: string;
+}): Promise<{ row: LocalObjectRow; body: Buffer } | null> {
+  const logicalKey = parseLogicalKey(input.key);
+  const row = await loadRow(input.query, logicalKey);
+  if (!row) return null;
+  const body = await readObjectFile(input.objectsDir, logicalKey);
+  if (!body) return null;
+  return { row, body };
+}
+
+export function createLocalStorageClient(options: LocalStorageClientOptions): StorageClient {
+  const query = options.query;
+  const objectsDir = options.objectsDir;
+  const publicBaseUrl = options.publicBaseUrl;
+
+  return {
+    async upload(key, data, upload?: StorageUploadOptions) {
+      const logicalKey = parseLogicalKey(key);
+      const contentType = upload?.contentType?.trim() || "application/octet-stream";
+      const isPublic = Boolean(upload?.public);
+      const buffer = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+      assertObjectSize(buffer.byteLength);
+
+      await mkdir(objectsDir, { recursive: true });
+      const dest = objectPath(objectsDir, logicalKey);
+      await mkdir(dirname(dest), { recursive: true });
+      const tmp = join(objectsDir, `.tmp-${randomBytes(8).toString("hex")}`);
+      await writeFile(tmp, buffer);
+      await rename(tmp, dest);
+
+      const result = await query<LocalObjectRow>(
+        `INSERT INTO robodev_storage.objects (key, public, size_bytes, content_type)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (key) DO UPDATE SET
+           public = EXCLUDED.public,
+           size_bytes = EXCLUDED.size_bytes,
+           content_type = EXCLUDED.content_type
+         RETURNING key, public, size_bytes, content_type, created_at`,
+        [logicalKey, isPublic, buffer.byteLength, contentType],
+      );
+      const row = result.rows[0];
+      if (!row) throw new Error("Failed to upsert storage metadata");
+      return toStorageObject(publicBaseUrl, row);
+    },
+
+    async get(key) {
+      const logicalKey = parseLogicalKey(key);
+      const resolved = await resolveLocalObject({ query, objectsDir, key: logicalKey });
+      if (!resolved) notFound(logicalKey);
+      return {
+        body: resolved.body,
+        contentType: resolved.row.content_type,
+        public: resolved.row.public,
+      };
+    },
+
+    async getUrl(key, urlOptions) {
+      const logicalKey = parseLogicalKey(key);
+      const row = await loadRow(query, logicalKey);
+      if (!row) notFound(logicalKey);
+      const body = await readObjectFile(objectsDir, logicalKey);
+      if (!body) notFound(logicalKey);
+      if (row.public) return stableObjectUrl(publicBaseUrl, logicalKey);
+      const { exp, sig } = mintStorageServeToken(
+        options.jwtSecret,
+        options.projectId,
+        logicalKey,
+        urlOptions?.expiresIn,
+      );
+      return `${stableObjectUrl(publicBaseUrl, logicalKey)}?exp=${exp}&sig=${sig}`;
+    },
+
+    async delete(key) {
+      const logicalKey = parseLogicalKey(key);
+      const row = await loadRow(query, logicalKey);
+      if (!row) notFound(logicalKey);
+      try {
+        await unlink(objectPath(objectsDir, logicalKey));
+      } catch {
+        /* ignore missing file */
+      }
+      await query(`DELETE FROM robodev_storage.objects WHERE key = $1`, [logicalKey]);
+    },
+
+    async list(listOptions) {
+      const parsed = storageListQuerySchema.parse({
+        prefix: listOptions?.prefix,
+        limit: listOptions?.limit,
+        offset: listOptions?.offset,
+      });
+      const prefix = parsed.prefix ?? "";
+      if (prefix) parseLogicalKey(prefix.replace(/\/+$/, "") || prefix);
+      const like = prefix ? `${escapeLike(prefix)}%` : "%";
+      const count = await query<{ count: string }>(
+        `SELECT count(*)::text AS count FROM robodev_storage.objects
+         WHERE key LIKE $1 ESCAPE E'\\\\'`,
+        [like],
+      );
+      const result = await query<LocalObjectRow>(
+        `SELECT key, public, size_bytes, content_type, created_at
+         FROM robodev_storage.objects
+         WHERE key LIKE $1 ESCAPE E'\\\\'
+         ORDER BY created_at DESC
+         LIMIT $2 OFFSET $3`,
+        [like, parsed.limit, parsed.offset],
+      );
+      return {
+        objects: result.rows.map((row) => toStorageObject(publicBaseUrl, row)),
+        total: Number(count.rows[0]?.count ?? 0),
+      };
+    },
+  };
+}

package/src/sockets.test.ts

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  MAX_PROJECT_SOCKETS,
+  MAX_SOCKET_PAYLOAD_BYTES,
+  SOCKET_CLOSE_INVALID,
+  SOCKET_CLOSE_POLICY,
+  SOCKET_CLOSE_TOO_BIG,
+  attachProjectSocket,
+  closeProjectSockets,
+  dispatchSocketsSend,
+  joinSocketRoom,
+  parseSocketMessage,
+  projectSocketCount,
+  sendToSocketRoom,
+  setProjectSocketNames,
+  stringifySocketPayload,
+} from "./sockets.js";
+
+function mockSocket() {
+  const sent: string[] = [];
+  let readyState = 1;
+  return {
+    sent,
+    get readyState() {
+      return readyState;
+    },
+    send(data: string) {
+      sent.push(data);
+    },
+    close() {
+      readyState = 3;
+    },
+  };
+}
+
+test("51st connection is rejected with 1008", () => {
+  const projectId = "sock-limit";
+  closeProjectSockets(projectId);
+  for (let i = 0; i < MAX_PROJECT_SOCKETS; i++) {
+    const attached = attachProjectSocket({
+      projectId,
+      name: "chat",
+      socket: mockSocket(),
+    });
+    assert.equal(attached.ok, true);
+  }
+  assert.equal(projectSocketCount(projectId), MAX_PROJECT_SOCKETS);
+  const extra = attachProjectSocket({
+    projectId,
+    name: "chat",
+    socket: mockSocket(),
+  });
+  assert.equal(extra.ok, false);
+  if (!extra.ok) {
+    assert.equal(extra.code, SOCKET_CLOSE_POLICY);
+  }
+  closeProjectSockets(projectId);
+  assert.equal(projectSocketCount(projectId), 0);
+});
+
+test("unknown socket name throws unknown_socket", () => {
+  setProjectSocketNames("sock-known", ["chat"]);
+  assert.throws(
+    () => dispatchSocketsSend("sock-known", ["chat"], { name: "missing", payload: { ok: true } }),
+    (err: { message?: string; code?: string }) =>
+      err.message === "unknown_socket" && err.code === "unknown_socket",
+  );
+});
+
+test("room broadcast stays on the same socket name", () => {
+  const projectId = "sock-rooms";
+  closeProjectSockets(projectId);
+  setProjectSocketNames(projectId, ["chat", "alerts"]);
+  const chatA = mockSocket();
+  const chatB = mockSocket();
+  const alerts = mockSocket();
+  const a = attachProjectSocket({ projectId, name: "chat", socket: chatA });
+  const b = attachProjectSocket({ projectId, name: "chat", socket: chatB });
+  const c = attachProjectSocket({ projectId, name: "alerts", socket: alerts });
+  assert.ok(a.ok && b.ok && c.ok);
+  if (!a.ok || !b.ok || !c.ok) return;
+  joinSocketRoom(a.conn, "lobby");
+  joinSocketRoom(b.conn, "lobby");
+  joinSocketRoom(c.conn, "lobby");
+  sendToSocketRoom(projectId, "chat", "lobby", JSON.stringify({ hi: true }), a.conn);
+  assert.deepEqual(chatA.sent, []);
+  assert.deepEqual(chatB.sent, [JSON.stringify({ hi: true })]);
+  assert.deepEqual(alerts.sent, []);
+  dispatchSocketsSend(projectId, ["chat", "alerts"], {
+    name: "chat",
+    room: "missing",
+    payload: { nope: true },
+  });
+  assert.deepEqual(chatA.sent, []);
+  assert.deepEqual(chatB.sent, [JSON.stringify({ hi: true })]);
+  closeProjectSockets(projectId);
+});
+
+test("JSON payload size is capped at 100KB", () => {
+  const ok = stringifySocketPayload({ ok: true });
+  assert.equal(ok, JSON.stringify({ ok: true }));
+  assert.throws(() => stringifySocketPayload("a".repeat(MAX_SOCKET_PAYLOAD_BYTES + 1)), /100KB/);
+  const parsed = parseSocketMessage('{"ok":true}');
+  assert.equal(parsed.ok, true);
+  const invalid = parseSocketMessage("{nope");
+  assert.equal(invalid.ok, false);
+  if (!invalid.ok) assert.equal(invalid.code, SOCKET_CLOSE_INVALID);
+  const tooBig = parseSocketMessage("a".repeat(MAX_SOCKET_PAYLOAD_BYTES + 1));
+  assert.equal(tooBig.ok, false);
+  if (!tooBig.ok) assert.equal(tooBig.code, SOCKET_CLOSE_TOO_BIG);
+});

package/src/sockets.ts

@@ -0,0 +1,293 @@
+import type {
+  ApiAuth,
+  SocketHandlerContext,
+  SocketRoomClient,
+  SocketsClient,
+} from "@robodev-ai/sdk";
+import { clampTimeoutMs, withHandlerTimeout } from "./handler-timeout.js";
+import { id } from "./ids.js";
+
+export const MAX_PROJECT_SOCKETS = 50;
+export const MAX_SOCKET_PAYLOAD_BYTES = 100 * 1024;
+export const SOCKET_IDLE_PING_MS = 60_000;
+export const SOCKET_CLOSE_POLICY = 1008;
+export const SOCKET_CLOSE_INVALID = 1007;
+export const SOCKET_CLOSE_TOO_BIG = 1009;
+export const SOCKET_CLOSE_RESTART = 1012;
+
+export type SocketWire = {
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+  readyState: number;
+};
+
+export type LiveConn = {
+  id: string;
+  projectId: string;
+  name: string;
+  socket: SocketWire;
+  rooms: Set<string>;
+};
+
+export type SocketSessionHelpers = {
+  send: (payload: unknown) => void;
+  close: (code?: number, reason?: string) => void;
+  room: SocketRoomClient;
+};
+
+export type BindSocketSessionInput = {
+  projectId: string;
+  name: string;
+  socket: SocketWire;
+  timeoutMs?: number;
+  createContext: (helpers: SocketSessionHelpers) => SocketHandlerContext;
+  onConnect?: (ctx: SocketHandlerContext) => Promise<void> | void;
+  onMessage: (ctx: SocketHandlerContext, value: unknown) => Promise<void> | void;
+  onClose?: (ctx: SocketHandlerContext) => Promise<void> | void;
+};
+
+const byProject = new Map<string, Set<LiveConn>>();
+const knownNamesByProject = new Map<string, string[]>();
+
+export function setProjectSocketNames(projectId: string, names: string[]): void {
+  knownNamesByProject.set(projectId, names);
+}
+
+export function stringifySocketPayload(payload: unknown): string {
+  const json = JSON.stringify(payload);
+  if (Buffer.byteLength(json, "utf8") > MAX_SOCKET_PAYLOAD_BYTES) {
+    throw new Error("socket payload must be at most 100KB");
+  }
+  return json;
+}
+
+export function parseSocketMessage(
+  raw: string,
+): { ok: true; value: unknown } | { ok: false; code: number } {
+  if (Buffer.byteLength(raw, "utf8") > MAX_SOCKET_PAYLOAD_BYTES) {
+    return { ok: false, code: SOCKET_CLOSE_TOO_BIG };
+  }
+  try {
+    return { ok: true, value: JSON.parse(raw) as unknown };
+  } catch {
+    return { ok: false, code: SOCKET_CLOSE_INVALID };
+  }
+}
+
+export function socketAuthDisplay(auth: ApiAuth): "required" | "public" {
+  return auth === "required" || typeof auth === "function" ? "required" : "public";
+}
+
+export function assertKnownSocket(name: string, known: Iterable<string>): void {
+  if (!new Set(known).has(name)) {
+    throw Object.assign(new Error("unknown_socket"), { code: "unknown_socket" });
+  }
+}
+
+export function projectSocketCount(projectId: string): number {
+  return byProject.get(projectId)?.size ?? 0;
+}
+
+export function closeProjectSockets(
+  projectId: string,
+  code = SOCKET_CLOSE_RESTART,
+  reason = "deployed",
+): void {
+  const set = byProject.get(projectId);
+  if (!set) return;
+  for (const conn of [...set]) {
+    try {
+      conn.socket.close(code, reason);
+    } catch {
+      /* already closed */
+    }
+  }
+  byProject.delete(projectId);
+  knownNamesByProject.delete(projectId);
+}
+
+export function attachProjectSocket(input: {
+  projectId: string;
+  name: string;
+  socket: SocketWire;
+}): { ok: true; conn: LiveConn } | { ok: false; code: number; reason: string } {
+  const current = byProject.get(input.projectId) ?? new Set<LiveConn>();
+  if (current.size >= MAX_PROJECT_SOCKETS) {
+    return { ok: false, code: SOCKET_CLOSE_POLICY, reason: "too_many_connections" };
+  }
+  const conn: LiveConn = {
+    id: id("sock"),
+    projectId: input.projectId,
+    name: input.name,
+    socket: input.socket,
+    rooms: new Set(),
+  };
+  current.add(conn);
+  byProject.set(input.projectId, current);
+  return { ok: true, conn };
+}
+
+export function detachProjectSocket(conn: LiveConn): void {
+  const set = byProject.get(conn.projectId);
+  if (!set) return;
+  set.delete(conn);
+  if (set.size === 0) byProject.delete(conn.projectId);
+}
+
+export function joinSocketRoom(conn: LiveConn, roomId: string): void {
+  conn.rooms.add(roomId);
+}
+
+export function leaveSocketRoom(conn: LiveConn, roomId: string): void {
+  conn.rooms.delete(roomId);
+}
+
+function sendRaw(socket: SocketWire, json: string): void {
+  if (socket.readyState !== 1) return;
+  socket.send(json);
+}
+
+export function sendToSocketName(projectId: string, name: string, json: string): void {
+  const set = byProject.get(projectId);
+  if (!set) return;
+  for (const conn of set) {
+    if (conn.name === name) sendRaw(conn.socket, json);
+  }
+}
+
+export function sendToSocketRoom(
+  projectId: string,
+  name: string,
+  roomId: string,
+  json: string,
+  except?: LiveConn,
+): void {
+  const set = byProject.get(projectId);
+  if (!set) return;
+  for (const conn of set) {
+    if (conn === except) continue;
+    if (conn.name === name && conn.rooms.has(roomId)) sendRaw(conn.socket, json);
+  }
+}
+
+export function dispatchSocketsSend(
+  projectId: string,
+  knownNames: Iterable<string>,
+  input: { name: string; room?: string; payload: unknown },
+): void {
+  assertKnownSocket(input.name, knownNames);
+  const json = stringifySocketPayload(input.payload);
+  if (input.room !== undefined) {
+    sendToSocketRoom(projectId, input.name, input.room, json);
+    return;
+  }
+  sendToSocketName(projectId, input.name, json);
+}
+
+export function createProjectSocketsClient(projectId: string): SocketsClient {
+  function knownNames(): string[] {
+    return knownNamesByProject.get(projectId) ?? [];
+  }
+  return {
+    send(input) {
+      dispatchSocketsSend(projectId, knownNames(), input);
+    },
+    broadcast(input) {
+      dispatchSocketsSend(projectId, knownNames(), input);
+    },
+  };
+}
+
+async function runSocketCallback(
+  timeoutMs: number | undefined,
+  run: () => Promise<void> | void,
+): Promise<void> {
+  await withHandlerTimeout(() => Promise.resolve(run()), clampTimeoutMs(timeoutMs));
+}
+
+export async function bindSocketSession(
+  input: BindSocketSessionInput,
+): Promise<
+  | { ok: false; code: number; reason: string }
+  | { ok: true; onText: (raw: string) => void; onBinary: () => void; onClose: () => void }
+> {
+  const attached = attachProjectSocket({
+    projectId: input.projectId,
+    name: input.name,
+    socket: input.socket,
+  });
+  if (!attached.ok) return attached;
+
+  const helpers: SocketSessionHelpers = {
+    send(payload) {
+      sendRaw(input.socket, stringifySocketPayload(payload));
+    },
+    close(code, reason) {
+      input.socket.close(code, reason);
+    },
+    room: {
+      join: (roomId) => joinSocketRoom(attached.conn, roomId),
+      leave: (roomId) => leaveSocketRoom(attached.conn, roomId),
+      broadcast: (roomId, payload) => {
+        sendToSocketRoom(
+          input.projectId,
+          input.name,
+          roomId,
+          stringifySocketPayload(payload),
+          attached.conn,
+        );
+      },
+    },
+  };
+
+  const ctx = input.createContext(helpers);
+
+  let closed = false;
+  const finish = async () => {
+    if (closed) return;
+    closed = true;
+    detachProjectSocket(attached.conn);
+    if (input.onClose) {
+      try {
+        await runSocketCallback(input.timeoutMs, () => input.onClose?.(ctx));
+      } catch {
+        /* onClose must not throw to the wire */
+      }
+    }
+  };
+
+  if (input.onConnect) {
+    try {
+      await runSocketCallback(input.timeoutMs, () => input.onConnect?.(ctx));
+    } catch {
+      input.socket.close(1011, "handler_failed");
+      await finish();
+      return { ok: false, code: 1011, reason: "handler_failed" };
+    }
+  }
+
+  return {
+    ok: true,
+    onText(raw) {
+      if (closed) return;
+      const parsed = parseSocketMessage(raw);
+      if (!parsed.ok) {
+        input.socket.close(
+          parsed.code,
+          parsed.code === SOCKET_CLOSE_TOO_BIG ? "too_big" : "invalid_json",
+        );
+        return;
+      }
+      void runSocketCallback(input.timeoutMs, () => input.onMessage(ctx, parsed.value)).catch(
+        () => undefined,
+      );
+    },
+    onBinary() {
+      if (closed) return;
+      input.socket.close(1003, "binary not supported");
+    },
+    onClose() {
+      void finish();
+    },
+  };
+}

package/src/storage-rules.test.ts

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  DEFAULT_LIST_LIMIT,
+  MAX_LIST_LIMIT,
+  MAX_OBJECT_BYTES,
+  PRESIGN_GET_DEFAULT,
+  PRESIGN_GET_MAX,
+  assertObjectSize,
+  mintStorageServeToken,
+  parseLogicalKey,
+  storageListQuerySchema,
+  verifyStorageServeToken,
+} from "./storage-rules.js";
+
+const SECRET = "robodev-dev-local-secret";
+
+test("parseLogicalKey accepts hosted-safe keys", () => {
+  assert.equal(parseLogicalKey("avatars/me.png"), "avatars/me.png");
+  assert.equal(parseLogicalKey("a"), "a");
+  assert.equal(parseLogicalKey("A-Za-z0.9_"), "A-Za-z0.9_");
+});
+
+test("parseLogicalKey rejects empty, slash, and .. segments", () => {
+  assert.throws(
+    () => parseLogicalKey(""),
+    (err: { code?: string; statusCode?: number }) =>
+      err.code === "invalid_key" && err.statusCode === 400,
+  );
+  assert.throws(
+    () => parseLogicalKey("/abs"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("../x"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("a/../b"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("a//b"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("a/./b"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("has space"),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+  assert.throws(
+    () => parseLogicalKey("x".repeat(513)),
+    (err: { code?: string }) => err.code === "invalid_key",
+  );
+});
+
+test("list query defaults and caps", () => {
+  const parsed = storageListQuerySchema.parse({});
+  assert.equal(parsed.limit, DEFAULT_LIST_LIMIT);
+  assert.equal(parsed.offset, 0);
+  assert.equal(parsed.prefix, undefined);
+  assert.equal(storageListQuerySchema.parse({ limit: 100 }).limit, MAX_LIST_LIMIT);
+  assert.throws(() => storageListQuerySchema.parse({ limit: 101 }));
+  assert.throws(() => storageListQuerySchema.parse({ offset: -1 }));
+});
+
+test("assertObjectSize uses 25MB", () => {
+  assertObjectSize(MAX_OBJECT_BYTES);
+  assert.throws(
+    () => assertObjectSize(MAX_OBJECT_BYTES + 1),
+    (err: { code?: string; statusCode?: number }) =>
+      err.code === "object_too_large" && err.statusCode === 400,
+  );
+});
+
+test("serve tokens verify until expiry", () => {
+  const { exp, sig } = mintStorageServeToken(SECRET, "prj-1", "avatars/me.png", 900);
+  assert.equal(
+    verifyStorageServeToken(SECRET, "prj-1", "avatars/me.png", { exp: String(exp), sig }),
+    true,
+  );
+  assert.equal(verifyStorageServeToken(SECRET, "prj-1", "other", { exp: String(exp), sig }), false);
+  assert.equal(
+    verifyStorageServeToken(SECRET, "prj-2", "avatars/me.png", { exp: String(exp), sig }),
+    false,
+  );
+  assert.equal(
+    verifyStorageServeToken(SECRET, "prj-1", "avatars/me.png", { exp: String(exp), sig: "nope" }),
+    false,
+  );
+  assert.equal(verifyStorageServeToken(SECRET, "prj-1", "avatars/me.png", {}), false);
+});
+
+test("expired serve tokens fail", () => {
+  const { sig } = mintStorageServeToken(SECRET, "prj-1", "file.bin", PRESIGN_GET_DEFAULT);
+  const exp = Math.floor(Date.now() / 1000) - 10;
+  assert.equal(
+    verifyStorageServeToken(SECRET, "prj-1", "file.bin", { exp: String(exp), sig }),
+    false,
+  );
+});
+
+test("expiresIn is clamped to 1 hour", () => {
+  const before = Math.floor(Date.now() / 1000);
+  const { exp } = mintStorageServeToken(SECRET, "prj-1", "file.bin", 10_000);
+  assert.ok(exp <= before + PRESIGN_GET_MAX + 1);
+});

package/src/storage-rules.ts

@@ -0,0 +1,80 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+
+export const MAX_OBJECT_BYTES = 25 * 1024 * 1024;
+export const DEFAULT_LIST_LIMIT = 50;
+export const MAX_LIST_LIMIT = 100;
+export const PRESIGN_GET_DEFAULT = 900;
+export const PRESIGN_GET_MAX = 3600;
+
+const KEY_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+
+export const storageListQuerySchema = z.object({
+  prefix: z.string().optional(),
+  limit: z.coerce.number().int().positive().max(MAX_LIST_LIMIT).default(DEFAULT_LIST_LIMIT),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+function codedError(statusCode: number, code: string, message: string): never {
+  throw Object.assign(new Error(message), { statusCode, code });
+}
+
+export function parseLogicalKey(key: string): string {
+  if (!key || key.length > 512) {
+    codedError(400, "invalid_key", "Storage key must be 1–512 characters.");
+  }
+  if (key.startsWith("/")) {
+    codedError(400, "invalid_key", "Storage key must not start with /.");
+  }
+  const segments = key.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    codedError(400, "invalid_key", "Storage key must not contain empty or .. segments.");
+  }
+  if (!KEY_RE.test(key)) {
+    codedError(400, "invalid_key", "Storage key may only contain A-Za-z0-9._- and /.");
+  }
+  return key;
+}
+
+export function assertObjectSize(size: number): void {
+  if (size > MAX_OBJECT_BYTES) {
+    codedError(400, "object_too_large", "File exceeds the 25MB limit.");
+  }
+}
+
+export function clampStorageExpiresIn(expiresIn?: number): number {
+  if (!expiresIn || !Number.isFinite(expiresIn)) return PRESIGN_GET_DEFAULT;
+  return Math.min(Math.max(Math.trunc(expiresIn), 1), PRESIGN_GET_MAX);
+}
+
+function serveSignature(secret: string, projectId: string, key: string, exp: number): string {
+  return createHmac("sha256", secret).update(`${projectId}\n${key}\n${exp}`).digest("hex");
+}
+
+export function mintStorageServeToken(
+  secret: string,
+  projectId: string,
+  key: string,
+  expiresIn?: number,
+): { exp: number; sig: string } {
+  const exp = Math.floor(Date.now() / 1000) + clampStorageExpiresIn(expiresIn);
+  return { exp, sig: serveSignature(secret, projectId, key, exp) };
+}
+
+export function verifyStorageServeToken(
+  secret: string,
+  projectId: string,
+  key: string,
+  query: { exp?: unknown; sig?: unknown },
+): boolean {
+  const expRaw = Array.isArray(query.exp) ? query.exp[0] : query.exp;
+  const sigRaw = Array.isArray(query.sig) ? query.sig[0] : query.sig;
+  if (typeof expRaw !== "string" && typeof expRaw !== "number") return false;
+  if (typeof sigRaw !== "string" || !sigRaw) return false;
+  const exp = Number(expRaw);
+  if (!Number.isFinite(exp) || exp <= Math.floor(Date.now() / 1000)) return false;
+  const expected = serveSignature(secret, projectId, key, Math.trunc(exp));
+  const given = sigRaw.toLowerCase();
+  if (expected.length !== given.length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(given));
+}