@selvajs/supabase-provider 0.11.0

package/src/data/pagination.ts

@@ -0,0 +1,68 @@
+/**
+ * Pagination helpers shared across Supabase stores.
+ *
+ * The platform contract specifies cursor pagination (`ListOptions.cursor`).
+ * Because Supabase/Postgres has no built-in opaque cursor format, we encode
+ * an offset as the cursor — simple, correct for stable sorts, and good
+ * enough for the volumes Selva deals with (admin/definition lists are
+ * bounded; nothing is infinite scroll over millions of rows).
+ *
+ * Keyset pagination would be faster at scale if it ever matters.
+ */
+
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '@selvajs/platform';
+import type { ListOptions } from '@selvajs/platform';
+
+export interface RangeSpec {
+	from: number;
+	to: number;
+	limit: number;
+}
+
+/** Decode an opaque cursor string. Returns 0 for missing/invalid cursors. */
+export function decodeCursor(cursor: string | undefined): number {
+	if (!cursor) return 0;
+	const n = parseInt(cursor, 10);
+	return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+export function encodeCursor(offset: number): string {
+	return String(offset);
+}
+
+/** Clamp limit + compute the PostgREST `range(from, to)` bounds. */
+export function toRange(opts: Pick<ListOptions, 'limit' | 'cursor'> | undefined): RangeSpec {
+	const limit = Math.min(Math.max(opts?.limit ?? DEFAULT_PAGE_LIMIT, 1), MAX_PAGE_LIMIT);
+	const from = decodeCursor(opts?.cursor);
+	return { from, to: from + limit - 1, limit };
+}
+
+/**
+ * Build the `nextCursor` from the count returned by PostgREST. Returns
+ * undefined when there is no next page.
+ */
+export function nextCursorFromRange(
+	range: RangeSpec,
+	returnedCount: number,
+	totalCount: number | null | undefined
+): string | undefined {
+	const consumed = range.from + returnedCount;
+	if (totalCount != null) {
+		return consumed < totalCount ? encodeCursor(consumed) : undefined;
+	}
+	// Without total, we can only infer "there might be more" if we got a full page.
+	return returnedCount >= range.limit ? encodeCursor(consumed) : undefined;
+}
+
+/** Map `ListOptions.orderBy` to a Postgres column name. */
+export function orderColumn(orderBy: ListOptions['orderBy'] | undefined): string {
+	switch (orderBy) {
+		case 'name':
+			return 'name';
+		case 'updatedAt':
+			return 'updated_at';
+		case 'createdAt':
+		default:
+			return 'created_at';
+	}
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { SupabaseStorageProvider } from './storage/SupabaseStorageProvider.js';
+export type { SupabaseStorageProviderConfig } from './storage/SupabaseStorageProvider.js';
+
+export {
+	SupabaseOrgStore,
+	SupabaseProjectStore,
+	SupabaseDefinitionStore,
+	SupabaseInviteStore,
+	SupabaseComputeServerStore,
+	SupabaseShareLinkStore,
+	SupabaseDataProvider,
+	SupabaseEventSink,
+	SupabaseAuditQuery,
+	buildClientBundle
+} from './data/index.js';
+export type { ClientBundle, BuildClientOptions } from './data/index.js';
+
+export { SupabaseUserProfileProvider } from './userProfile/index.js';
+
+export { SupabaseAuthProvider } from './auth/index.js';
+export type { SupabaseAuthProviderConfig } from './auth/index.js';
+
+export { SupabasePlatformPermissionStore } from './permissions/index.js';

package/src/permissions/SupabasePlatformPermissionStore.ts

@@ -0,0 +1,161 @@
+import type {
+	IPlatformPermissionStore,
+	PlatformPermission,
+	RequestContext,
+	UserManagementResult
+} from '@selvajs/platform';
+import { ProviderError, hasPermission, PlatformPermissionSchema } from '@selvajs/platform';
+import type { ClientBundle } from '../data/client.js';
+
+/**
+ * Supabase-backed platform-permission store. Reads and writes
+ * `public.user_profiles.platform_permissions` (auto-seeded by the
+ * `handle_new_auth_user` trigger). Service-role throughout — the store's own
+ * `assertAdmin` / `assertCanRead` enforce the auth boundary at the app level
+ * since RLS on `user_profiles` is coarse-grained for cross-user reads.
+ *
+ * Disabled-user state lives on `auth.users.user_metadata.disabled`, so the
+ * invariant counters cross-reference the auth backend to exclude disabled
+ * admins (matches `Permissions.md §10` "enabled instance_admin" semantics).
+ */
+export class SupabasePlatformPermissionStore implements IPlatformPermissionStore {
+	constructor(private readonly clients: ClientBundle) {}
+
+	private client() {
+		return this.clients.serviceClient;
+	}
+
+	async getFor(ctx: RequestContext, userId: string): Promise<PlatformPermission[]> {
+		assertCanRead(ctx, userId);
+		const { data, error } = await this.client()
+			.from('user_profiles')
+			.select('platform_permissions')
+			.eq('user_id', userId)
+			.maybeSingle();
+		if (error) throw mapError(error);
+		return filterValid(data?.platform_permissions ?? []);
+	}
+
+	async getForBatch(
+		ctx: RequestContext,
+		userIds: readonly string[]
+	): Promise<Map<string, PlatformPermission[]>> {
+		assertAdmin(ctx);
+		const out = new Map<string, PlatformPermission[]>();
+		if (userIds.length === 0) return out;
+		const { data, error } = await this.client()
+			.from('user_profiles')
+			.select('user_id, platform_permissions')
+			.in('user_id', [...userIds]);
+		if (error) throw mapError(error);
+		for (const row of data ?? []) {
+			out.set(row.user_id as string, filterValid((row.platform_permissions ?? []) as string[]));
+		}
+		return out;
+	}
+
+	async set(
+		ctx: RequestContext,
+		userId: string,
+		permissions: readonly PlatformPermission[]
+	): Promise<UserManagementResult> {
+		assertAdmin(ctx);
+		// 1. Confirm the target exists in the auth backend (the FK + trigger
+		//    means the user_profiles row should exist post-signup; if not,
+		//    treat as not_found rather than auto-creating).
+		const { data: existing, error: fetchError } = await this.client()
+			.from('user_profiles')
+			.select('platform_permissions')
+			.eq('user_id', userId)
+			.maybeSingle();
+		if (fetchError) throw mapError(fetchError);
+		if (!existing) return 'not_found';
+
+		// 2. §2 invariant: refuse if dropping the last instance_admin.
+		const wasAdmin = (existing.platform_permissions ?? []).includes('instance_admin');
+		const willBeAdmin = permissions.includes('instance_admin');
+		if (wasAdmin && !willBeAdmin) {
+			const others = await this.countOtherEnabledAdmins(userId);
+			if (others === 0) return 'last_admin';
+		}
+
+		// 3. Apply.
+		const { error } = await this.client()
+			.from('user_profiles')
+			.update({ platform_permissions: [...permissions] })
+			.eq('user_id', userId);
+		if (error) throw mapError(error);
+		return 'ok';
+	}
+
+	async hasInstanceAdmin(_ctx: RequestContext): Promise<boolean> {
+		const { data, error } = await this.client()
+			.from('user_profiles')
+			.select('user_id')
+			.contains('platform_permissions', ['instance_admin']);
+		if (error) throw mapError(error);
+		const candidates = (data ?? []).map((r) => r.user_id as string);
+		if (candidates.length === 0) return false;
+		// Check at least one isn't disabled.
+		for (const id of candidates) {
+			const { data: authData } = await this.clients.serviceClient.auth.admin.getUserById(id);
+			if (authData.user && authData.user.user_metadata?.disabled !== true) return true;
+		}
+		return false;
+	}
+
+	async countInstanceAdminsExcluding(_ctx: RequestContext, excludeUserId: string): Promise<number> {
+		return this.countOtherEnabledAdmins(excludeUserId);
+	}
+
+	private async countOtherEnabledAdmins(excludeUserId: string): Promise<number> {
+		const { data, error } = await this.client()
+			.from('user_profiles')
+			.select('user_id')
+			.contains('platform_permissions', ['instance_admin'])
+			.neq('user_id', excludeUserId);
+		if (error) throw mapError(error);
+		const candidates = (data ?? []).map((r) => r.user_id as string);
+		if (candidates.length === 0) return 0;
+		let count = 0;
+		for (const id of candidates) {
+			const { data: authData } = await this.clients.serviceClient.auth.admin.getUserById(id);
+			if (authData.user && authData.user.user_metadata?.disabled !== true) count += 1;
+		}
+		return count;
+	}
+}
+
+function filterValid(raw: readonly string[]): PlatformPermission[] {
+	return raw.filter((p): p is PlatformPermission => PlatformPermissionSchema.safeParse(p).success);
+}
+
+function assertCanRead(ctx: RequestContext, userId: string): void {
+	if (ctx.system) return;
+	if (ctx.userId === userId) return;
+	if (hasPermission(ctx, 'instance_admin')) return;
+	throw new ProviderError('Forbidden: cannot read another user’s permissions', 403);
+}
+
+function assertAdmin(ctx: RequestContext): void {
+	if (ctx.system) return;
+	if (hasPermission(ctx, 'instance_admin')) return;
+	throw new ProviderError('Forbidden: instance admin required', 403);
+}
+
+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; code?: string };
+		return new Error(obj.code ? `[${obj.code}] ${obj.message ?? ''}` : (obj.message ?? String(e)));
+	}
+	return new Error(String(e));
+}

package/src/permissions/__tests__/conformance.test.ts

@@ -0,0 +1,28 @@
+import { describe, beforeEach, it } from 'vitest';
+import { runPlatformPermissionStoreConformance } from '@selvajs/platform/testing';
+import { SupabasePlatformPermissionStore } from '../SupabasePlatformPermissionStore.js';
+import { readEnv, resetAllData, seedPlainUser } from '../../data/__tests__/test-helpers.js';
+
+const envCtx = readEnv();
+
+if (!envCtx) {
+	describe.skip('SupabasePlatformPermissionStore (skipped: no live stack)', () => {
+		it('populate packages/providers/supabase/.env.test with Supabase creds to run these tests', () => {});
+	});
+} else {
+	describe('SupabasePlatformPermissionStore', () => {
+		beforeEach(async () => {
+			await resetAllData(envCtx);
+		});
+
+		runPlatformPermissionStoreConformance({
+			name: 'SupabasePlatformPermissionStore',
+			createStore: async () => {
+				return {
+					store: new SupabasePlatformPermissionStore(envCtx.bundle),
+					seedUser: async () => (await seedPlainUser(envCtx, '')).userId
+				};
+			}
+		});
+	});
+}

package/src/permissions/index.ts

@@ -0,0 +1 @@
+export { SupabasePlatformPermissionStore } from './SupabasePlatformPermissionStore.js';

package/src/storage/SupabaseStorageProvider.ts

@@ -0,0 +1,177 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { createClient } from '@supabase/supabase-js';
+import { transcodeImageIfNeeded } from '@selvajs/platform/storage';
+import type { IStorageProvider } from '@selvajs/platform/storage';
+
+/**
+ * Storage backend for Selva on Supabase Storage.
+ *
+ * Uses two buckets:
+ *   - {publicBucket} (public): cover images, archive thumbnails, anything
+ *     CDN-safe. `getPublicUrl` returns the direct CDN URL.
+ *   - {privateBucket} (private): .gh / .ghx source files. `getPublicUrl`
+ *     returns the authenticated proxy URL (`${privateUrlPrefix}/{path}`) —
+ *     the consuming app must have a route at that prefix that authenticates
+ *     the request and streams the bytes via `get()`.
+ *
+ * Path routing: any path whose basename matches `definition.{ext}` is
+ * considered private. Covers (`cover.webp`) and archives (`archive/{ref}`)
+ * stay public. `definitionPaths` from @selvajs/platform produces exactly these
+ * names, so the routing is implicit — no caller has to think about buckets.
+ */
+export interface SupabaseStorageProviderConfig {
+	/** Supabase project URL (e.g. http://127.0.0.1:54321 for local stack). */
+	supabaseUrl: string;
+	/**
+	 * Service-role key. Required because the provider runs server-side and
+	 * must bypass RLS for server-internal actions (admin uploads, janitor
+	 * cleanup). The provider is never used directly from the browser.
+	 */
+	serviceRoleKey: string;
+	/** Bucket for CDN-readable objects. Default: "selva-public". */
+	publicBucket?: string;
+	/** Bucket for authenticated-only objects. Default: "selva-private". */
+	privateBucket?: string;
+	/**
+	 * URL prefix the app exposes for authenticated file downloads. Used by
+	 * `getPublicUrl` for private-bucket paths. Default: "/api/files".
+	 * The matching SvelteKit route is expected to call `get()` and stream
+	 * bytes back after an auth check.
+	 */
+	privateUrlPrefix?: string;
+}
+
+export class SupabaseStorageProvider implements IStorageProvider {
+	private readonly client: SupabaseClient;
+	private readonly publicBucket: string;
+	private readonly privateBucket: string;
+	private readonly publicBaseUrl: string;
+	private readonly privateUrlPrefix: string;
+
+	static fromEnv(env: Record<string, string | undefined>): SupabaseStorageProvider {
+		const supabaseUrl = env.SUPABASE_URL;
+		const serviceRoleKey = env.SUPABASE_SERVICE_ROLE_KEY;
+		if (!supabaseUrl) throw new Error('Missing required env var: SUPABASE_URL');
+		if (!serviceRoleKey) throw new Error('Missing required env var: SUPABASE_SERVICE_ROLE_KEY');
+		return new SupabaseStorageProvider({
+			supabaseUrl,
+			serviceRoleKey,
+			publicBucket: env.SUPABASE_PUBLIC_BUCKET,
+			privateBucket: env.SUPABASE_PRIVATE_BUCKET,
+			privateUrlPrefix: env.SUPABASE_PRIVATE_URL_PREFIX
+		});
+	}
+
+	constructor(config: SupabaseStorageProviderConfig) {
+		this.client = createClient(config.supabaseUrl, config.serviceRoleKey, {
+			auth: { persistSession: false, autoRefreshToken: false }
+		});
+		this.publicBucket = config.publicBucket ?? 'selva-public';
+		this.privateBucket = config.privateBucket ?? 'selva-private';
+		// Direct CDN URL format: {supabaseUrl}/storage/v1/object/public/{bucket}/{path}
+		this.publicBaseUrl = `${config.supabaseUrl.replace(/\/$/, '')}/storage/v1/object/public/${this.publicBucket}`;
+		this.privateUrlPrefix = (config.privateUrlPrefix ?? '/api/files').replace(/\/$/, '');
+	}
+
+	/**
+	 * Route a storage path to a bucket. Any `.gh`/`.ghx` source file is
+	 * private — confidentiality is determined by extension, not location, so
+	 * a path-scheme rename (e.g. `definition.gh` → `versions/v1.gh`) can't
+	 * silently move source files into the public bucket. Everything else
+	 * (covers, archives, thumbnails) is public.
+	 */
+	private bucketFor(storagePath: string): string {
+		return /\.(gh|ghx)$/i.test(storagePath) ? this.privateBucket : this.publicBucket;
+	}
+
+	async get(storagePath: string): Promise<Uint8Array | null> {
+		const bucket = this.bucketFor(storagePath);
+		const { data, error } = await this.client.storage.from(bucket).download(storagePath);
+		if (error) {
+			// storage-js surfaces 404 as an error with message "Object not found".
+			// Normalize any "not found" to null — we don't have a stable status code.
+			const msg = (error as { message?: string }).message ?? '';
+			if (/not found/i.test(msg) || /no such key/i.test(msg)) return null;
+			throw error;
+		}
+		const buffer = await data.arrayBuffer();
+		return new Uint8Array(buffer);
+	}
+
+	async put(storagePath: string, data: Uint8Array, contentType?: string): Promise<void> {
+		// Normalize images through the shared helper so this provider produces
+		// the same bytes / extensions as LocalStorageProvider for the same input.
+		const transcoded = await transcodeImageIfNeeded(data, contentType, storagePath);
+		const bucket = this.bucketFor(transcoded.path);
+		const { error } = await this.client.storage
+			.from(bucket)
+			.upload(transcoded.path, transcoded.data, {
+				contentType: transcoded.contentType,
+				upsert: true
+			});
+		if (error) throw error;
+	}
+
+	async delete(storagePath: string): Promise<void> {
+		const bucket = this.bucketFor(storagePath);
+		const { error } = await this.client.storage.from(bucket).remove([storagePath]);
+		// remove() does not error for missing paths — it just returns an empty array.
+		if (error) throw error;
+	}
+
+	async deletePrefix(prefix: string): Promise<void> {
+		// Hit both buckets: a definition's GUID prefix may have files in each.
+		// Scoped by the trailing slash in the prefix, so siblings aren't touched.
+		await Promise.all([
+			this.deletePrefixInBucket(this.publicBucket, prefix),
+			this.deletePrefixInBucket(this.privateBucket, prefix)
+		]);
+	}
+
+	private async deletePrefixInBucket(bucket: string, prefix: string): Promise<void> {
+		const normalized = prefix.replace(/\/+$/, '');
+		const keys = await this.listAllKeys(bucket, normalized);
+		if (keys.length === 0) return;
+		// `remove` accepts up to 1000 paths; batch just in case.
+		for (let i = 0; i < keys.length; i += 1000) {
+			const slice = keys.slice(i, i + 1000);
+			const { error } = await this.client.storage.from(bucket).remove(slice);
+			if (error) throw error;
+		}
+	}
+
+	/**
+	 * Recursively list every key under a prefix. `storage-js`'s `list` API
+	 * only returns the immediate children of a "folder", so we DFS.
+	 */
+	private async listAllKeys(bucket: string, prefix: string): Promise<string[]> {
+		const out: string[] = [];
+		const stack: string[] = [prefix];
+		while (stack.length > 0) {
+			const dir = stack.pop()!;
+			const { data, error } = await this.client.storage.from(bucket).list(dir, {
+				limit: 1000,
+				sortBy: { column: 'name', order: 'asc' }
+			});
+			if (error) throw error;
+			for (const entry of data ?? []) {
+				const full = dir ? `${dir}/${entry.name}` : entry.name;
+				// Folder entries have `id === null` in storage-js.
+				if (entry.id === null) {
+					stack.push(full);
+				} else {
+					out.push(full);
+				}
+			}
+		}
+		return out;
+	}
+
+	getPublicUrl(storagePath: string): string {
+		if (this.bucketFor(storagePath) === this.publicBucket) {
+			return `${this.publicBaseUrl}/${storagePath}`;
+		}
+		// Private files: the app's authenticated proxy route. See `privateUrlPrefix`.
+		return `${this.privateUrlPrefix}/${storagePath}`;
+	}
+}

package/src/storage/__tests__/conformance.test.ts

@@ -0,0 +1,152 @@
+import { describe, beforeEach, it, expect } from 'vitest';
+import { createClient } from '@supabase/supabase-js';
+import { runStorageProviderConformance } from '@selvajs/platform/testing';
+import { definitionPaths } from '@selvajs/platform';
+import { SupabaseStorageProvider } from '../SupabaseStorageProvider.js';
+
+const SUPABASE_URL = process.env.SUPABASE_URL;
+const SERVICE_ROLE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY;
+const PUBLIC_BUCKET = process.env.SUPABASE_PUBLIC_BUCKET ?? 'selva-public';
+const PRIVATE_BUCKET = process.env.SUPABASE_PRIVATE_BUCKET ?? 'selva-private';
+
+// The conformance suite hits a live Supabase stack. If creds aren't present
+// (e.g. in CI without Docker, or a clean clone pre-`supabase start`), skip
+// the suite with a single explanatory test so the run surfaces the reason.
+// `createClient` transitively loads `@supabase/realtime-js`, which on Node < 22
+// throws at construction without native WebSocket — treat that as "no stack"
+// rather than crashing the suite during collection.
+function tryBuildAdminClient(): ReturnType<typeof createClient> | null {
+	if (!SUPABASE_URL || !SERVICE_ROLE_KEY) return null;
+	try {
+		return createClient(SUPABASE_URL, SERVICE_ROLE_KEY, {
+			auth: { persistSession: false, autoRefreshToken: false }
+		});
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (msg.includes('WebSocket')) return null;
+		throw err;
+	}
+}
+const _adminClient = tryBuildAdminClient();
+
+if (_adminClient === null) {
+	describe.skip('SupabaseStorageProvider (skipped: no live stack)', () => {
+		it('populate packages/providers/supabase/.env.test with SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (from `npx supabase start`) to run these tests', () => {});
+	});
+} else {
+	// Re-bind in this branch so closures below see the non-null narrowed type.
+	const adminClient = _adminClient;
+
+	/**
+	 * Delete every object under a prefix in a bucket. The conformance suite
+	 * assumes fresh state per test; Supabase Storage is shared across runs,
+	 * so we reset both buckets before each test.
+	 */
+	async function emptyBucket(bucket: string): Promise<void> {
+		const keys: string[] = [];
+		const stack: string[] = [''];
+		while (stack.length > 0) {
+			const dir = stack.pop()!;
+			const { data, error } = await adminClient.storage.from(bucket).list(dir, {
+				limit: 1000,
+				sortBy: { column: 'name', order: 'asc' }
+			});
+			if (error) throw error;
+			for (const entry of data ?? []) {
+				const full = dir ? `${dir}/${entry.name}` : entry.name;
+				if (entry.id === null) stack.push(full);
+				else keys.push(full);
+			}
+		}
+		if (keys.length === 0) return;
+		for (let i = 0; i < keys.length; i += 1000) {
+			const { error } = await adminClient.storage.from(bucket).remove(keys.slice(i, i + 1000));
+			if (error) throw error;
+		}
+	}
+
+	describe('SupabaseStorageProvider', () => {
+		beforeEach(async () => {
+			await Promise.all([emptyBucket(PUBLIC_BUCKET), emptyBucket(PRIVATE_BUCKET)]);
+		});
+
+		runStorageProviderConformance({
+			name: 'SupabaseStorageProvider',
+			createStorage: () =>
+				new SupabaseStorageProvider({
+					supabaseUrl: SUPABASE_URL!,
+					serviceRoleKey: SERVICE_ROLE_KEY!,
+					publicBucket: PUBLIC_BUCKET,
+					privateBucket: PRIVATE_BUCKET
+				})
+		});
+
+		// ============================================================================
+		// Bucket routing — Supabase-specific (the conformance suite is provider-
+		// agnostic and can't see which bucket a file lands in). Without these tests
+		// a regex regression in `bucketFor` could silently move .gh source files
+		// into the public/CDN bucket.
+		// ============================================================================
+		describe('bucket routing', () => {
+			const storage = new SupabaseStorageProvider({
+				supabaseUrl: SUPABASE_URL!,
+				serviceRoleKey: SERVICE_ROLE_KEY!,
+				publicBucket: PUBLIC_BUCKET,
+				privateBucket: PRIVATE_BUCKET
+			});
+
+			async function existsInBucket(bucket: string, path: string): Promise<boolean> {
+				const { data, error } = await adminClient.storage.from(bucket).download(path);
+				if (error) return false;
+				return Boolean(data);
+			}
+
+			it('versioned .gh files land in the private bucket', async () => {
+				const guid = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+				const path = definitionPaths.version(guid, 1, 'gh');
+				await storage.put(path, new TextEncoder().encode('GH_BYTES'));
+				expect(await existsInBucket(PRIVATE_BUCKET, path)).toBe(true);
+				expect(await existsInBucket(PUBLIC_BUCKET, path)).toBe(false);
+			});
+
+			it('versioned .ghx files land in the private bucket', async () => {
+				const guid = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+				const path = definitionPaths.version(guid, 3, 'ghx');
+				await storage.put(path, new TextEncoder().encode('GHX_BYTES'));
+				expect(await existsInBucket(PRIVATE_BUCKET, path)).toBe(true);
+				expect(await existsInBucket(PUBLIC_BUCKET, path)).toBe(false);
+			});
+
+			it('cover images land in the public bucket', async () => {
+				const guid = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+				const path = definitionPaths.image(guid);
+				// Real 1×1 transparent PNG. The provider runs every image through
+				// transcodeImageIfNeeded → sharp, so a hand-crafted byte stub
+				// would fail the decode. Routing (the test's actual concern) is
+				// independent of which format the input arrives in.
+				const tinyPng = Uint8Array.from([
+					137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0, 0, 1, 0, 0, 0, 1, 8,
+					6, 0, 0, 0, 31, 21, 196, 137, 0, 0, 0, 9, 112, 72, 89, 115, 0, 0, 3, 232, 0, 0, 3, 232, 1,
+					181, 123, 82, 107, 0, 0, 0, 13, 73, 68, 65, 84, 120, 156, 99, 96, 96, 96, 96, 0, 0, 0, 5,
+					0, 1, 165, 246, 69, 64, 0, 0, 0, 0, 73, 69, 78, 68, 174, 66, 96, 130
+				]);
+				await storage.put(path, tinyPng, 'image/png');
+				expect(await existsInBucket(PUBLIC_BUCKET, path)).toBe(true);
+				expect(await existsInBucket(PRIVATE_BUCKET, path)).toBe(false);
+			});
+
+			it('getPublicUrl returns the proxy prefix for private files', () => {
+				const path = definitionPaths.version('guid-1', 1, 'gh');
+				const url = storage.getPublicUrl(path);
+				expect(url.startsWith('/api/files/')).toBe(true);
+				expect(url).not.toContain('/storage/v1/object/public/');
+			});
+
+			it('getPublicUrl returns the CDN URL for public files', () => {
+				const path = definitionPaths.image('guid-1');
+				const url = storage.getPublicUrl(path);
+				expect(url).toContain(`/storage/v1/object/public/${PUBLIC_BUCKET}/`);
+			});
+		});
+	});
+}

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export { SupabaseStorageProvider } from './SupabaseStorageProvider.js';
+export type { SupabaseStorageProviderConfig } from './SupabaseStorageProvider.js';