@spooky-sync/core 0.0.1-canary.250 → 0.0.1-canary.256

package/AGENTS.md

@@ -50,6 +50,7 @@ re-materialized from state, never patched in place.
 - **`db.update` takes `(table, id, payload, options?)`**. The `debounced` option (`{ debounced: true }` or `{ debounced: { delay, key } }`) coalesces rapid updates — use it for CRDT text/title fields.
 - **`db.remoteQuery(sql, vars?)` is the one-shot remote read.** It runs one SurrealQL statement through the client's remote path (connect gate, per-statement timeout, concurrency limit) and returns the SurrealDB result array; results are not synced into the local cache. Use it for counts and other reads the query builder can't express.
 - **`db.useRemote(fn)` hands out the bare SDK client.** Same cache bypass, but it skips the connect gate (a call during a reconnect fails with "Specify a namespace to use"). Reserve it for SDK features `remoteQuery` cannot reach (transactions, `live`).
+- **Raw remote calls are gated by the query allowlist.** When the generated schema carries `policy.queryAllowlist: 'warn' | 'enforce'` (from `sync.queryAllowlist` in `sp00ky.yml`), `remoteQuery`, `useRemote` and `queryRaw` throw unless the client config sets `allowRawRemote: true`; builder queries are unaffected. A registration the SSP refuses as not allowlisted (403 `not_allowlisted`) is marked `remote: 'failed'` after one attempt with an error-level log carrying the surql and a `spky generate` hint; the view stays cold (`membershipKnown` false), it is never read as confirmed empty.
 - **`@parent` columns are auto-populated.** Defined in the `.surql` schema as `record<user>` with the `-- @parent` annotation; never write them yourself — they're set from the auth context server-side.
 - **`db.preload` is a registered query.** Resolved before on this device (a `_00_view` row exists) it returns at once; never resolved it waits until the server's membership and every body are local. It holds no subscriber, so it is evicted a ttl after registration unless a view mounts the same query. `refresh`/`staleTime` are ignored; pass `signal` to abort a cold wait.
 - **A rejected write is not lost.** Application errors roll the local row back (create/update/delete) and move the mutation to `_00_failed_mutations`; the tray API above lists, retries (as a fresh write) or discards it. Network errors keep the row queued.

package/dist/index.d.ts

@@ -2255,6 +2255,12 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   query<Table extends TableNames<S>>(table: Table, options: QueryOptions<TableModel<GetTable<S, Table>>, false>, ttl?: QueryTimeToLive): QueryBuilder<S, Table, Sp00kyQueryResultPromise>;
   private registerInput;
   private initQuery;
+  /**
+   * The raw remote escape hatches bypass the query builder, so their shapes
+   * can never be on the server's query allowlist. When the generated schema
+   * says the allowlist is on, refuse them unless the app opted in explicitly.
+   */
+  private assertRawRemoteAllowed;
   queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string>;
   /**
    * Preload = register a query nobody subscribes to. Resolved before on this

package/dist/index.js

@@ -1073,8 +1073,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.250";
-const WASM_VERSION = "0.0.1-canary.250";
+const CORE_VERSION = "0.0.1-canary.256";
+const WASM_VERSION = "0.0.1-canary.256";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -3219,6 +3219,13 @@ function* ensureRegistered(env, opts = {}) {
 }
 const stmt = (results, i) => results[i];
 /**
+* The SSP answers a registration whose shape is not on the query allowlist
+* with HTTP 403 `{"error":"not_allowlisted"}`. It reaches the client as the
+* `fn::query::register` statement error carrying SurrealDB's http error text
+* (status reason and/or body), and no retry can change the answer.
+*/
+const isNotAllowlisted = (error) => /not_allowlisted|\b403\b|forbidden/i.test(String(error?.message ?? error));
+/**
 * One remote registration: `fn::query::register` plus the edge/meta/children
 * read in ONE request, then membership application. Concurrent with every
 * other registration; retried on its own backoff; stops when the entry is
@@ -3260,6 +3267,27 @@ function* registerRemote(env, hash, retry = false) {
 	} catch (error) {
 		const current = yield fx.state.read((s) => s.queries.get(hash));
 		if (!current) return;
+		if (isNotAllowlisted(error)) {
+			yield fx.state.update(applyLifecycle(hash, { type: "remote-failed" }));
+			yield fx.emit({
+				type: "log",
+				level: "error",
+				message: "query refused: not allowlisted",
+				data: {
+					hash,
+					table: entry.def.tableName,
+					surql: entry.def.surql,
+					params: Object.keys(entry.def.params),
+					hint: "Add or regenerate the query allowlist: spky generate, then spky deploy (or restart spky dev)."
+				}
+			});
+			yield fx.dispatch({
+				type: "SyncOutcome",
+				ok: false,
+				error
+			});
+			return;
+		}
 		const attempts = current.registerAttempts + 1;
 		yield fx.state.update(bumpRegisterAttempts(hash));
 		yield fx.emit({
@@ -12516,7 +12544,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.250",
+			coreVersion: "0.0.1-canary.256",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -12993,7 +13021,17 @@ var Sp00kyClient = class {
 	initQuery(table, q, ttl) {
 		return this.runtime.run(registerLocal(this.env, this.registerInput(table, q, ttl)));
 	}
+	/**
+	* The raw remote escape hatches bypass the query builder, so their shapes
+	* can never be on the server's query allowlist. When the generated schema
+	* says the allowlist is on, refuse them unless the app opted in explicitly.
+	*/
+	assertRawRemoteAllowed(method) {
+		const mode = this.config.schema.policy?.queryAllowlist;
+		if ((mode === "warn" || mode === "enforce") && !this.config.allowRawRemote) throw new Error(`sp00ky: ${method} is disabled because sync.queryAllowlist is on for this schema; pass allowRawRemote: true in the client config to opt in`);
+	}
 	async queryRaw(sql, params, ttl) {
+		this.assertRawRemoteAllowed("queryRaw");
 		const tableName = sql.split("FROM ")[1]?.split(" ")[0] ?? "";
 		return this.runtime.run(registerLocal(this.env, {
 			tableName,
@@ -13144,9 +13182,11 @@ var Sp00kyClient = class {
 		return this.services.remote.getClient().invalidate();
 	}
 	async useRemote(fn) {
+		this.assertRawRemoteAllowed("useRemote");
 		return fn(this.services.remote.getClient());
 	}
 	async remoteQuery(sql, vars) {
+		this.assertRawRemoteAllowed("remoteQuery");
 		return this.services.remote.query(sql, vars);
 	}
 	feature(key, options) {

package/dist/types.d.ts

@@ -628,6 +628,15 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * one-shot but never sync live.
    */
   enableAnonymousLiveQueries?: boolean;
+  /**
+   * Opt in to the raw remote escape hatches (`useRemote`, `remoteQuery`,
+   * `queryRaw`) when the generated schema's `policy.queryAllowlist` is `warn`
+   * or `enforce`. With the allowlist on, the server only accepts query shapes
+   * that `spky generate` collected from the query builder, so a hand-written
+   * SurrealQL string cannot be allowlisted and these methods throw unless this
+   * flag is `true`. Defaults to `false`.
+   */
+  allowRawRemote?: boolean;
   /**
    * Surface sustained sync failures as a "degraded" health status that the app
    * can observe via `subscribeToSyncHealth` (or the client-solid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.250",
+  "version": "0.0.1-canary.256",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -63,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.250",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.250",
+    "@spooky-sync/query-builder": "0.0.1-canary.256",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.256",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/client/sp00ky-client.test.ts

@@ -225,6 +225,29 @@ describe('Sp00kyClient facade (builder, devtools source, event fan-out)', () =>
     runtime.emit({ type: 'activity:changed', fetching: 0, pending: 4 });
     expect(pending).toEqual([0, 4]);
   });
+  it('gates queryRaw/useRemote/remoteQuery behind allowRawRemote when the schema policy turns the allowlist on', async () => {
+    const services = fakeServiceBundle<any>();
+    const a = fakeAdapters({});
+    const runtime = new Runtime({ env: defaultEnv(schema), adapters: a.adapters, logger: services.logger, tabId: 't' });
+    const withPolicy = (mode: string | undefined, allowRawRemote?: boolean) =>
+      new Sp00kyClient<any>(
+        { ...config, schema: mode === undefined ? schema : { ...schema, policy: { queryAllowlist: mode } }, allowRawRemote } as any,
+        { services, runtime }
+      );
+    const msg = (m: string) => `sp00ky: ${m} is disabled because sync.queryAllowlist is on for this schema; pass allowRawRemote: true in the client config to opt in`;
+    for (const mode of ['warn', 'enforce']) {
+      const gated = withPolicy(mode);
+      await expect(gated.queryRaw('SELECT * FROM thing', {}, '10m')).rejects.toThrow(msg('queryRaw'));
+      await expect(gated.useRemote(() => 1)).rejects.toThrow(msg('useRemote'));
+      await expect(gated.remoteQuery('RETURN 1')).rejects.toThrow(msg('remoteQuery'));
+      expect(a.names().filter((n) => n === 'remote.query')).toEqual([]);
+    }
+    for (const client of [withPolicy('enforce', true), withPolicy('off'), withPolicy(undefined)]) {
+      await expect(client.useRemote(() => 1)).resolves.toBe(1);
+      await expect(client.remoteQuery('RETURN 1')).resolves.toBeDefined();
+    }
+  });
+
   it('honours config knobs when building the saga env', () => {
     const services = fakeServiceBundle<any>();
     const a = fakeAdapters();

package/src/client/sp00ky-client.ts

@@ -269,7 +269,22 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.runtime.run(registerLocal(this.env, this.registerInput(table, q, ttl)));
   }
 
+  /**
+   * The raw remote escape hatches bypass the query builder, so their shapes
+   * can never be on the server's query allowlist. When the generated schema
+   * says the allowlist is on, refuse them unless the app opted in explicitly.
+   */
+  private assertRawRemoteAllowed(method: string): void {
+    const mode = this.config.schema.policy?.queryAllowlist;
+    if ((mode === 'warn' || mode === 'enforce') && !this.config.allowRawRemote) {
+      throw new Error(
+        `sp00ky: ${method} is disabled because sync.queryAllowlist is on for this schema; pass allowRawRemote: true in the client config to opt in`
+      );
+    }
+  }
+
   async queryRaw(sql: string, params: Record<string, any>, ttl: QueryTimeToLive): Promise<string> {
+    this.assertRawRemoteAllowed('queryRaw');
     const tableName = sql.split('FROM ')[1]?.split(' ')[0] ?? '';
     return this.runtime.run(registerLocal(this.env, { tableName, surql: sql, params, ttl }));
   }
@@ -436,10 +451,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   async useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T> {
+    this.assertRawRemoteAllowed('useRemote');
     return fn(this.services.remote.getClient());
   }
 
   async remoteQuery<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T> {
+    this.assertRawRemoteAllowed('remoteQuery');
     return this.services.remote.query<T>(sql, vars);
   }
 

package/src/query/register.saga.test.ts

@@ -4,7 +4,7 @@ import { runPure, sha256Hex } from '../testing/run-pure';
 import { buildEntry, buildState } from '../testing/build';
 import { defaultEnv } from './env';
 import { queryHashInput } from './hash';
-import { ensureRegistered, registerLocal, registerRemote } from './register.saga';
+import { ensureRegistered, isNotAllowlisted, registerLocal, registerRemote } from './register.saga';
 import * as R from '../state/reducers';
 import { emptyState } from '../state/client-state';
 import type { StatementResult } from '../kernel/effects';
@@ -212,6 +212,40 @@ describe('registerRemote', () => {
     expect(last.state.queries.get('a')!.lifecycle.remote).toBe('failed');
     expect(last.timers.size).toBe(0);
   });
+  it('not allowlisted: 403/Forbidden/not_allowlisted fails after ONE attempt with an error log, no retry timer', async () => {
+    for (const text of ['HTTP 403 Forbidden', 'There was an error processing a remote HTTP request: {"error":"not_allowlisted"}', 'status 403']) {
+      const out = await runPure(registerRemote(env, 'a'), {
+        state: buildState([entry]),
+        handlers: { 'remote.query': () => [{ status: 'ERR', error: text }] },
+      });
+      const e = out.state.queries.get('a')!;
+      expect(e.lifecycle).toMatchObject({ remote: 'failed', phase: 'cold', fetchDepth: 0 });
+      expect(e.registerAttempts).toBe(0);
+      expect(out.timers.size).toBe(0);
+      expect(out.emitted).toContainEqual(
+        expect.objectContaining({
+          type: 'log',
+          level: 'error',
+          message: 'query refused: not allowlisted',
+          data: expect.objectContaining({ hash: 'a', table: entry.def.tableName, surql: entry.def.surql, params: [] }),
+        })
+      );
+      expect(out.dispatched).toContainEqual(expect.objectContaining({ type: 'SyncOutcome', ok: false }));
+    }
+    const thrown = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': () => {
+          throw new Error('Forbidden');
+        },
+      },
+    });
+    expect(thrown.state.queries.get('a')!.lifecycle.remote).toBe('failed');
+    expect(thrown.timers.size).toBe(0);
+    expect(isNotAllowlisted(new Error('socket closed'))).toBe(false);
+    expect(isNotAllowlisted('HTTP 4030')).toBe(false);
+  });
+
   it('tolerates ERR meta/children statements: edges still apply, missing meta reads as no row', async () => {
     const out = await runPure(registerRemote(env, 'a'), {
       state: buildState([entry]),

package/src/query/register.saga.ts

@@ -128,6 +128,15 @@ export function* ensureRegistered(env: SagaEnv, opts: { requireAuth?: boolean; a
 
 const stmt = (results: StatementResult[], i: number): StatementResult | undefined => results[i];
 
+/**
+ * The SSP answers a registration whose shape is not on the query allowlist
+ * with HTTP 403 `{"error":"not_allowlisted"}`. It reaches the client as the
+ * `fn::query::register` statement error carrying SurrealDB's http error text
+ * (status reason and/or body), and no retry can change the answer.
+ */
+export const isNotAllowlisted = (error: unknown): boolean =>
+  /not_allowlisted|\b403\b|forbidden/i.test(String((error as { message?: unknown })?.message ?? error));
+
 /**
  * One remote registration: `fn::query::register` plus the edge/meta/children
  * read in ONE request, then membership application. Concurrent with every
@@ -174,6 +183,23 @@ export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): S
   } catch (error) {
     const current = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
     if (!current) return;
+    if (isNotAllowlisted(error)) {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-failed' }));
+      yield fx.emit({
+        type: 'log',
+        level: 'error',
+        message: 'query refused: not allowlisted',
+        data: {
+          hash,
+          table: entry.def.tableName,
+          surql: entry.def.surql,
+          params: Object.keys(entry.def.params),
+          hint: 'Add or regenerate the query allowlist: spky generate, then spky deploy (or restart spky dev).',
+        },
+      });
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+      return;
+    }
     const attempts = current.registerAttempts + 1;
     yield fx.state.update(R.bumpRegisterAttempts(hash));
     yield fx.emit({ type: 'log', level: 'warn', message: 'remote registration failed', data: { hash, attempts, error } });

package/src/types.ts

@@ -322,6 +322,15 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * one-shot but never sync live.
    */
   enableAnonymousLiveQueries?: boolean;
+  /**
+   * Opt in to the raw remote escape hatches (`useRemote`, `remoteQuery`,
+   * `queryRaw`) when the generated schema's `policy.queryAllowlist` is `warn`
+   * or `enforce`. With the allowlist on, the server only accepts query shapes
+   * that `spky generate` collected from the query builder, so a hand-written
+   * SurrealQL string cannot be allowlisted and these methods throw unless this
+   * flag is `true`. Defaults to `false`.
+   */
+  allowRawRemote?: boolean;
   /**
    * Surface sustained sync failures as a "degraded" health status that the app
    * can observe via `subscribeToSyncHealth` (or the client-solid