@selvajs/supabase-provider 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Selva FelixBrunold VektorNode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# @selvajs/supabase-provider
+
+Supabase (Auth + Postgres + Storage) implementation of the `@selvajs/platform` interfaces.
+
+Runs the Selva backend against **either** a managed Supabase project (production) or a local Supabase CLI stack in Docker (development). Same code — different `SUPABASE_URL` and keys.
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Environment variables](#environment-variables)
+- [Wiring into `selva.config.ts`](#wiring-into-selvaconfigts)
+- [Applying the schema](#applying-the-schema)
+- [Development — local Supabase stack](#development--local-supabase-stack)
+- [Production — hosted Supabase project](#production--hosted-supabase-project)
+- [Running the conformance tests](#running-the-conformance-tests)
+- [Architecture notes](#architecture-notes)
+
+---
+
+## Quick start
+
+1. Install the package in the workspace (already listed in `pnpm-workspace.yaml`).
+2. Provision Supabase — either local (`npx supabase start`) or hosted (supabase.com).
+3. Apply the migrations from `packages/providers/supabase/supabase/migrations/` (the local CLI does this automatically on `db reset`).
+4. Copy the three env vars into your selva app `.env` (see below).
+5. Edit [`selva.config.ts`](../../../selva.config.ts) at the repo root to swap the local provider for the Supabase provider.
+6. `pnpm dev` — the selva app now reads and writes from Supabase.
+
+---
+
+## Environment variables
+
+All env vars are documented in [`packages/selva/.env.example`](../../selva/.env.example) — copy that file to `.env` and edit it. The Supabase provider needs `SUPABASE_URL`, `SUPABASE_ANON_KEY`, and `SUPABASE_SERVICE_ROLE_KEY`; the optional bucket / private-URL / signup overrides are also listed there.
+
+`SELVA_HMAC_KEY` is not used for sessions by the Supabase provider — those are Supabase JWTs. It's still consulted as the fallback secret for share-link / invite token hashing if `SHARE_LINK_SECRET` / `INVITE_TOKEN_SECRET` are unset. `SELVA_AT_REST_KEY` is local-provider-only and is ignored. Both are harmless if left set.
+
+Rhino.Compute URL + API key are configured in `/admin/compute` and persisted in the `compute_config` table — unchanged by the provider choice.
+
+### Finding the keys
+
+**Local (`npx supabase status`):**
+
+```
+╭──────────────────────────────────────────────────╮
+│ 🔑 Authentication Keys                            │
+├─────────────┬────────────────────────────────────┤
+│ Publishable │ sb_publishable_...                 │  ← SUPABASE_ANON_KEY
+│ Secret      │ sb_secret_...                      │  ← SUPABASE_SERVICE_ROLE_KEY
+╰─────────────┴────────────────────────────────────╯
+```
+
+**Hosted:** Supabase Dashboard → **Project Settings** → **API**.
+
+> **The S3-compat keys under the "Storage (S3)" section are NOT what you want.** Those are for external S3 tooling (rclone, etc.), not for `@supabase/supabase-js`.
+
+---
+
+## Wiring into `selva.config.ts`
+
+The repo's [`selva.config.ts`](../../selva.config.ts) is the single DI point — it picks which provider backs every interface. Switch between providers by changing imports:
+
+```ts
+import { defineConfig } from '@selvajs/platform';
+import * as supa from '@selvajs/supabase-provider';
+
+export default defineConfig((env) => ({
+	tenancy: 'single' as const,
+	flags: {
+		ALLOW_CROSS_ORG_PUBLIC: false,
+		ALLOW_ORG_COMPUTE_OVERRIDE: false,
+		ALLOW_ORG_CREATION: false
+	},
+	auth: supa.SupabaseAuthProvider.fromEnv(env),
+	data: supa.SupabaseDataProvider.fromEnv(env),
+	storage: supa.SupabaseStorageProvider.fromEnv(env)
+}));
+```
+
+To switch back to the local provider, swap the import and the three provider lines. See the commented example in [`selva.config.ts`](../../selva.config.ts).
+
+---
+
+## Applying the schema
+
+The `supabase/migrations/` directory holds a single bootstrap file that installs the entire schema in one pass:
+
+| File               | What it installs                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0001_initial.sql` | Everything: `user_profiles` (+ auto-seed trigger), `orgs` / `org_members` / `projects` / `project_members` (+ RLS helpers), `definitions` / `definition_versions` (+ deletion-protection FKs and the atomic `increment_run_count` RPC), `invites` (+ `get_invite_by_token` RPC), `compute_servers` (+ per-org/instance defaults, spec §3 BYO compute), `share_links` (+ `try_increment_share_link_solve_count` RPC, spec §7), and the `selva-public` / `selva-private` storage policies. |
+
+Future schema changes go in numbered files (`0002_…`, `0003_…`).
+
+The `supabase/seed.sql` file creates the two storage buckets (`selva-public`, `selva-private`).
+
+**Local:** `npx supabase db reset` applies everything on a fresh DB.
+
+**Hosted:** link the CLI to your project, then push:
+
+```bash
+cd packages/providers/supabase
+
+# One-time link. Reads the project-ref from Supabase Dashboard → Project Settings → General.
+npx supabase link --project-ref <your-project-ref>
+
+# Review what will be applied.
+npx supabase db diff
+
+# Apply migrations + seed.
+npx supabase db push
+```
+
+Alternatively you can copy each `.sql` file into Supabase Dashboard → **SQL Editor** and run them in order. The CLI path is strongly preferred — it's idempotent and version-controlled.
+
+---
+
+## Development — local Supabase stack
+
+Prerequisite: **Docker Desktop running.** First run pulls ~1 GB of images.
+
+```bash
+cd packages/providers/supabase
+npx supabase start
+```
+
+This spins up Postgres (54322), GoTrue/Auth (54321), Storage, Studio (54323), and Mailpit (54324 — fake SMTP inbox for auth emails). Migrations and the bucket seed apply automatically.
+
+Copy the printed **Publishable** and **Secret** keys into your `.env` at the selva app or repo root:
+
+```bash
+# selva app .env
+SUPABASE_URL=http://127.0.0.1:54321
+SUPABASE_ANON_KEY=sb_publishable_...
+SUPABASE_SERVICE_ROLE_KEY=sb_secret_...
+```
+
+Rhino.Compute server URL + API key are registered in `/admin/compute` after first boot.
+
+Switch `selva.config.ts` to Supabase (snippet above), then:
+
+```bash
+pnpm dev
+```
+
+**Useful commands:**
+
+```bash
+npx supabase status         # show URL + keys again
+npx supabase db reset       # wipe DB + re-run migrations + seed
+npx supabase stop           # stop containers (keeps volumes)
+npx supabase stop --no-backup  # stop + wipe volumes
+```
+
+Studio is a full admin UI at `http://127.0.0.1:54323`. Use it to inspect tables, rows, and RLS policies while developing.
+
+---
+
+## Production — hosted Supabase project
+
+1. Create a project on [supabase.com](https://supabase.com). Choose a region close to your selva app deployment.
+2. Dashboard → **Project Settings** → **API**. Copy the **Project URL**, **Publishable** key, and **Secret** key.
+3. Apply migrations via the CLI:
+   ```bash
+   cd packages/providers/supabase
+   npx supabase link --project-ref <your-project-ref>
+   npx supabase db push
+   ```
+4. Create the two storage buckets by running `supabase/seed.sql` in the Dashboard → **SQL Editor** (the CLI's `db push` doesn't run the seed on a hosted project — it's dev-only).
+5. Set the env vars on your selva app host (Vercel, Fly.io, Docker, etc.):
+   ```
+   SUPABASE_URL=https://<project-ref>.supabase.co
+   SUPABASE_ANON_KEY=sb_publishable_...
+   SUPABASE_SERVICE_ROLE_KEY=sb_secret_...
+   ```
+   After deploying, register your Rhino.Compute server URL (+ optional API key) via `/admin/compute`.
+6. Deploy the selva app with `selva.config.ts` wired to `@selvajs/supabase-provider`.
+7. Bootstrap the first user:
+   - Open `/setup` once — creates the first admin with `instance_admin`.
+   - Or manually: Dashboard → **Authentication** → **Add user**, then in the SQL Editor: `UPDATE public.user_profiles SET platform_permissions = ARRAY['instance_admin']::text[] WHERE user_id = '<uuid>';`
+
+### Operational checklist
+
+- **Backups.** Supabase handles daily backups on paid plans; verify restore works before relying on it.
+- **Rotate keys** if the Secret key is ever logged or committed. Dashboard → **Project Settings** → **API** → **Reset service_role key**.
+- **Row-level security is on for every table.** Disabling it on any table silently breaks the tenant boundary.
+- **Email sender.** Dashboard → **Authentication** → **Email templates** — configure an SMTP provider before going live, otherwise password-reset emails route through Supabase's rate-limited dev sender.
+
+---
+
+## Running the conformance tests
+
+The package ships a full conformance suite that runs against a **live** Supabase stack. It proves the provider implements every interface the same way the local provider does.
+
+```bash
+cd packages/providers/supabase
+
+# 1. Make sure the stack is running.
+npx supabase start
+
+# 2. Create .env.test with the same three vars.
+# (This is separate from your app's .env — it's gitignored and used only by tests.)
+cat > .env.test <<EOF
+SUPABASE_URL=http://127.0.0.1:54321
+SUPABASE_ANON_KEY=<publishable key>
+SUPABASE_SERVICE_ROLE_KEY=<secret key>
+EOF
+
+# 3. Run.
+pnpm test
+```
+
+When `.env.test` is missing the suite skips with a single explanatory test.
+
+The suite wipes every table and every auth user between tests — **do not point it at a production project.**
+
+---
+
+## Architecture notes
+
+### Storage
+
+Two buckets:
+
+- **`selva-public`** (public) — covers, archives. `getPublicUrl` returns the direct CDN URL.
+- **`selva-private`** (private) — `.gh` / `.ghx` files. `getPublicUrl` returns `/api/files/{path}` which the selva app's route handler must proxy after an auth check.
+
+Images are transcoded to WebP (1200px cap, quality 85) via the shared `transcodeImageIfNeeded` helper from `@selvajs/platform/storage`. Same bytes out of both providers.
+
+### Auth
+
+`SupabaseAuthProvider.verifyLogin` wraps `supabase.auth.signInWithPassword`, returning the JWT directly as `sessionToken`. `verifyToken` calls `supabase.auth.getUser(token)` — GoTrue validates the signature for us. Platform permissions merge in from `user_profiles.platform_permissions` (auto-created by the signup trigger).
+
+MFA methods on `IPasswordAuth` are currently undefined — MFA is deferred. If a user enrolls a factor via the Supabase dashboard, `signInWithPassword` returns an AAL1 session and routes that gate on AAL2 would fail; no route does today.
+
+### Data + RLS
+
+Every store goes through `ClientBundle.forRequest(ctx)`:
+
+- `ctx.system` → service-role client (bypasses RLS)
+- `ctx.adapterContext.sessionToken` → anon client with `Authorization: Bearer <jwt>` (RLS enforces per-user visibility)
+- neither → service-role fallback (admin paths)
+
+Helper SQL functions (`is_instance_admin`, `is_org_member`, `visible_project`, `has_org_permission`) are `SECURITY DEFINER` so they evaluate without looping through RLS.
+
+### User profile
+
+`user_profiles` is 1:1 with `auth.users`. The `handle_new_auth_user` trigger inserts a profile row on every signup so the provider never has to fence creation. `starDefinition` / `unstarDefinition` / `recordRun` do read-modify-write — OK for the expected scale; a SECURITY DEFINER RPC would close the race if concurrent starring ever matters.
+
+### Atomic improvements over the local provider
+
+- **`incrementRunCount`** uses a SQL function (`UPDATE … SET run_count = run_count + 1`) — atomic. The local provider does read-modify-write and can lose bumps under concurrent solves.
+
+### Findings
+
+Every abstraction-pressure point hit during implementation is logged in [FINDINGS.md](./FINDINGS.md). Short version: six items, none requiring platform contract changes beyond the Phase 0 set.
+
+---
+
+## Status
+
+Every interface from `@selvajs/platform` is implemented and exercised by the shared conformance suites against a live local Supabase stack:
+
+- `SupabaseAuthProvider` (incl. MFA-ready `LoginResult`)
+- `SupabaseStorageProvider`
+- `SupabaseOrgStore`, `SupabaseProjectStore`, `SupabaseDefinitionStore` (atomic `incrementRunCount`), `SupabaseInviteStore`, `SupabaseShareLinkStore`, `SupabaseComputeServerStore`
+- `SupabaseUserProfileProvider`
+- `SupabasePlatformPermissionStore`
+- `SupabaseDataProvider` — composition of the data stores
+
+Run them with `pnpm test` (see [Running the conformance tests](#running-the-conformance-tests)).

package/dist/auth/SupabaseAuthProvider.d.ts

@@ -0,0 +1,81 @@
+import type { IAuthProvider, IEmailLinkAuth, IOAuthAuth, IPasswordAuth, AuthUser, UserManagementResult, ListOptions, Page } from '@selvajs/platform';
+/**
+ * Auth backed by Supabase Auth (GoTrue).
+ *
+ * Identity + session lifecycle are fully delegated:
+ *  - `verifyLogin` wraps `auth.signInWithPassword` — returns the access_token
+ *    straight from Supabase as the session token.
+ *  - `verifyToken` calls `auth.getUser(token)` against an anon client scoped
+ *    to that bearer; GoTrue validates the JWT for us.
+ *  - User management uses `auth.admin.*` with the service-role client.
+ *
+ * Identity-only — platform permissions live on `IPlatformPermissionStore`
+ * (`SupabasePlatformPermissionStore` reads `user_profiles.platform_permissions`)
+ * and profile state on `IUserProfileStore`.
+ */
+export interface SupabaseAuthProviderConfig {
+    supabaseUrl: string;
+    anonKey: string;
+    serviceRoleKey: string;
+    /**
+     * Whether self-service signup is allowed via `passwordAuth.registerUser`.
+     * Default false — production deployments start with invite-only.
+     */
+    enableSelfSignup?: boolean;
+    /**
+     * OAuth providers enabled in the Supabase dashboard (lowercased:
+     * "google", "github", …). Surfaced via `oauth.listProviders()` so the
+     * driving layer doesn't read provider-specific env vars itself. Defaults
+     * to an empty list.
+     */
+    oauthProviders?: readonly string[];
+    /**
+     * Allow `emailLink.sendMagicLink` to create new users on first request.
+     * Default true — matches Supabase's `signInWithOtp` default and gives
+     * fresh installs a working signup path. Set false for invite-only
+     * deployments; `sendMagicLink` for an unknown email returns
+     * `{ ok: false, reason: 'signup_disabled' }`.
+     */
+    allowEmailLinkSignup?: boolean;
+}
+export declare class SupabaseAuthProvider implements IAuthProvider {
+    readonly name = "Supabase Auth";
+    readonly passwordAuth: IPasswordAuth;
+    readonly oauth: IOAuthAuth;
+    readonly emailLink: IEmailLinkAuth;
+    private readonly admin;
+    private readonly anon;
+    private readonly anonKey;
+    private readonly supabaseUrl;
+    constructor(config: SupabaseAuthProviderConfig);
+    static fromEnv(env: Record<string, string | undefined>): SupabaseAuthProvider;
+    verifyToken(token: string): Promise<AuthUser | null>;
+    getUser(id: string): Promise<AuthUser | null>;
+    listUsers(opts?: ListOptions): Promise<Page<AuthUser> | null>;
+    createUser(email: string): Promise<AuthUser>;
+    deleteUser(id: string): Promise<UserManagementResult>;
+    disableUser(id: string): Promise<UserManagementResult>;
+    touchLastLogin(id: string): Promise<void>;
+    /**
+     * Sign in via GoTrue. Returns the access token string and the hydrated
+     * user. Called by `SupabasePasswordAuth.verifyLogin` — kept on the
+     * provider class so it has access to the hydrate helper without plumbing.
+     */
+    private signIn;
+    /**
+     * Map a GoTrue `User` to our identity-only `AuthUser`. Platform permissions
+     * live on `IPlatformPermissionStore` and profile fields (displayName,
+     * starred, recentRuns) on `IUserProfileStore` — neither is in AuthUser.
+     */
+    private hydrate;
+    /**
+     * Expose the anon URL + key so other code (e.g. the same process's
+     * storage provider or per-request client factories) can build user-scoped
+     * clients without requiring a second config read.
+     */
+    getAnonClientConfig(): {
+        supabaseUrl: string;
+        anonKey: string;
+    };
+}
+//# sourceMappingURL=SupabaseAuthProvider.d.ts.map

package/dist/auth/SupabaseAuthProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseAuthProvider.d.ts","sourceRoot":"","sources":["../../src/auth/SupabaseAuthProvider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,QAAQ,EAER,oBAAoB,EACpB,WAAW,EACX,IAAI,EACJ,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,0BAA0B;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,qBAAa,oBAAqB,YAAW,aAAa;IACzD,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,0BAA0B;IA4B9C,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,oBAAoB;IAuBvE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAWpD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAM7C,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAkB7D,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa5C,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcrD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAoBtD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB/C;;;;OAIG;YACW,MAAM;IAUpB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAWf;;;;OAIG;IACH,mBAAmB,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAG/D"}