@spooky-sync/core 0.0.1-canary.330 → 0.0.1-canary.331

package/AGENTS.md

@@ -35,7 +35,7 @@ re-materialized from state, never patched in place.
 
 - `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button and shifts the page down onto a hazard-striped layer. `impersonationBanner` in the client config restyles it (`theme`), replaces it (`mode: 'custom'` + `client.acknowledgeImpersonationBanner()`, else it falls back after ~2.5s) or turns it off (`mode: 'none'`). See `/docs/client/impersonation`. Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)` (queries a user waits on; a query that already shows rows and is only re-registering, as after a reload, is not counted). Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
 - `FailedMutation` — a row of the `_00_failed_mutations` tray (`mutationType`, `recordId`, `data`, `beforeRecord`, `error`, `revert`).
-- `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
+- `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache. A bucket generated with `backend: 'r2'` (`BACKEND "r2"`) sends its bytes to the SSP over HTTP (`<files.endpoint>/bucket/<name>/<path>`, bearer = the session token from `RemoteDatabaseService.getAuthToken()`) instead of `f"bucket:/path"` statements; the SSP checks `fn::_00_bucket::<name>` as the user first.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.
 - `AuthService` — token management, sign-in/sign-out events. `subscribe(cb, { immediate? })` calls `cb` at once with the current user unless `immediate: false`, then on every change.
 - `CrdtManager`, `CrdtField`, `cursorColorFromName`, `CURSOR_COLORS`: collaborative `@crdt` fields on Loro. Client methods: `openCrdtField(table, recordId, field, draft?)` -> `Promise<CrdtField>` (every open of one field in a tab shares one `LoroDoc`; pair each with a close), `closeCrdtField(table, recordId, field)` -> `Promise<void>` (resolves once unsent edits are in the outbox; offline, once they are saved on the device, never waiting on the network), `createCrdtDraft(table, field)` -> a detached `CrdtField` for a record not created yet (`db.create` first, then pass it to `openCrdtField` as `draft`). `CrdtField`: `getDoc()`, `hasContent()`, `pushCursorState(bytes)`, `onCursorUpdate = cb` (a setter). Config: `crdt: true` preloads Loro, `crdtDebounceMs` (default 300, max wait 2 s). Design: `docs/crdt-v2.md` at the repo root.

package/dist/index.d.ts

@@ -1985,13 +1985,21 @@ interface BucketHandleSettings {
   logger?: {
     warn: (obj: unknown, msg?: string) => void;
   };
+  /** The bucket's backend as generated (`'r2'`: files live with the SSP). */
+  backend?: string;
+  /** {@link Sp00kyConfig.files}: where `r2` bucket files are read and written. */
+  files?: {
+    endpoint?: string;
+  };
 }
+/** A handle's settings from the client config and the bucket's generated schema. */
+
 declare class BucketHandle {
   private bucketName;
-  private remote;
   /** Absent on the raw handle the cache itself reads through. */
   private blobs?;
   private settings?;
+  private io;
   constructor(bucketName: string, remote: RemoteDatabaseService, /** Absent on the raw handle the cache itself reads through. */
   blobs?: (BlobCache | null) | undefined, settings?: BucketHandleSettings | undefined);
   /** Effective blurhash setting: per-call option > client config > default ON. */

package/dist/index.js

@@ -2188,8 +2188,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.330";
-const WASM_VERSION = "0.0.1-canary.330";
+const CORE_VERSION = "0.0.1-canary.331";
+const WASM_VERSION = "0.0.1-canary.331";
 const SURREAL_VERSION = "3.1.0";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -8544,6 +8544,11 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 	setAuthToken(token) {
 		this.authToken = token;
 	}
+	/** The token the session is signed in with (or the configured one), for
+	*  calls that leave the socket: `r2` bucket files go to the SSP over HTTP. */
+	getAuthToken() {
+		return this.authToken ?? this.getConfig().token ?? null;
+	}
 	/** Resolved reconnect tunables; the supervisor reads its own knobs here. */
 	getReconnectConfig() {
 		return this.reconnectConfig;
@@ -15150,6 +15155,122 @@ function bucketContentToBlob(content) {
 	if (ArrayBuffer.isView(content)) return new Blob([content]);
 	return null;
 }
+/** A handle's settings from the client config and the bucket's generated schema. */
+function bucketSettings(config, name, logger) {
+	const backend = config.schema.buckets?.find((b) => b.name === name)?.backend;
+	return {
+		blurhash: config.blurhash,
+		logger,
+		backend,
+		files: config.files
+	};
+}
+/** `f"bucket:/path"` statements over the database connection. */
+function surrealIo(bucket, remote) {
+	const file = (path) => `f"${bucket}:/${path}"`;
+	return {
+		async put(path, content) {
+			await remote.query(`RETURN ${file(path)}.put($content);`, { content });
+		},
+		async get(path) {
+			const [result] = await remote.query(`RETURN ${file(path)}.get();`);
+			return result;
+		},
+		async delete(path) {
+			await remote.query(`RETURN ${file(path)}.delete();`);
+		},
+		async exists(path) {
+			const [result] = await remote.query(`RETURN ${file(path)}.exists();`);
+			return result;
+		},
+		async head(path) {
+			const [result] = await remote.query(`RETURN ${file(path)}.head();`);
+			return result;
+		},
+		async copy(sourcePath, targetPath) {
+			await remote.query(`RETURN ${file(sourcePath)}.copy($target);`, { target: targetPath });
+		},
+		async rename(sourcePath, targetPath) {
+			await remote.query(`RETURN ${file(sourcePath)}.rename($target);`, { target: targetPath });
+		},
+		async list(prefix) {
+			const [result] = await remote.query(`RETURN ${file(prefix)}.list();`);
+			return result;
+		}
+	};
+}
+/**
+* `BACKEND "r2"` buckets: the SSP keeps the files (R2 on Cloudflare, a
+* directory under `spky dev`) and serves them at `/bucket/<name>/<key>`,
+* after asking SurrealDB, as the signed-in user, whether the bucket's
+* PERMISSIONS clause allows it. The request carries the session's token.
+*/
+function sspIo(bucket, remote, endpoint) {
+	const base = () => {
+		if (!endpoint) throw new Error(`Bucket '${bucket}' is stored with the SSP (BACKEND "r2"): set \`files.endpoint\` in the client config to the SSP's URL.`);
+		return endpoint.replace(/\/+$/, "");
+	};
+	const url = (path) => `${base()}/bucket/${encodeURIComponent(bucket)}/${path.split("/").filter(Boolean).map(encodeURIComponent).join("/")}`;
+	const send = async (method, path, body, contentType) => {
+		const headers = {};
+		const token = remote.getAuthToken();
+		if (token) headers.Authorization = `Bearer ${token}`;
+		if (contentType) headers["Content-Type"] = contentType;
+		const response = await fetch(url(path), {
+			method,
+			headers,
+			body,
+			credentials: "omit"
+		});
+		if (!response.ok && response.status !== 404) {
+			let message = response.statusText;
+			try {
+				message = (await response.json()).error ?? message;
+			} catch {}
+			throw new Error(`Bucket '${bucket}' ${method} ${path} failed (${response.status}): ${message}`);
+		}
+		return response;
+	};
+	const op = async (path, body) => {
+		const response = await send("POST", path, JSON.stringify(body), "application/json");
+		if (response.status === 404) return null;
+		return await response.json();
+	};
+	const missing = (path) => /* @__PURE__ */ new Error(`Bucket '${bucket}': no file at ${path}`);
+	return {
+		async put(path, content) {
+			await send("PUT", path, content, (content instanceof Blob ? content.type : void 0) || "application/octet-stream");
+		},
+		async get(path) {
+			const response = await send("GET", path);
+			return response.status === 404 ? null : await response.blob();
+		},
+		async delete(path) {
+			await send("DELETE", path);
+		},
+		async exists(path) {
+			return await op(path, { op: "exists" }) ?? false;
+		},
+		async head(path) {
+			return await op(path, { op: "head" });
+		},
+		async copy(sourcePath, targetPath) {
+			if (await op(sourcePath, {
+				op: "copy",
+				target: targetPath
+			}) === null) throw missing(sourcePath);
+		},
+		async rename(sourcePath, targetPath) {
+			if (await op(sourcePath, {
+				op: "rename",
+				target: targetPath
+			}) === null) throw missing(sourcePath);
+		},
+		async list() {
+			throw new Error(`Bucket '${bucket}': listing is not available (BACKEND "r2")`);
+		}
+	};
+}
 /**
 * Paths known to have no blurhash sidecar, per tab. The blob cache has no
 * negative caching, so without this every mount of a hashless image would pay
@@ -15158,11 +15279,12 @@ function bucketContentToBlob(content) {
 */
 const missingBlurhash = /* @__PURE__ */ new Set();
 var BucketHandle = class {
+	io;
 	constructor(bucketName, remote, blobs, settings) {
 		this.bucketName = bucketName;
-		this.remote = remote;
 		this.blobs = blobs;
 		this.settings = settings;
+		this.io = settings?.backend === "r2" ? sspIo(bucketName, remote, settings.files?.endpoint) : surrealIo(bucketName, remote);
 	}
 	/** Effective blurhash setting: per-call option > client config > default ON. */
 	resolveBlurhash(option) {
@@ -15173,7 +15295,7 @@ var BucketHandle = class {
 	async put(path, content, options) {
 		const encodeOptions = this.resolveBlurhash(options?.blurhash);
 		const hashPromise = encodeOptions && isImagePath(path) ? encodeImageToBlurhash(content, encodeOptions) : Promise.resolve(null);
-		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+		await this.io.put(path, content);
 		await this.blobs?.invalidate({
 			bucket: this.bucketName,
 			path
@@ -15183,7 +15305,7 @@ var BucketHandle = class {
 			hash = await hashPromise;
 			if (hash) {
 				const sidecar = blurhashSidecarPath(path);
-				await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, { content: hash });
+				await this.io.put(sidecar, hash);
 				await this.blobs?.invalidate({
 					bucket: this.bucketName,
 					path: sidecar
@@ -15231,8 +15353,7 @@ var BucketHandle = class {
 		}
 	}
 	async get(path) {
-		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".get();`);
-		return result;
+		return this.io.get(path);
 	}
 	/**
 	* Read through the local blob cache: OPFS first, the bucket second. Unlike
@@ -15286,7 +15407,7 @@ var BucketHandle = class {
 		})));
 	}
 	async delete(path) {
-		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+		await this.io.delete(path);
 		await this.blobs?.invalidate({
 			bucket: this.bucketName,
 			path
@@ -15294,7 +15415,7 @@ var BucketHandle = class {
 		if (isImagePath(path)) {
 			const sidecar = blurhashSidecarPath(path);
 			try {
-				await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+				await this.io.delete(sidecar);
 				await this.blobs?.invalidate({
 					bucket: this.bucketName,
 					path: sidecar
@@ -15304,23 +15425,19 @@ var BucketHandle = class {
 		}
 	}
 	async exists(path) {
-		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".exists();`);
-		return result;
+		return this.io.exists(path);
 	}
 	async head(path) {
-		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".head();`);
-		return result;
+		return this.io.head(path);
 	}
 	async copy(sourcePath, targetPath) {
-		await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, { target: targetPath });
+		await this.io.copy(sourcePath, targetPath);
 	}
 	async rename(sourcePath, targetPath) {
-		await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, { target: targetPath });
+		await this.io.rename(sourcePath, targetPath);
 	}
 	async list(prefix) {
-		const p = prefix ?? "";
-		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${p}".list();`);
-		return result;
+		return this.io.list(prefix ?? "");
 	}
 };
 
@@ -15405,10 +15522,7 @@ function createServices(config) {
 	const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
 	const remote = new RemoteDatabaseService(config.database, logger);
 	const connectionSupervisor = new ConnectionSupervisor(remote, logger);
-	const rawBucket = (name) => new BucketHandle(name, remote, null, {
-		blurhash: config.blurhash,
-		logger
-	});
+	const rawBucket = (name) => new BucketHandle(name, remote, null, bucketSettings(config, name, logger));
 	const blobs = createBlobCache({
 		local,
 		namespace: ANON_USER_ID,
@@ -15453,7 +15567,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.330",
+			coreVersion: "0.0.1-canary.331",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -16564,10 +16678,7 @@ var Sp00kyClient = class {
 		return this.services.crdt.close(table, recordId, field);
 	}
 	bucket(name) {
-		return new BucketHandle(name, this.services.remote, this.services.blobs, {
-			blurhash: this.config.blurhash,
-			logger: this.services.logger
-		});
+		return new BucketHandle(name, this.services.remote, this.services.blobs, bucketSettings(this.config, name, this.services.logger));
 	}
 	getBlobCacheStats() {
 		return this.services.blobs.stats();

package/dist/types.d.ts

@@ -733,6 +733,9 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
    * from-scratch connect reproduce that state.
    */
   setAuthToken(token: string | null): void;
+  /** The token the session is signed in with (or the configured one), for
+   *  calls that leave the socket: `r2` bucket files go to the SSP over HTTP. */
+  getAuthToken(): string | null;
   /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
   getReconnectConfig(): Required<ReconnectConfig>;
   /** Current transport state as reported by the SDK. */
@@ -1707,6 +1710,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
     componentX?: number;
     componentY?: number;
   };
+  /**
+   * Buckets declared `BACKEND "r2"` keep their files with the SSP (R2 on
+   * Cloudflare, a directory under `spky dev`) instead of in SurrealDB, which
+   * on Surreal Cloud can only hold memory buckets. `endpoint` is the SSP's
+   * URL: `spky dev` and `spky deploy` hand it to Vite as
+   * `VITE_SPKY_FILES_ENDPOINT`.
+   */
+  files?: {
+    endpoint?: string;
+  };
   /**
    * Deadline (ms) for a single outgoing mutation push. Tighter than
    * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.330",
+  "version": "0.0.1-canary.331",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.330",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.330",
+    "@spooky-sync/query-builder": "0.0.1-canary.331",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.331",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.1.0",
     "@surrealdb/wasm-native": "^3.3.4",

package/src/client/bucket-handle.test.ts

@@ -115,3 +115,81 @@ describe('BucketHandle', () => {
     expect(calls.some(([s]) => s === 'RETURN f"files:/pre/".list();')).toBe(true);
   });
 });
+
+describe('r2 buckets (files with the SSP)', () => {
+  function fakeSsp(files: Record<string, string> = {}) {
+    const requests: Array<{ method: string; url: string; auth: string | null; body: unknown }> = [];
+    const fetchMock = vi.fn(async (url: string, init: RequestInit) => {
+      const headers = (init.headers ?? {}) as Record<string, string>;
+      requests.push({ method: init.method ?? 'GET', url, auth: headers.Authorization ?? null, body: init.body });
+      const key = decodeURIComponent(new URL(url).pathname.replace(/^\/bucket\/[^/]+\//, ''));
+      const json = (status: number, value: unknown) => new Response(JSON.stringify(value), { status });
+      if (headers.Authorization !== 'Bearer tok') return json(401, { error: 'invalid or expired token' });
+      switch (init.method) {
+        case 'PUT':
+          files[key] = typeof init.body === 'string' ? init.body : 'bytes';
+          return json(200, { ok: true });
+        case 'GET':
+          return key in files ? new Response(files[key], { status: 200 }) : json(404, { error: 'no such file' });
+        case 'DELETE':
+          delete files[key];
+          return json(200, { ok: true });
+        default: {
+          const op = JSON.parse(String(init.body));
+          if (op.op === 'exists') return json(200, key in files);
+          if (op.op === 'head') return json(200, key in files ? { key: `/${key}`, size: files[key].length } : null);
+          if (!(key in files)) return json(404, { error: 'no such file' });
+          files[op.target] = files[key];
+          if (op.op === 'rename') delete files[key];
+          return json(200, { ok: true });
+        }
+      }
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    return { requests, files };
+  }
+
+  const remote = (token: string | null = 'tok') => ({ getAuthToken: () => token, query: vi.fn() }) as any;
+  const r2 = (r = remote()) =>
+    new BucketHandle('pics', r, null, { backend: 'r2', files: { endpoint: 'https://app.db.example/' }, blurhash: false });
+
+  it('reads and writes over HTTP with the session token, never the database socket', async () => {
+    const { requests, files } = fakeSsp();
+    const db = remote();
+    const h = r2(db);
+    await h.put('u1/a b.png', 'PNG');
+    expect(files['u1/a b.png']).toBe('PNG');
+    expect(requests[0]).toMatchObject({ method: 'PUT', url: 'https://app.db.example/bucket/pics/u1/a%20b.png', auth: 'Bearer tok' });
+    expect(await ((await h.get('u1/a b.png')) as Blob).text()).toBe('PNG');
+    expect(await h.get('missing.png')).toBeNull();
+    expect(await h.exists('u1/a b.png')).toBe(true);
+    expect(await h.head('u1/a b.png')).toEqual({ key: '/u1/a b.png', size: 3 });
+    await h.copy('u1/a b.png', 'u1/c.png');
+    await h.rename('u1/c.png', 'u1/d.png');
+    expect(Object.keys(files).sort()).toEqual(['u1/a b.png', 'u1/d.png']);
+    await expect(h.copy('nope.png', 'x.png')).rejects.toThrow(/no file/);
+    await h.delete('u1/a b.png');
+    expect(await h.exists('u1/a b.png')).toBe(false);
+    await expect(h.list()).rejects.toThrow(/listing/);
+    expect(db.query).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it('surfaces refusals and a missing endpoint as errors', async () => {
+    fakeSsp({ 'a.png': 'x' });
+    await expect(r2(remote(null)).get('a.png')).rejects.toThrow(/401.*invalid or expired token/);
+    const noEndpoint = new BucketHandle('pics', remote(), null, { backend: 'r2', files: {} });
+    await expect(noEndpoint.get('a.png')).rejects.toThrow(/files\.endpoint/);
+    vi.unstubAllGlobals();
+  });
+
+  it('a bucket without backend r2 keeps using the database', async () => {
+    const db = { getAuthToken: () => 'tok', query: vi.fn(async () => ['content']) } as any;
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    const h = new BucketHandle('pics', db, null, { files: { endpoint: 'https://app.db.example' } });
+    expect(await h.get('a.png')).toBe('content');
+    expect(fetchMock).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});

package/src/client/bucket-handle.ts

@@ -34,6 +34,143 @@ export interface BucketPutResult {
 interface BucketHandleSettings {
   blurhash?: BlurhashSetting;
   logger?: { warn: (obj: unknown, msg?: string) => void };
+  /** The bucket's backend as generated (`'r2'`: files live with the SSP). */
+  backend?: string;
+  /** {@link Sp00kyConfig.files}: where `r2` bucket files are read and written. */
+  files?: { endpoint?: string };
+}
+
+/** A handle's settings from the client config and the bucket's generated schema. */
+export function bucketSettings(
+  config: { blurhash?: BlurhashSetting; files?: { endpoint?: string }; schema: { buckets?: readonly { name: string; backend?: string }[] } },
+  name: string,
+  logger: { warn: (obj: unknown, msg?: string) => void }
+): BucketHandleSettings {
+  const backend = config.schema.buckets?.find((b) => b.name === name)?.backend;
+  return { blurhash: config.blurhash, logger, backend, files: config.files };
+}
+
+/** Where a bucket's bytes go: SurrealDB itself, or the SSP for `r2` buckets. */
+interface BucketIo {
+  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  /** The file, or null when it does not exist. */
+  get(path: string): Promise<unknown>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  head(path: string): Promise<Record<string, unknown>>;
+  copy(sourcePath: string, targetPath: string): Promise<void>;
+  rename(sourcePath: string, targetPath: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}
+
+/** `f"bucket:/path"` statements over the database connection. */
+function surrealIo(bucket: string, remote: RemoteDatabaseService): BucketIo {
+  const file = (path: string) => `f"${bucket}:/${path}"`;
+  return {
+    async put(path, content) {
+      await remote.query(`RETURN ${file(path)}.put($content);`, { content });
+    },
+    async get(path) {
+      const [result] = await remote.query<[unknown]>(`RETURN ${file(path)}.get();`);
+      return result;
+    },
+    async delete(path) {
+      await remote.query(`RETURN ${file(path)}.delete();`);
+    },
+    async exists(path) {
+      const [result] = await remote.query<[boolean]>(`RETURN ${file(path)}.exists();`);
+      return result;
+    },
+    async head(path) {
+      const [result] = await remote.query<[Record<string, unknown>]>(`RETURN ${file(path)}.head();`);
+      return result;
+    },
+    async copy(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.copy($target);`, { target: targetPath });
+    },
+    async rename(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.rename($target);`, { target: targetPath });
+    },
+    async list(prefix) {
+      const [result] = await remote.query<[string[]]>(`RETURN ${file(prefix)}.list();`);
+      return result;
+    },
+  };
+}
+
+/**
+ * `BACKEND "r2"` buckets: the SSP keeps the files (R2 on Cloudflare, a
+ * directory under `spky dev`) and serves them at `/bucket/<name>/<key>`,
+ * after asking SurrealDB, as the signed-in user, whether the bucket's
+ * PERMISSIONS clause allows it. The request carries the session's token.
+ */
+function sspIo(bucket: string, remote: RemoteDatabaseService, endpoint: string | undefined): BucketIo {
+  const base = () => {
+    if (!endpoint) {
+      throw new Error(
+        `Bucket '${bucket}' is stored with the SSP (BACKEND "r2"): set \`files.endpoint\` in the client config to the SSP's URL.`
+      );
+    }
+    return endpoint.replace(/\/+$/, '');
+  };
+  const url = (path: string) =>
+    `${base()}/bucket/${encodeURIComponent(bucket)}/${path
+      .split('/')
+      .filter(Boolean)
+      .map(encodeURIComponent)
+      .join('/')}`;
+  const send = async (method: string, path: string, body?: BodyInit, contentType?: string): Promise<Response> => {
+    const headers: Record<string, string> = {};
+    const token = remote.getAuthToken();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (contentType) headers['Content-Type'] = contentType;
+    const response = await fetch(url(path), { method, headers, body, credentials: 'omit' });
+    if (!response.ok && response.status !== 404) {
+      let message = response.statusText;
+      try {
+        message = ((await response.json()) as { error?: string }).error ?? message;
+      } catch {
+        // Not JSON: keep the status text.
+      }
+      throw new Error(`Bucket '${bucket}' ${method} ${path} failed (${response.status}): ${message}`);
+    }
+    return response;
+  };
+  const op = async <T>(path: string, body: Record<string, unknown>): Promise<T | null> => {
+    const response = await send('POST', path, JSON.stringify(body), 'application/json');
+    if (response.status === 404) return null;
+    return (await response.json()) as T;
+  };
+  const missing = (path: string) => new Error(`Bucket '${bucket}': no file at ${path}`);
+  return {
+    async put(path, content) {
+      const type = content instanceof Blob ? content.type : undefined;
+      await send('PUT', path, content as BodyInit, type || 'application/octet-stream');
+    },
+    async get(path) {
+      const response = await send('GET', path);
+      return response.status === 404 ? null : await response.blob();
+    },
+    async delete(path) {
+      await send('DELETE', path);
+    },
+    async exists(path) {
+      return (await op<boolean>(path, { op: 'exists' })) ?? false;
+    },
+    async head(path) {
+      return (await op<Record<string, unknown>>(path, { op: 'head' })) as Record<string, unknown>;
+    },
+    async copy(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'copy', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async rename(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'rename', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async list() {
+      // SurrealDB refuses `list` to record users; the SSP does too.
+      throw new Error(`Bucket '${bucket}': listing is not available (BACKEND "r2")`);
+    },
+  };
 }
 
 /**
@@ -45,13 +182,20 @@ interface BucketHandleSettings {
 const missingBlurhash = new Set<string>();
 
 export class BucketHandle {
+  private io: BucketIo;
+
   constructor(
     private bucketName: string,
-    private remote: RemoteDatabaseService,
+    remote: RemoteDatabaseService,
     /** Absent on the raw handle the cache itself reads through. */
     private blobs?: BlobCache | null,
     private settings?: BucketHandleSettings
-  ) {}
+  ) {
+    this.io =
+      settings?.backend === 'r2'
+        ? sspIo(bucketName, remote, settings.files?.endpoint)
+        : surrealIo(bucketName, remote);
+  }
 
   /** Effective blurhash setting: per-call option > client config > default ON. */
   private resolveBlurhash(option?: BlurhashSetting): BlurhashEncodeOptions | null {
@@ -73,7 +217,7 @@ export class BucketHandle {
         ? encodeImageToBlurhash(content, encodeOptions)
         : Promise.resolve(null);
 
-    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+    await this.io.put(path, content);
     // A path can be overwritten, so anything cached under it is now wrong.
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
 
@@ -84,9 +228,7 @@ export class BucketHandle {
       hash = await hashPromise;
       if (hash) {
         const sidecar = blurhashSidecarPath(path);
-        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, {
-          content: hash,
-        });
+        await this.io.put(sidecar, hash);
         await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
         missingBlurhash.delete(`${this.bucketName}:${path}`);
       }
@@ -128,10 +270,7 @@ export class BucketHandle {
   }
 
   async get(path: string): Promise<unknown> {
-    const [result] = await this.remote.query<[unknown]>(
-      `RETURN f"${this.bucketName}:/${path}".get();`
-    );
-    return result;
+    return this.io.get(path);
   }
 
   /**
@@ -174,14 +313,14 @@ export class BucketHandle {
   }
 
   async delete(path: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+    await this.io.delete(path);
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
     // Symmetry with put: an image's blurhash sidecar dies with it. Best-effort,
     // the sidecar may simply not exist.
     if (isImagePath(path)) {
       const sidecar = blurhashSidecarPath(path);
       try {
-        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+        await this.io.delete(sidecar);
         await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
       } catch {
         // Nothing to clean up.
@@ -191,37 +330,23 @@ export class BucketHandle {
   }
 
   async exists(path: string): Promise<boolean> {
-    const [result] = await this.remote.query<[boolean]>(
-      `RETURN f"${this.bucketName}:/${path}".exists();`
-    );
-    return result;
+    return this.io.exists(path);
   }
 
   async head(path: string): Promise<Record<string, unknown>> {
-    const [result] = await this.remote.query<[Record<string, unknown>]>(
-      `RETURN f"${this.bucketName}:/${path}".head();`
-    );
-    return result;
+    return this.io.head(path);
   }
 
   async copy(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, {
-      target: targetPath,
-    });
+    await this.io.copy(sourcePath, targetPath);
   }
 
   async rename(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, {
-      target: targetPath,
-    });
+    await this.io.rename(sourcePath, targetPath);
   }
 
   async list(prefix?: string): Promise<string[]> {
-    const p = prefix ?? '';
-    const [result] = await this.remote.query<[string[]]>(
-      `RETURN f"${this.bucketName}:/${p}".list();`
-    );
-    return result;
+    return this.io.list(prefix ?? '');
   }
 }
 

package/src/client/services.ts

@@ -32,7 +32,7 @@ import { sha256Hex } from '../utils/sha256';
 import { leaveViewsBeacon, listRefLive } from '../query/sql';
 import { hashOfEdge, rowOfEdge } from '../utils/edges';
 import { mintMutationId } from '../mutation/mutation-id';
-import { BucketHandle, bucketContentToBlob } from './bucket-handle';
+import { BucketHandle, bucketContentToBlob, bucketSettings } from './bucket-handle';
 
 const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
 
@@ -157,7 +157,7 @@ export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S
   const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
   const remote = new RemoteDatabaseService(config.database, logger);
   const connectionSupervisor = new ConnectionSupervisor(remote, logger);
-  const rawBucket = (name: string) => new BucketHandle(name, remote, null, { blurhash: config.blurhash, logger });
+  const rawBucket = (name: string) => new BucketHandle(name, remote, null, bucketSettings(config, name, logger));
   const blobs = createBlobCache({
     local,
     namespace: ANON_USER_ID,

package/src/client/sp00ky-client.ts

@@ -54,7 +54,7 @@ import { preload } from '../boot/preload.saga';
 import { DEGRADE_AFTER_FAILURES, OUTBOX_BATCH_SIZE, PUSH_TIMEOUT_MS } from '../kernel/constants';
 import { Runtime } from './runtime';
 import { createAdapters, createServices, createTabsCoordinator, type ServiceHost, type Services } from './services';
-import { BucketHandle } from './bucket-handle';
+import { BucketHandle, bucketSettings } from './bucket-handle';
 import { ImpersonationBanner } from '../modules/auth/impersonation-banner';
 import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
 
@@ -615,7 +615,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
-    return new BucketHandle(name, this.services.remote, this.services.blobs, { blurhash: this.config.blurhash, logger: this.services.logger });
+    return new BucketHandle(name, this.services.remote, this.services.blobs, bucketSettings(this.config, name, this.services.logger));
   }
 
   getBlobCacheStats() {

package/src/services/database/remote.ts

@@ -222,6 +222,12 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
     this.authToken = token;
   }
 
+  /** The token the session is signed in with (or the configured one), for
+   *  calls that leave the socket: `r2` bucket files go to the SSP over HTTP. */
+  getAuthToken(): string | null {
+    return this.authToken ?? this.getConfig().token ?? null;
+  }
+
   /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
   getReconnectConfig(): Required<ReconnectConfig> {
     return this.reconnectConfig;

package/src/types.ts

@@ -371,6 +371,14 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * A per-call `put(path, content, { blurhash })` option overrides this.
    */
   blurhash?: boolean | { componentX?: number; componentY?: number };
+  /**
+   * Buckets declared `BACKEND "r2"` keep their files with the SSP (R2 on
+   * Cloudflare, a directory under `spky dev`) instead of in SurrealDB, which
+   * on Surreal Cloud can only hold memory buckets. `endpoint` is the SSP's
+   * URL: `spky dev` and `spky deploy` hand it to Vite as
+   * `VITE_SPKY_FILES_ENDPOINT`.
+   */
+  files?: { endpoint?: string };
   /**
    * Deadline (ms) for a single outgoing mutation push. Tighter than
    * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains