Add Vercel Blob emulator support (#175)

* Add Vercel Blob emulator support

- Add stateful Vercel Blob emulation for put, head, list, delete, and public object serving

- Cover Blob SDK behavior with @vercel/blob tests and register blob storage in service metadata

- Document Blob configuration and make seeded Vercel user IDs stable

* Fix Vercel Blob OIDC store resolution

* Fix Vercel Blob copy and store scoping

Author: ctate

README.md

@@ -520,6 +520,24 @@ Every endpoint below is fully stateful with Vercel-style JSON responses and curs
 - `PATCH /v9/projects/:idOrName/env/:id` - update env var
 - `DELETE /v9/projects/:idOrName/env/:id` - delete env var
 
+### Blob
+Implements the Vercel Blob API used by the `@vercel/blob` SDK (`put`, `head`, `list`, `del`).
+
+- `PUT /api/blob?pathname=<path>` - upload a blob (honors `x-add-random-suffix`, `x-allow-overwrite`, `x-content-type`, `x-cache-control-max-age`, `x-if-match` headers)
+- `GET /api/blob?url=<urlOrPathname>` - blob metadata (`head()`)
+- `GET /api/blob?prefix=&limit=&cursor=&mode=` - list blobs (`list()`, including folded mode)
+- `POST /api/blob/delete` - delete blobs (`del()`)
+- `GET /blob/:storeId/<pathname>` - serve blob content (public, no auth; `?download=1` adds an attachment disposition)
+
+Point the SDK at the emulator with two environment variables:
+
+```bash
+VERCEL_BLOB_API_URL=http://localhost:4000/api/blob
+BLOB_READ_WRITE_TOKEN=vercel_blob_rw_mystore_secret
+```
+
+Any token of the form `vercel_blob_rw_<storeId>_<secret>` is accepted; the store id is parsed from the token. Multipart uploads and client (browser) uploads are not supported yet.
+
 ## GitHub API
 
 Every endpoint below is fully stateful. Creates, updates, and deletes persist in memory and affect related entities.

apps/web/app/docs/vercel/page.mdx

@@ -51,3 +51,22 @@ Every endpoint below is fully stateful with Vercel-style JSON responses and curs
 - `GET /v10/projects/:idOrName/env/:id` - get env var
 - `PATCH /v9/projects/:idOrName/env/:id` - update env var
 - `DELETE /v9/projects/:idOrName/env/:id` - delete env var
+
+## Blob
+
+Implements the Vercel Blob API used by the `@vercel/blob` SDK (`put`, `head`, `list`, `del`).
+
+- `PUT /api/blob?pathname=<path>` - upload a blob (honors `x-add-random-suffix`, `x-allow-overwrite`, `x-content-type`, `x-cache-control-max-age`, `x-if-match` headers)
+- `GET /api/blob?url=<urlOrPathname>` - blob metadata (`head()`)
+- `GET /api/blob?prefix=&limit=&cursor=&mode=` - list blobs (`list()`, including folded mode)
+- `POST /api/blob/delete` - delete blobs (`del()`)
+- `GET /blob/:storeId/<pathname>` - serve blob content (public, no auth; `?download=1` adds an attachment disposition)
+
+Point the SDK at the emulator with two environment variables:
+
+```bash
+VERCEL_BLOB_API_URL=http://localhost:4000/api/blob
+BLOB_READ_WRITE_TOKEN=vercel_blob_rw_mystore_secret
+```
+
+Any token of the form `vercel_blob_rw_<storeId>_<secret>` is accepted; the store id is parsed from the token. Multipart uploads and client (browser) uploads are not supported yet.

packages/@emulators/vercel/package.json

@@ -38,6 +38,7 @@
     "@emulators/core": "workspace:*"
   },
   "devDependencies": {
+    "@vercel/blob": "^2.4.0",
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0"

packages/@emulators/vercel/src/__tests__/blob.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { randomBytes } from "node:crypto";
+import type { AddressInfo } from "node:net";
+import { Hono, serve } from "@emulators/core";
+import { Store, WebhookDispatcher, authMiddleware, type TokenMap } from "@emulators/core";
+import { put, head, list, del, copy, BlobNotFoundError, BlobAccessError } from "@vercel/blob";
+import { vercelPlugin } from "../index.js";
+
+const token = "vercel_blob_rw_teststore_secret";
+const storeId = "teststore";
+
+let emulatorUrl: string;
+let apiUrl: string;
+let closeServer: () => Promise<void>;
+
+beforeAll(async () => {
+  const store = new Store();
+  const webhooks = new WebhookDispatcher();
+  const tokenMap: TokenMap = new Map();
+  const app = new Hono();
+  app.use("*", authMiddleware(tokenMap));
+
+  const server = serve({ fetch: app.fetch, port: 0 });
+  await new Promise<void>((resolve, reject) => {
+    server.once("listening", () => resolve());
+    server.once("error", reject);
+  });
+  const { port } = server.address() as AddressInfo;
+  emulatorUrl = `http://127.0.0.1:${port}`;
+  apiUrl = `${emulatorUrl}/api/blob`;
+
+  // Blob URLs embed the base URL, so register routes after the port is known.
+  vercelPlugin.register(app as any, store, webhooks, emulatorUrl, tokenMap);
+  vercelPlugin.seed?.(store, emulatorUrl);
+
+  process.env.VERCEL_BLOB_API_URL = apiUrl;
+  process.env.BLOB_READ_WRITE_TOKEN = token;
+
+  closeServer = () =>
+    new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+});
+
+afterAll(async () => {
+  delete process.env.VERCEL_BLOB_API_URL;
+  delete process.env.BLOB_READ_WRITE_TOKEN;
+  await closeServer();
+});
+
+describe("Vercel Blob via the @vercel/blob SDK", () => {
+  it("put uploads bytes and the returned url serves them back", async () => {
+    const data = randomBytes(1024);
+    const result = await put("round-trip/data.bin", data, { access: "public", token });
+
+    expect(result.pathname).toBe("round-trip/data.bin");
+    expect(result.url).toBe(`${emulatorUrl}/blob/${storeId}/round-trip/data.bin`);
+    expect(result.contentType).toBe("application/octet-stream");
+    expect(result.contentDisposition).toBe('attachment; filename="data.bin"');
+
+    const res = await fetch(result.url);
+    expect(res.status).toBe(200);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(data)).toBe(true);
+    expect(res.headers.get("etag")).toBe(result.etag);
+    expect(res.headers.get("cache-control")).toBe("public, max-age=2592000");
+  });
+
+  it("put with addRandomSuffix appends a suffix before the extension", async () => {
+    const result = await put("suffix/report.txt", "hello suffix", {
+      access: "public",
+      token,
+      addRandomSuffix: true,
+    });
+
+    expect(result.pathname).toMatch(/^suffix\/report-[a-z0-9]+\.txt$/);
+    expect(result.pathname).not.toBe("suffix/report.txt");
+
+    const res = await fetch(result.url);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("hello suffix");
+    expect(res.headers.get("content-type")).toContain("text/plain");
+  });
+
+  it("put with allowOverwrite: false rejects when the blob already exists", async () => {
+    await put("conflict/file.txt", "first", { access: "public", token });
+    await expect(
+      put("conflict/file.txt", "second", { access: "public", token, allowOverwrite: false }),
+    ).rejects.toThrow(/allowOverwrite/);
+
+    // The original content is untouched and allowOverwrite: true replaces it.
+    const before = await fetch(`${emulatorUrl}/blob/${storeId}/conflict/file.txt`);
+    expect(await before.text()).toBe("first");
+
+    await put("conflict/file.txt", "second", { access: "public", token, allowOverwrite: true });
+    const after = await fetch(`${emulatorUrl}/blob/${storeId}/conflict/file.txt`);
+    expect(await after.text()).toBe("second");
+  });
+
+  it("head returns blob metadata", async () => {
+    const uploaded = await put("meta/info.json", JSON.stringify({ ok: true }), {
+      access: "public",
+      token,
+      cacheControlMaxAge: 60,
+    });
+
+    const meta = await head(uploaded.url, { token });
+    expect(meta.pathname).toBe("meta/info.json");
+    expect(meta.url).toBe(uploaded.url);
+    expect(meta.downloadUrl).toBe(uploaded.downloadUrl);
+    expect(meta.size).toBe(Buffer.byteLength(JSON.stringify({ ok: true })));
+    expect(meta.contentType).toBe("application/json");
+    expect(meta.contentDisposition).toBe('attachment; filename="info.json"');
+    expect(meta.cacheControl).toBe("public, max-age=60");
+    expect(meta.etag).toBe(uploaded.etag);
+    expect(meta.uploadedAt).toBeInstanceOf(Date);
+    expect(Number.isNaN(meta.uploadedAt.getTime())).toBe(false);
+  });
+
+  it("head falls back to BLOB_READ_WRITE_TOKEN when no token option is given", async () => {
+    const uploaded = await put("meta/env-token.txt", "env token", { access: "public", token });
+    const meta = await head(uploaded.url);
+    expect(meta.pathname).toBe("meta/env-token.txt");
+  });
+
+  it("put accepts SDK OIDC auth with an explicit storeId", async () => {
+    const uploaded = await put("auth/oidc.txt", "oidc token", {
+      access: "public",
+      oidcToken: "local-oidc-token",
+      storeId,
+    });
+
+    expect(uploaded.url).toBe(`${emulatorUrl}/blob/${storeId}/auth/oidc.txt`);
+    const res = await fetch(uploaded.url);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("oidc token");
+  });
+
+  it("copy duplicates source content into the destination blob", async () => {
+    const source = await put("copy/source.txt", "copy me", { access: "public", token });
+    const copied = await copy(source.url, "copy/dest.txt", { access: "public", token });
+
+    expect(copied.pathname).toBe("copy/dest.txt");
+    const res = await fetch(copied.url);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("copy me");
+
+    const meta = await head(copied.url, { token });
+    expect(meta.size).toBe("copy me".length);
+    expect(meta.etag).toBe(source.etag);
+  });
+
+  it("list filters by prefix and returns metadata", async () => {
+    await put("listing/a.txt", "a", { access: "public", token });
+    await put("listing/b.txt", "b", { access: "public", token });
+    await put("other/c.txt", "c", { access: "public", token });
+
+    const result = await list({ prefix: "listing/", token });
+    const pathnames = result.blobs.map((b) => b.pathname);
+    expect(pathnames).toEqual(["listing/a.txt", "listing/b.txt"]);
+    expect(result.hasMore).toBe(false);
+    for (const blob of result.blobs) {
+      expect(blob.url).toBe(`${emulatorUrl}/blob/${storeId}/${blob.pathname}`);
+      expect(blob.size).toBe(1);
+      expect(blob.uploadedAt).toBeInstanceOf(Date);
+      expect(blob.etag).toMatch(/^"[0-9a-f]{64}"$/);
+    }
+  });
+
+  it("list paginates with limit and cursor", async () => {
+    await put("paging/1.txt", "1", { access: "public", token });
+    await put("paging/2.txt", "2", { access: "public", token });
+    await put("paging/3.txt", "3", { access: "public", token });
+
+    const first = await list({ prefix: "paging/", limit: 2, token });
+    expect(first.blobs.map((b) => b.pathname)).toEqual(["paging/1.txt", "paging/2.txt"]);
+    expect(first.hasMore).toBe(true);
+    expect(first.cursor).toBeDefined();
+
+    const second = await list({ prefix: "paging/", cursor: first.cursor, token });
+    expect(second.blobs.map((b) => b.pathname)).toEqual(["paging/3.txt"]);
+    expect(second.hasMore).toBe(false);
+  });
+
+  it("del removes a blob and head then rejects with BlobNotFoundError", async () => {
+    const uploaded = await put("deletion/gone.txt", "bye", { access: "public", token });
+    await del(uploaded.url, { token });
+
+    await expect(head(uploaded.url, { token })).rejects.toBeInstanceOf(BlobNotFoundError);
+    const res = await fetch(uploaded.url);
+    expect(res.status).toBe(404);
+  });
+
+  it("full blob URLs cannot target a different authenticated store", async () => {
+    const otherToken = "vercel_blob_rw_otherstore_secret";
+    const own = await put("store-scope/shared.txt", "own", { access: "public", token });
+    const other = await put("store-scope/shared.txt", "other", { access: "public", token: otherToken });
+
+    await expect(head(other.url, { token })).rejects.toBeInstanceOf(BlobNotFoundError);
+
+    await del(other.url, { token });
+    const ownRes = await fetch(own.url);
+    const otherRes = await fetch(other.url);
+    expect(ownRes.status).toBe(200);
+    expect(await ownRes.text()).toBe("own");
+    expect(otherRes.status).toBe(200);
+    expect(await otherRes.text()).toBe("other");
+  });
+
+  it("downloadUrl serves the content with an attachment disposition", async () => {
+    const uploaded = await put("downloads/manual.txt", "download me", { access: "public", token });
+
+    const res = await fetch(uploaded.downloadUrl);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-disposition")).toBe('attachment; filename="manual.txt"');
+    expect(await res.text()).toBe("download me");
+
+    // The plain url has no attachment disposition.
+    const inline = await fetch(uploaded.url);
+    expect(inline.headers.get("content-disposition")).toBeNull();
+  });
+
+  it("a bad token surfaces as BlobAccessError", async () => {
+    await expect(list({ token: "not-a-blob-token" })).rejects.toBeInstanceOf(BlobAccessError);
+  });
+});
+
+describe("Vercel Blob direct HTTP error shapes", () => {
+  it("returns a 403 forbidden JSON body for a bad token", async () => {
+    const res = await fetch(apiUrl, { headers: { authorization: "Bearer wrong" } });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string; message: string } };
+    expect(body.error.code).toBe("forbidden");
+    expect(typeof body.error.message).toBe("string");
+  });
+
+  it("returns a 404 not_found JSON body when head misses", async () => {
+    const res = await fetch(`${apiUrl}?url=${encodeURIComponent("missing/never-uploaded.txt")}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string; message: string } };
+    expect(body.error.code).toBe("not_found");
+    expect(body.error.message).toBe("The requested blob does not exist");
+  });
+});

packages/@emulators/vercel/src/entities.ts

@@ -236,6 +236,18 @@ export interface VercelApiKey extends Entity {
   tokenString: string;
 }
 
+export interface VercelBlob extends Entity {
+  pathname: string;
+  storeId: string;
+  contentType: string;
+  contentDisposition: string;
+  cacheControl: string;
+  size: number;
+  etag: string;
+  uploadedAt: string;
+  dataBase64: string;
+}
+
 export interface VercelIntegration extends Entity {
   client_id: string;
   client_secret: string;

packages/@emulators/vercel/src/helpers.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import type { Context } from "@emulators/core";
 import type {
   VercelUser,
@@ -17,6 +17,17 @@ export function generateUid(prefix = ""): string {
   return prefix ? `${prefix}_${id}` : id;
 }
 
+/**
+ * Deterministic uid for seeded entities. Seeded identities must be stable
+ * across emulator restarts: downstream apps key accounts on the OIDC sub,
+ * and a regenerated uid for the same seeded user creates a duplicate
+ * account in the app after every restart.
+ */
+export function stableUid(prefix: string, seedKey: string): string {
+  const id = createHash("sha256").update(seedKey).digest("base64url").slice(0, 20);
+  return `${prefix}_${id}`;
+}
+
 export function generateSecret(): string {
   return randomBytes(32).toString("base64url");
 }

packages/@emulators/vercel/src/index.ts

@@ -2,14 +2,15 @@ import type { Hono } from "@emulators/core";
 import type { AppEnv, RouteContext, ServicePlugin, Store, WebhookDispatcher, TokenMap } from "@emulators/core";
 import type { VercelEnvVar } from "./entities.js";
 import { getVercelStore } from "./store.js";
-import { generateUid, nowMs } from "./helpers.js";
+import { generateUid, nowMs, stableUid } from "./helpers.js";
 import { userRoutes } from "./routes/user.js";
 import { projectsRoutes } from "./routes/projects.js";
 import { deploymentsRoutes } from "./routes/deployments.js";
 import { domainsRoutes } from "./routes/domains.js";
 import { envRoutes } from "./routes/env.js";
 import { oauthRoutes } from "./routes/oauth.js";
 import { apiKeysRoutes } from "./routes/api-keys.js";
+import { blobRoutes } from "./routes/blob.js";
 
 export { getVercelStore, type VercelStore } from "./store.js";
 export * from "./entities.js";
@@ -53,7 +54,7 @@ function seedDefaults(store: Store, _baseUrl: string): void {
   const vs = getVercelStore(store);
 
   vs.users.insert({
-    uid: generateUid("user"),
+    uid: stableUid("user", "vercel.user.admin"),
     email: "admin@localhost",
     username: "admin",
     name: "Admin",
@@ -75,7 +76,7 @@ export function seedFromConfig(store: Store, baseUrl: string, config: VercelSeed
       const existing = vs.users.findOneBy("username", u.username);
       if (existing) continue;
       vs.users.insert({
-        uid: generateUid("user"),
+        uid: stableUid("user", `vercel.user.${u.username}`),
         email: u.email ?? `${u.username}@localhost`,
         username: u.username,
         name: u.name ?? null,
@@ -218,6 +219,7 @@ export const vercelPlugin: ServicePlugin = {
     domainsRoutes(ctx);
     envRoutes(ctx);
     apiKeysRoutes(ctx);
+    blobRoutes(ctx);
   },
   seed(store: Store, baseUrl: string): void {
     seedDefaults(store, baseUrl);