@selvajs/supabase-provider 0.14.3 → 0.14.4-beta.0

package/src/data/SupabaseShareLinkStore.ts

@@ -6,10 +6,15 @@ import type {
 	ListOptions,
 	Page
 } from '@selvajs/platform';
-import { ProviderError, actorFrom, NoopEventSink } from '@selvajs/platform';
+import { actorFrom, NoopEventSink } from '@selvajs/platform';
 import type { ClientBundle } from './client.js';
+import { mapPostgrestError } from './errors.js';
 import { nextCursorFromRange, toRange } from './pagination.js';
 
+/** Explicit column list for `share_links` — every field `rowToLink` consumes. */
+const SHARE_LINK_COLUMNS =
+	'id, definition_guid, channel, token_hash, name, created_by, created_at, expires_at, revoked_at, allow_solve, max_solves, solve_count';
+
 /**
  * Spec §7 — share-link store backed by Postgres.
  *
@@ -37,7 +42,7 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 			.forRequest(ctx)
 			.from('share_links')
 			.insert(linkToRow(link));
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		await this.events.emit({
 			type: 'share_link.minted',
 			linkId: link.id,
@@ -55,12 +60,12 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 		const { data, error, count } = await this.clients
 			.forRequest(ctx)
 			.from('share_links')
-			.select('*', { count: 'exact' })
+			.select(SHARE_LINK_COLUMNS, { count: 'exact' })
 			.eq('definition_guid', definitionId)
 			.is('revoked_at', null)
 			.order('created_at', { ascending: false })
 			.range(range.from, range.to);
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		const items = (data ?? []).map(rowToLink);
 		return { items, nextCursor: nextCursorFromRange(range, items.length, count) };
 	}
@@ -69,10 +74,10 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 		const { data, error } = await this.clients
 			.forRequest(ctx)
 			.from('share_links')
-			.select('*')
+			.select(SHARE_LINK_COLUMNS)
 			.eq('id', id)
 			.maybeSingle();
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		return data ? rowToLink(data) : null;
 	}
 
@@ -82,12 +87,12 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 		// — exactly the wrong semantic for token-credentialed access.
 		const { data, error } = await this.clients.serviceClient
 			.from('share_links')
-			.select('*, definitions!inner(deleted_at)')
+			.select(`${SHARE_LINK_COLUMNS}, definitions!inner(deleted_at)`)
 			.eq('token_hash', tokenHash)
 			.is('revoked_at', null)
 			.is('definitions.deleted_at', null)
 			.maybeSingle();
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		return data ? rowToLink(data) : null;
 	}
 
@@ -101,7 +106,7 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 			.update({ revoked_at: new Date().toISOString() })
 			.eq('id', id)
 			.is('revoked_at', null);
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		await this.events.emit({ type: 'share_link.revoked', linkId: id, actorId: actorFrom(ctx) });
 	}
 
@@ -113,7 +118,7 @@ export class SupabaseShareLinkStore implements IShareLinkStore {
 			'try_increment_share_link_solve_count',
 			{ link_id: id }
 		);
-		if (error) throw mapError(error);
+		if (error) throw mapPostgrestError(error);
 		return typeof data === 'number' ? data : null;
 	}
 }
@@ -169,23 +174,3 @@ function linkToRow(l: ShareLink): Record<string, unknown> {
 		solve_count: l.solveCount
 	};
 }
-
-interface PostgrestError {
-	code?: string;
-	message?: string;
-}
-
-function mapError(e: unknown): Error {
-	const pg = e as PostgrestError;
-	if (pg?.code === '23505') return new ProviderError(pg.message ?? 'Duplicate record', 409);
-	if (pg?.code === '23503') return new ProviderError(pg.message ?? 'Foreign key violation', 409);
-	if (e instanceof Error) return e;
-	if (e && typeof e === 'object') {
-		const obj = e as { message?: string; details?: string; hint?: string; code?: string };
-		const msg = obj.message ?? obj.details ?? obj.hint ?? 'Unknown Postgres error';
-		const err = new Error(obj.code ? `[${obj.code}] ${msg}` : msg);
-		Object.assign(err, obj);
-		return err;
-	}
-	return new Error(String(e));
-}

package/src/data/__tests__/compute-server-conformance.test.ts

@@ -1,10 +1,16 @@
 import { describe, beforeEach, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
 import { runComputeServerStoreConformance } from '@selvajs/platform/testing';
 import { SupabaseComputeServerStore } from '../SupabaseComputeServerStore.js';
 import { readEnv, resetAllData, seedUser } from './test-helpers.js';
 
 const envCtx = readEnv();
 
+// A throwaway at-rest key so the store encrypts apiKeys during the suite. The
+// round-trip (encrypt on write, decrypt on read) must be transparent to the
+// conformance assertions, which compare plaintext apiKeys.
+const TEST_SECRET_KEY = randomBytes(32);
+
 if (!envCtx) {
 	describe.skip('SupabaseComputeServerStore (skipped: no live stack)', () => {
 		it('populate packages/providers/supabase/.env.test with Supabase creds to run these tests', () => {});
@@ -17,7 +23,7 @@ if (!envCtx) {
 
 		runComputeServerStoreConformance({
 			name: 'SupabaseComputeServerStore',
-			createStore: () => new SupabaseComputeServerStore(envCtx.bundle),
+			createStore: () => new SupabaseComputeServerStore(envCtx.bundle, TEST_SECRET_KEY),
 			seedOrg: async (orgId) => {
 				// `compute_servers.owner_org_id` and `compute_server_org_defaults.org_id`
 				// FK to `orgs(id)`; the suite invents an `orgId` per org-scoped test,

package/src/data/__tests__/compute-server-encryption.test.ts

@@ -0,0 +1,173 @@
+/**
+ * CI-runnable (no live stack) unit tests for at-rest encryption of
+ * `compute_servers.api_key`. Uses a minimal fake of the Supabase query builder
+ * that records `insert` payloads and serves canned `select` rows, so we can
+ * assert the exact bytes that would reach the DB without a real Postgres.
+ *
+ * The security property under test: a plaintext apiKey handed to the store is
+ * NEVER written verbatim — the DB only ever sees an `enc:v1:` envelope — and it
+ * round-trips back to plaintext on read.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { isEncryptedSecret, decryptSecret } from '@selvajs/platform/computeServer';
+import type { RequestContext } from '@selvajs/platform';
+import { SupabaseComputeServerStore } from '../SupabaseComputeServerStore.js';
+import type { ClientBundle } from '../client.js';
+
+const SYSTEM_CTX = { userId: '', system: true } as unknown as RequestContext;
+const KEY = randomBytes(32);
+
+/**
+ * Records every `insert` payload and returns canned rows for each table's
+ * `select`. Only the fragments the store actually chains are implemented; the
+ * builder is thenable so `await client.from(...).select(...)` resolves.
+ */
+function fakeBundle(selectRows: Record<string, unknown[]> = {}) {
+	const inserted: Record<string, unknown[]> = {};
+
+	function builder(table: string) {
+		const result = { data: selectRows[table] ?? [], error: null };
+		const chain: Record<string, unknown> = {
+			select: () => ({
+				...chain,
+				eq: () => ({ ...chain, maybeSingle: async () => ({ data: null, error: null }) }),
+				then: (resolve: (v: unknown) => unknown) => resolve(result)
+			}),
+			insert: (rows: unknown) => {
+				inserted[table] = (inserted[table] ?? []).concat(rows as unknown[]);
+				return { error: null };
+			},
+			delete: () => ({ eq: () => ({ eq: () => ({ error: null }), error: null }) }),
+			update: () => ({ eq: () => ({ error: null }) }),
+			upsert: () => ({ error: null })
+		};
+		return chain;
+	}
+
+	const client = { from: (t: string) => builder(t) };
+	const bundle = {
+		serviceClient: client,
+		forRequest: () => client
+	} as unknown as ClientBundle;
+	return { bundle, inserted };
+}
+
+describe('SupabaseComputeServerStore — apiKey encryption at rest', () => {
+	beforeEach(() => vi.restoreAllMocks());
+
+	it('encrypts apiKey before insert — DB never sees plaintext', async () => {
+		const { bundle, inserted } = fakeBundle();
+		const store = new SupabaseComputeServerStore(bundle, KEY);
+
+		await store.savePlatformServers(
+			SYSTEM_CTX,
+			[
+				{
+					id: 's1',
+					label: 'prod',
+					serverUrl: 'https://compute.example.com',
+					apiKey: 'super-secret-key',
+					scope: 'platform',
+					sharedWith: 'all'
+				}
+			],
+			's1'
+		);
+
+		const rows = inserted['compute_servers'] as Array<{ api_key: string }>;
+		expect(rows).toHaveLength(1);
+		expect(rows[0].api_key).not.toBe('super-secret-key');
+		expect(isEncryptedSecret(rows[0].api_key)).toBe(true);
+		// And it's genuinely our plaintext under the envelope.
+		expect(decryptSecret(rows[0].api_key, KEY)).toBe('super-secret-key');
+	});
+
+	it('decrypts apiKey on read — callers see plaintext', async () => {
+		// Seed the "DB" with an already-encrypted row.
+		const { encryptSecret } = await import('@selvajs/platform/computeServer');
+		const envelope = encryptSecret('round-trip-key', KEY);
+		const { bundle } = fakeBundle({
+			compute_servers: [
+				{
+					id: 's1',
+					scope: 'platform',
+					owner_org_id: null,
+					shared_with_all: true,
+					label: 'prod',
+					server_url: 'https://compute.example.com',
+					api_key: envelope,
+					timeout_ms: null,
+					retry_count: null
+				}
+			]
+		});
+		const store = new SupabaseComputeServerStore(bundle, KEY);
+
+		const config = await store.getConfig(SYSTEM_CTX);
+		expect(config.servers).toHaveLength(1);
+		expect(config.servers[0].apiKey).toBe('round-trip-key');
+	});
+
+	it('throws rather than persist plaintext when no key is configured', async () => {
+		const { bundle } = fakeBundle();
+		const store = new SupabaseComputeServerStore(bundle); // no key
+
+		await expect(
+			store.savePlatformServers(
+				SYSTEM_CTX,
+				[
+					{
+						id: 's1',
+						label: 'prod',
+						serverUrl: 'https://compute.example.com',
+						apiKey: 'secret',
+						scope: 'platform',
+						sharedWith: 'all'
+					}
+				],
+				's1'
+			)
+		).rejects.toThrow(/SELVA_AT_REST_KEY/);
+	});
+
+	it('verifySecrets flags a plaintext row', async () => {
+		const { bundle } = fakeBundle({
+			compute_servers: [{ id: 's1', label: 'legacy', api_key: 'raw-plaintext' }]
+		});
+		const store = new SupabaseComputeServerStore(bundle, KEY);
+
+		const report = await store.verifySecrets();
+		expect(report.ok).toBe(false);
+		expect(report.plaintextFound).toBe(true);
+		expect(report.failures).toEqual([
+			{ serverId: 's1', serverLabel: 'legacy', reason: 'plaintext_on_disk' }
+		]);
+	});
+
+	it('verifySecrets reports key_mismatch when the at-rest key rotated', async () => {
+		const { encryptSecret } = await import('@selvajs/platform/computeServer');
+		const envelope = encryptSecret('secret', randomBytes(32)); // different key
+		const { bundle } = fakeBundle({
+			compute_servers: [{ id: 's1', label: 'prod', api_key: envelope }]
+		});
+		const store = new SupabaseComputeServerStore(bundle, KEY);
+
+		const report = await store.verifySecrets();
+		expect(report.ok).toBe(false);
+		expect(report.plaintextFound).toBe(false);
+		expect(report.failures[0]).toMatchObject({ serverId: 's1', reason: 'key_mismatch' });
+	});
+
+	it('verifySecrets returns ok when every apiKey decrypts', async () => {
+		const { encryptSecret } = await import('@selvajs/platform/computeServer');
+		const { bundle } = fakeBundle({
+			compute_servers: [{ id: 's1', label: 'prod', api_key: encryptSecret('k', KEY) }]
+		});
+		const store = new SupabaseComputeServerStore(bundle, KEY);
+
+		const report = await store.verifySecrets();
+		expect(report).toEqual({ ok: true, failures: [], plaintextFound: false });
+	});
+});

package/src/data/__tests__/share-link-concurrency.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Audit Q4/Q5 — the concurrent-solve guarantee for share-link caps.
+ *
+ * `tryIncrementSolveCount` is the load-bearing race-sensitive method: the
+ * `/api/compute` endpoint calls it BEFORE solving and turns a `null` return
+ * (cap hit) into HTTP 429. Under concurrent solves against one capped link, the
+ * cap must hold exactly — no overshoot, no lost update handing two solves the
+ * same slot. Supabase provides this via the SECURITY DEFINER
+ * `try_increment_share_link_solve_count` RPC, which does the check-and-increment
+ * in a single statement.
+ *
+ * This lives in the Supabase suite (not the shared conformance suite or the app
+ * route tests) because it is the ONLY backend that actually provides the
+ * guarantee: the local provider's whole-file read-modify-write is a documented
+ * dev-scale tradeoff and is not concurrency-safe. Skipped without a live stack,
+ * matching the other conformance tests here.
+ *
+ * Complements the sequential cap/count tests at
+ * `packages/selva/src/routes/api/compute/__tests__/solve-cap-and-count.test.ts`.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { RequestContext, ShareLink } from '@selvajs/platform';
+import { SupabaseShareLinkStore } from '../SupabaseShareLinkStore.js';
+import { readEnv, resetAllData, seedUser } from './test-helpers.js';
+
+const envCtx = readEnv();
+
+if (!envCtx) {
+	describe.skip('SupabaseShareLinkStore concurrency (skipped: no live stack)', () => {
+		it('populate packages/providers/supabase/.env.test with Supabase creds to run these tests', () => {});
+	});
+} else {
+	const ctx: RequestContext = { userId: '', system: true } as RequestContext;
+
+	/** Seed org → project → definition → share link, all via service-role. */
+	async function seedCappedLink(maxSolves: number): Promise<{ linkId: string }> {
+		const { userId: ownerId } = await seedUser(envCtx!, '');
+		const admin = envCtx!.adminClient;
+		const orgId = crypto.randomUUID();
+		const projectId = crypto.randomUUID();
+		const definitionId = crypto.randomUUID();
+		const linkId = crypto.randomUUID();
+		const now = new Date().toISOString();
+
+		const { error: orgErr } = await admin.from('orgs').insert({
+			id: orgId,
+			name: 'Concurrency Org',
+			slug: `conc-${orgId.slice(0, 8)}`,
+			owner_id: ownerId,
+			created_at: now,
+			updated_at: now
+		});
+		if (orgErr) throw orgErr;
+		const { error: projErr } = await admin.from('projects').insert({
+			id: projectId,
+			org_id: orgId,
+			name: 'Project',
+			slug: `proj-${projectId.slice(0, 8)}`,
+			visibility: 'public',
+			owner_id: ownerId,
+			created_at: now,
+			updated_at: now
+		});
+		if (projErr) throw projErr;
+		const { error: defErr } = await admin.from('definitions').insert({
+			guid: definitionId,
+			project_id: projectId,
+			owner_id: ownerId,
+			display_name: 'Def',
+			status: 'published',
+			created_at: now,
+			updated_at: now
+		});
+		if (defErr) throw defErr;
+
+		const link: ShareLink = {
+			id: linkId,
+			definitionId,
+			channel: 'live',
+			tokenHash: crypto.randomUUID().replace(/-/g, ''),
+			createdBy: ownerId,
+			createdAt: now,
+			expiresAt: null,
+			revokedAt: null,
+			allowSolve: true,
+			maxSolves,
+			solveCount: 0
+		};
+		const store = new SupabaseShareLinkStore(envCtx!.bundle);
+		await store.create(ctx, link);
+		return { linkId };
+	}
+
+	describe('SupabaseShareLinkStore — concurrent solve-cap enforcement', () => {
+		beforeEach(async () => {
+			await resetAllData(envCtx!);
+		});
+
+		it('N concurrent solves against a cap-K link admit exactly K, refuse the rest', async () => {
+			const CAP = 5;
+			const ATTEMPTS = 25;
+			const { linkId } = await seedCappedLink(CAP);
+			const store = new SupabaseShareLinkStore(envCtx!.bundle);
+
+			const outcomes = await Promise.all(
+				Array.from({ length: ATTEMPTS }, () => store.tryIncrementSolveCount(ctx, linkId))
+			);
+
+			const admitted = outcomes.filter((n): n is number => n !== null);
+			const refused = outcomes.filter((n) => n === null);
+			// Exactly CAP admitted — the atomic RPC never lets a concurrent burst
+			// overshoot the cap.
+			expect(admitted).toHaveLength(CAP);
+			expect(refused).toHaveLength(ATTEMPTS - CAP);
+			// Each admitted solve got a distinct slot 1..CAP — no lost update.
+			expect([...admitted].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+
+			// The persisted count settles at exactly the cap.
+			const finalLink = await store.getById(ctx, linkId);
+			expect(finalLink?.solveCount).toBe(CAP);
+		});
+	});
+}

package/src/data/client.ts

@@ -10,6 +10,27 @@ import type { RequestContext } from '@selvajs/platform';
  */
 export type SelvaSchemaClient = SupabaseClient<any, 'public', 'selva'>;
 
+/** Default schema every engine store targets. */
+export const DEFAULT_SCHEMA = 'selva' as const;
+
+/**
+ * A client pinned to a caller-chosen schema. When the schema is `'selva'` this
+ * is the narrow `SelvaSchemaClient`; for an app-owned schema (e.g. `'public'`)
+ * the schema generic is opaque — the store surface (`.from` / `.rpc`) is the
+ * same either way.
+ */
+export type SchemaClient = SupabaseClient<any, string, any>;
+
+export interface ForRequestOptions {
+	/**
+	 * Postgres schema this client targets. Defaults to `'selva'` (the engine's
+	 * tables). Pass `'public'` (or another app schema) to build stores on the
+	 * consuming app's own tables while keeping the same fail-closed RLS
+	 * dispatch as the engine stores.
+	 */
+	schema?: string;
+}
+
 /**
  * Build a Supabase client for a given `RequestContext`.
  *
@@ -35,15 +56,20 @@ export type SelvaSchemaClient = SupabaseClient<any, 'public', 'selva'>;
  * fetch connection without leaking auth across requests.
  */
 export interface ClientBundle {
-	/** Long-lived service-role client. Bypasses RLS. */
+	/** Long-lived service-role client, pinned to the `'selva'` schema. Bypasses RLS. */
 	serviceClient: SelvaSchemaClient;
 	/**
-	 * Produce (or reuse) a client scoped to this request's identity.
+	 * Produce (or reuse) a client scoped to this request's identity, targeting
+	 * `opts.schema` (default `'selva'`).
 	 *  - `ctx.system === true` → service-role (RLS bypassed).
 	 *  - `ctx.adapterContext.sessionToken` set → user-scoped (RLS active).
 	 *  - neither → anon client (RLS active, no `auth.uid()`).
+	 *
+	 * The schema pin and the RLS dispatch travel together: an app building
+	 * stores on its own `'public'` tables gets the same fail-closed behavior as
+	 * engine stores, just aimed at a different schema.
 	 */
-	forRequest(ctx: RequestContext): SelvaSchemaClient;
+	forRequest(ctx: RequestContext, opts?: ForRequestOptions): SchemaClient;
 }
 
 export interface BuildClientOptions {
@@ -53,44 +79,93 @@ export interface BuildClientOptions {
 }
 
 export function buildClientBundle(opts: BuildClientOptions): ClientBundle {
-	const serviceClient = createClient(opts.supabaseUrl, opts.serviceRoleKey, {
-		db: { schema: 'selva' },
-		auth: { persistSession: false, autoRefreshToken: false }
-	});
+	// Long-lived service-role + anon clients, one per schema. Both are stateless
+	// w.r.t. request identity, so a single instance is safe to share across all
+	// requests targeting the same schema.
+	const serviceBySchema = new Map<string, SchemaClient>();
+	const anonBySchema = new Map<string, SchemaClient>();
+
+	function serviceFor(schema: string): SchemaClient {
+		let client = serviceBySchema.get(schema);
+		if (!client) {
+			client = createClient(opts.supabaseUrl, opts.serviceRoleKey, {
+				db: { schema },
+				auth: { persistSession: false, autoRefreshToken: false }
+			});
+			serviceBySchema.set(schema, client);
+		}
+		return client;
+	}
+
+	function anonFor(schema: string): SchemaClient {
+		let client = anonBySchema.get(schema);
+		if (!client) {
+			client = createClient(opts.supabaseUrl, opts.anonKey, {
+				db: { schema },
+				auth: { persistSession: false, autoRefreshToken: false }
+			});
+			anonBySchema.set(schema, client);
+		}
+		return client;
+	}
 
-	// Long-lived anon client — the fail-closed default for ctxes that aren't
-	// explicitly system and don't carry a session token.
-	const anonClient = createClient(opts.supabaseUrl, opts.anonKey, {
-		db: { schema: 'selva' },
-		auth: { persistSession: false, autoRefreshToken: false }
-	});
+	// The `'selva'`-pinned service client is exposed directly on the bundle for
+	// engine code that reaches for RLS-bypassing reads without a request context.
+	const serviceClient = serviceFor(DEFAULT_SCHEMA) as SelvaSchemaClient;
 
-	const perRequestCache = new WeakMap<RequestContext, SelvaSchemaClient>();
+	// Per-request user-scoped clients, keyed first by context then by schema so
+	// a handler that touches both `'selva'` and an app schema reuses one client
+	// per (request, schema) without leaking auth across requests.
+	const perRequestCache = new WeakMap<RequestContext, Map<string, SchemaClient>>();
 
 	return {
 		serviceClient,
-		forRequest(ctx: RequestContext): SelvaSchemaClient {
-			if (ctx.system) return serviceClient;
+		forRequest(ctx: RequestContext, forOpts?: ForRequestOptions): SchemaClient {
+			const schema = forOpts?.schema ?? DEFAULT_SCHEMA;
+			if (ctx.system) return serviceFor(schema);
 
 			const token = extractSessionToken(ctx.adapterContext);
-			if (!token) return anonClient;
+			if (!token) return anonFor(schema);
 
-			const cached = perRequestCache.get(ctx);
+			let bySchema = perRequestCache.get(ctx);
+			if (!bySchema) {
+				bySchema = new Map();
+				perRequestCache.set(ctx, bySchema);
+			}
+			const cached = bySchema.get(schema);
 			if (cached) return cached;
 
 			const client = createClient(opts.supabaseUrl, opts.anonKey, {
-				db: { schema: 'selva' },
+				db: { schema },
 				auth: { persistSession: false, autoRefreshToken: false },
 				global: {
 					headers: { Authorization: `Bearer ${token}` }
 				}
 			});
-			perRequestCache.set(ctx, client);
+			bySchema.set(schema, client);
 			return client;
 		}
 	};
 }
 
+/**
+ * Build a `ClientBundle` straight from environment variables — the
+ * `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` triple,
+ * nothing else. Deliberately does NOT require `SELVA_AT_REST_KEY`: that key
+ * only matters for compute-server secret encryption, which a consuming app
+ * building its own `'public'` stores never touches. `SupabaseDataProvider.fromEnv`
+ * layers the at-rest-key requirement on top of this.
+ */
+export function clientBundleFromEnv(env: Record<string, string | undefined>): ClientBundle {
+	const supabaseUrl = env.SUPABASE_URL;
+	const anonKey = env.SUPABASE_ANON_KEY;
+	const serviceRoleKey = env.SUPABASE_SERVICE_ROLE_KEY;
+	if (!supabaseUrl) throw new Error('Missing required env var: SUPABASE_URL');
+	if (!anonKey) throw new Error('Missing required env var: SUPABASE_ANON_KEY');
+	if (!serviceRoleKey) throw new Error('Missing required env var: SUPABASE_SERVICE_ROLE_KEY');
+	return buildClientBundle({ supabaseUrl, anonKey, serviceRoleKey });
+}
+
 function extractSessionToken(adapterContext: unknown): string | undefined {
 	if (!adapterContext || typeof adapterContext !== 'object') return undefined;
 	const maybe = (adapterContext as { sessionToken?: unknown }).sessionToken;

package/src/data/errors.ts

@@ -0,0 +1,45 @@
+import { ProviderError } from '@selvajs/platform';
+
+/**
+ * Canonical PostgREST/Postgres error translation shared by every Supabase
+ * store. Replaces the six near-identical private `mapError` copies that had
+ * drifted into two variants (a "full" one preserving `details`/`hint`, and a
+ * slimmer message-only one) and none of which handled `PGRST116`.
+ *
+ * Mapping:
+ *  - `PGRST116` (single-row selector matched zero rows) → 404. PostgREST
+ *    raises this when `.single()` finds nothing; treating it as "not found"
+ *    is almost always what a store's caller wants.
+ *  - `23505` (unique violation) / `23503` (foreign-key violation) → 409.
+ *  - Anything else → a plain `Error` (500 downstream via `api-errors`), with
+ *    `details`/`hint`/`code` preserved on the error object for logs.
+ */
+
+/** The subset of a `PostgrestError` this mapper inspects. */
+interface PostgrestErrorShape {
+	code?: string;
+	message?: string;
+	details?: string;
+	hint?: string;
+}
+
+export function mapPostgrestError(e: unknown): Error {
+	const pg = e as PostgrestErrorShape;
+	switch (pg?.code) {
+		case 'PGRST116':
+			return new ProviderError(pg.message ?? 'Not found', 404);
+		case '23505':
+			return new ProviderError(pg.message ?? 'Duplicate record', 409);
+		case '23503':
+			return new ProviderError(pg.message ?? 'Foreign key violation', 409);
+	}
+	if (e instanceof Error) return e;
+	if (e && typeof e === 'object') {
+		const obj = e as PostgrestErrorShape;
+		const msg = obj.message ?? obj.details ?? obj.hint ?? 'Unknown Postgres error';
+		const err = new Error(obj.code ? `[${obj.code}] ${msg}` : msg);
+		Object.assign(err, obj);
+		return err;
+	}
+	return new Error(String(e));
+}

package/src/data/index.ts

@@ -8,5 +8,22 @@ export { SupabaseDataProvider } from './SupabaseDataProvider.js';
 export { SupabaseEventSink } from './SupabaseEventSink.js';
 export { SupabaseSolveMetricSink } from './SupabaseSolveMetricSink.js';
 export { SupabaseAuditQuery } from './SupabaseAuditQuery.js';
-export { buildClientBundle } from './client.js';
-export type { ClientBundle, BuildClientOptions } from './client.js';
+export { buildClientBundle, clientBundleFromEnv, DEFAULT_SCHEMA } from './client.js';
+export type {
+	ClientBundle,
+	BuildClientOptions,
+	ForRequestOptions,
+	SchemaClient,
+	SelvaSchemaClient
+} from './client.js';
+export { mapPostgrestError } from './errors.js';
+export { stampUpdate, stampSoftDelete } from './rowStamp.js';
+export { notDeleted } from './query.js';
+export {
+	toRange,
+	orderColumn,
+	nextCursorFromRange,
+	encodeCursor,
+	decodeCursor
+} from './pagination.js';
+export type { RangeSpec } from './pagination.js';