better-supabase 0.2.0 → 0.4.0

package/skills/better-supabase-auth/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: better-supabase-auth
+description: Read and check the caller in better-supabase apps, including sessions, typed claims, user profiles, OAuth clients and agents acting for a user, scopes, ended sessions and PermDock. Use when code reads auth, session or claims, when adding a custom access token hook, an OAuth or agent integration, sign-out, account deletion or role changes, or when the project has a permdock.config.ts.
+---
+
+# Auth with better-supabase
+
+Every adapter resolves the caller once. It verifies the access token locally
+against the project's JWKS, so a valid token costs no network call, and only
+the Next.js proxy (`bs.proxy`) refreshes sessions. Don't call
+`supabase.auth.getUser()` per request, and don't read cookies yourself.
+
+## Workflow: read the caller
+
+1. Take `auth` from the handler context (`ctx.auth`, `c.var.auth`,
+   `context.auth`), or a token-free `AuthSession` from `await bs.session()`
+   or `toSession(ctx.auth)`.
+2. Branch on `kind` with an exhaustive `switch` that ends in a `never` check:
+
+```ts
+switch (auth.kind) {
+  case "user": // auth.user.id, auth.claims
+    break;
+  case "service": // a secret key
+    break;
+  case "anon": // auth.reason: 'none' | 'expired' | 'signed_out' | 'refresh_failed'
+    break;
+  case "invalid": // auth.reason: 'token' | 'claims' | 'actor', answer 401
+    break;
+  default: {
+    const unreachable: never = auth;
+    return unreachable;
+  }
+}
+```
+
+3. Prefer the adapter's `allow` option (`['user']` by default) over checking
+   `kind` by hand; it answers 401 or 403 as Problem Details.
+
+Done when every `invalid` reason, `actor` included, ends in a 401 and no code
+path treats `invalid` as `anon`.
+
+## Workflow: type the claims
+
+1. Describe the claims your access token hook adds with any Standard Schema
+   and pass it to `betterSupabase.claims(schema)`. Use a loose object (`v.looseObject`,
+   `z.looseObject`) so claims the schema doesn't list stay on the session.
+   Make anything the hook doesn't always set optional or give it a default.
+2. For display data users edit themselves (name, avatar), use
+   `betterSupabase.userMetadata(schema)` and read `session.profile`.
+3. Read roles, memberships, the tenant and entitlements from the verified
+   claims only. Never from `user_metadata`, `session.profile`, a URL or a
+   request body.
+
+Done when `session.claims` is typed without casts, and a token whose claims
+fail the schema gets a 401 with code `CLAIMS_INVALID`.
+
+## Bearer callers: OAuth clients and agents
+
+A token from the Supabase OAuth server carries `client_id` and `scope`; a
+token exchanged for an agent carries an RFC 8693 `act` chain. The session
+names who acts for the user:
+
+| Token                                           | `session.actor`                      | `session.delegation` |
+| ----------------------------------------------- | ------------------------------------ | -------------------- |
+| The user's own                                  | not set                              | not set              |
+| `client_id: "c1"`, `scope: "openid crm.read"`   | `{ id: "c1", kind: "oauth-client" }` | `{ scopes: [...] }`  |
+| `act: { sub: "agent", act: { sub: "mcp-42" } }` | `{ id: "agent", chain, ... }`        | `{ scopes, chain }`  |
+
+- Limit what delegated tokens may do with the `scopes` guard option on
+  `bs.route`, `bs.action`, `bs.handler` and `bs.middleware`. A missing
+  scope answers 403 with an `insufficient_scope` challenge. The user's own
+  token is never limited by scopes.
+- In MCP servers, refuse calls in `authorize` by reading
+  `toSession(ctx.auth).delegation?.scopes` (the `better-supabase-api` skill).
+- RLS still decides the rows: `sub` is the user, so a client sees at most
+  what the user sees. Record `session.actor` (and `chain`) in audit data when
+  a change was made by a client or an agent.
+
+## Workflow: irreversible actions
+
+Tokens stay valid until they expire (an hour by default), even after the user
+signs out everywhere or an admin ends the session. Before an action you can't
+undo (deleting the account, transferring ownership, rotating keys), check
+that the session still exists:
+
+```ts
+import { err } from "better-supabase";
+import { checkSession } from "better-supabase/server";
+
+const ended = await checkSession(postgres.admin, auth);
+if (ended) return err(ended); // unauthorized, code SESSION_REVOKED
+```
+
+It needs a connection that can read `auth.sessions` (`createPostgres().admin`).
+Nothing calls it by default; keep it to the actions that need it.
+
+Done when the irreversible action returns `SESSION_REVOKED` for a signed-out
+session in a test.
+
+## When claims change
+
+A token carries the claims from when Auth issued it, so a revoked role or
+membership lasts until the next refresh. When that window matters:
+
+- Write policies that read the source of truth, for example
+  `organization_id in (select better_supabase.member_org_ids())`, instead of
+  the claim.
+- After a change the user made themselves (joining an organization), call
+  `supabase.auth.refreshSession()` in the browser.
+- In Next.js, drop the user's cached views with
+  `bs.invalidateSession(userId, { tags })`.
+
+## Next.js caching
+
+- Per-user data goes through `bs.cached()` inside your own
+  `'use cache: private'` function. It tags the entry `bs:session:<user id>`
+  and caps its lifetime at the token's.
+- `bs.cached({ tags, life: { stale } })` adds tags and caps the stale time
+  further, for example for a PermDock snapshot.
+- Keep layouts synchronous: pass the `bs.session()` promise to
+  `<SessionProvider>` and read it with `useSession()`.
+
+## PermDock
+
+When the project has a `permdock.config.ts`, PermDock owns the access token
+hook, roles, memberships and the tenant claim. Read
+[references/permdock.md](references/permdock.md) before touching the hook,
+claims, tenant or entitlements.
+
+## Don't
+
+- Don't refresh sessions outside the proxy, and don't verify tokens by
+  calling the Auth server.
+- Don't use `bs.admin()` or the service role for a user's request.
+- Don't downgrade an `invalid` caller to `anon`.
+- Don't build 401 or 403 JSON by hand; return the `DbError` or use `allow`
+  and `scopes`.
+
+## Docs
+
+https://bettersupabase.com/docs/auth.md,
+https://bettersupabase.com/docs/frameworks/next.md (bearer callers),
+https://bettersupabase.com/docs/auth/account-deletion.md,
+https://bettersupabase.com/docs/frameworks/next-cache-components.md and
+https://bettersupabase.com/docs/auth/permdock.md.

package/skills/better-supabase-auth/references/permdock.md

@@ -0,0 +1,55 @@
+# better-supabase next to PermDock
+
+PermDock handles authorization and better-supabase handles tokens and data.
+They share one access token hook and one claim contract, and neither imports
+the other.
+
+## Who owns what
+
+| Area                 | better-supabase                                             | PermDock                                                                               |
+| -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Access token hook    | none                                                        | `permdock supabase hook generate`, the only hook                                       |
+| Claims               | `features`, through `supabase.hook.claims`                  | `user_role`, `roles`, `memberships`, the tenant claim, `attrs`, `authz_ver`            |
+| SQL helpers          | the SQL kit (`better_supabase.*`)                           | `permdock rls generate`: `permdock_has`, `permitted_<scope>_ids`, `member_<scope>_ids` |
+| Storage and Realtime | `defineBucket`, `defineTopic` with a `permdock` policy mode | the helpers those policies call                                                        |
+| MCP                  | `createMcp` with `authorize` and `visible`                  | the permissions in each tool's `meta`                                                  |
+
+## Rules
+
+- Don't run `better-supabase sql add tenant` (it stops without `--force`),
+  don't call `membership_claims()` from a hook, and don't write `roles`,
+  `user_role`, `memberships` or the tenant claim yourself. Doctor reports
+  BS407 when a hook does.
+- `sql add entitlements` is fine: `features` is not a PermDock claim. Add
+  `claims: { features: 'better_supabase.feature_claims' }` to `supabase.hook`
+  in `permdock.config.ts`, run `permdock supabase hook generate`, and
+  `hasEntitlement(session, ...)` works.
+- Run `permdock supabase inspect --out` before `sql add entitlements`. With
+  `permdock.manifest.json` present, the module reads PermDock's
+  `member_<scope>_ids` helpers and doesn't add `tenant`. Set
+  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for a
+  scope other than `organization`.
+- Name the same tenant claim on both sides. A non-default `claims.tenant` in
+  `better-supabase.config.ts` must also be PermDock's `rls.tenantClaim` and
+  go to `subjectFromSupabase` or `subjectFromSupabaseSession` as `{ tenant }`.
+- Validate claims with PermDock's schema: `betterSupabase.claims(supabaseClaims().extend(appClaims))`.
+- The helpers live in PermDock's `rls.schema`, which must equal the `schema`
+  option of buckets and topics in `permdock` mode.
+- The `permdock` policy mode checks role and scope only. Use it only for
+  permissions whose `rowConditions` is `false` in `permissions.catalog.json`.
+  Leave permissions with row conditions to the policies
+  `permdock rls generate` writes; doctor reports BS214 and `permdock doctor`
+  PD037 otherwise.
+- `permdock` mode compares ids as text, so a path or topic segment must be
+  the id's lowercase form.
+- In MCP servers, narrow `tool.meta` with PermDock's `isPermission`, answer
+  `visible` with `mayUse` and `authorize` with `can`. `can` decides without
+  a row, so check row-conditioned permissions inside `run` or rely on RLS.
+- In Next.js, cache the permission snapshot with
+  `bs.cached({ tags: [snapshotTag(userId)], life: cacheLifeFor(snapshot) })`
+  and drop it with `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`
+  when a role or plan changes.
+- Doctor BS405 measures `memberships` plus `attrs` against PermDock's 1 KB
+  budget and the whole token against 2 KB; run `doctor --as <user id>`.
+
+Docs: https://bettersupabase.com/docs/auth/permdock.md

package/skills/better-supabase-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: better-supabase-testing
-description: Test Supabase RLS policies, APIs and SQL against the local stack with better-supabase/testing, typed seeds and pgTAP. Use when writing or fixing tests that touch the database, policies or auth.
+description: Test Supabase RLS policies, APIs and SQL against the local stack with better-supabase/testing, typed seeds and pgTAP. Use when writing or fixing tests that touch the database, policies, auth, OAuth or agent scopes, or Temporal time values.
 ---
 
 # Testing with better-supabase
@@ -11,7 +11,8 @@ supabase-js, and don't use the service role for anything a user does.
 ## Workflow: test a table or policy
 
 1. Start the stack (`supabase start`) and write `.env.local` with
-   `better-supabase env`.
+   `better-supabase env`. In a sandbox without Docker, start it with
+   `SUPABASE_EXPERIMENTAL_STACK=1` (the Supabase CLI's native stack).
 2. Add the rows the test needs to `supabase/seed.ts`, including one row
    owned by another tenant, then `supabase db reset`.
 3. Write the RLS test with `asUser` for each role that matters.
@@ -29,24 +30,30 @@ again once you restore it.
 - Typed fixtures live in `supabase/seed.ts`:
 
 ```ts
-import { defineSeed } from 'better-supabase/testing';
-import { sb } from '../src/lib/supabase.ts';
+import { defineSeed } from "better-supabase/testing";
+import { betterSupabase } from "../src/lib/supabase/index.ts";
 
-export const seed = defineSeed(sb, {
-  organizations: { acme: { id: ACME, name: 'Acme' } },
-  customers: { first: { id: FIRST, organizationId: ACME, name: 'First' } },
+export const seed = defineSeed(betterSupabase, {
+  organizations: { acme: { id: ACME, name: "Acme" } },
+  customers: { first: { id: FIRST, organizationId: ACME, name: "First" } },
 });
 ```
 
-  `better-supabase seed` renders them to SQL for `supabase db reset`, and
-  tests import the same rows (`seed.rows.customers.first.id`).
+`better-supabase seed` renders them to SQL for `supabase db reset`, and
+tests import the same rows (`seed.rows.customers.first.id`).
 
 ## RLS tests
 
 ```ts
-const alice = await asUser(sb, { sub: aliceId, tenant_id: ACME }, { postgres });
+const alice = await asUser(
+  betterSupabase,
+  { sub: aliceId, tenant_id: ACME },
+  { postgres },
+);
 expect(await alice.db.customers.count().orThrow()).toBe(1);
-expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({ ok: false });
+expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({
+  ok: false,
+});
 ```
 
 - Check both directions: the user sees their own rows and never sees another tenant's.
@@ -58,6 +65,56 @@ expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({ ok
 Send `authorization: Bearer ${alice.token}` (or a token from `signLocalJwt`).
 The adapter verifies it against the local JWKS; no test-only resolver is needed.
 
+For a route with `scopes`, sign a delegated token the way the Supabase OAuth
+server or an agent token exchange would, and assert both sides:
+
+```ts
+const client = await signLocalJwt({
+  sub: aliceId,
+  tenant_id: ACME,
+  client_id: "c1",
+  scope: "openid", // add "customers:read" to pass
+});
+const response = await app.request("/api/customers", {
+  headers: { authorization: `Bearer ${client}` },
+});
+expect(response.status).toBe(403);
+expect(response.headers.get("www-authenticate")).toContain(
+  'error="insufficient_scope"',
+);
+```
+
+The user's own token (no `client_id`, no `act`) must still pass, and a
+malformed `act` claim (`act: { sub: "" }`) must get a 401.
+
+## Time values
+
+With `codecs.timestamptz: 'instant'`, rows hold `Temporal` values. Import
+`temporal-polyfill/global` in the test setup on Node 24, and compare with
+`.equals()` or an equality tester, because `toEqual` treats any two instants
+as equal:
+
+```ts title="tests/setup.ts"
+import "temporal-polyfill/global";
+import { expect } from "vitest";
+
+expect.addEqualityTesters([
+  (a, b) =>
+    a instanceof Temporal.Instant && b instanceof Temporal.Instant
+      ? a.equals(b)
+      : undefined,
+]);
+```
+
+With the polyfill, `vi.useFakeTimers({ now })` drives `Temporal.Now` too.
+
+## Doctor in CI
+
+Run `pnpm better-supabase doctor` against the reset stack and fail the job on
+a nonzero exit. `--json` prints the report with each finding's code,
+`--format github` annotates the pull request, and
+`--format sarif --out doctor.sarif` feeds code scanning.
+
 ## pgTAP
 
 `better-supabase sql add pgtap` installs `tests.create_user`,

package/dist/casing-da0uRTqt.js

@@ -1,14 +0,0 @@
-//#region src/casing/index.ts
-/** `first_name` to `firstName`. Leaves already camel-cased names untouched. */
-function toCamel(name) {
-	return name.replace(/_+([a-z0-9])/g, (_, char) => char.toUpperCase());
-}
-/** `firstName` to `first_name`. */
-function toSnake(name) {
-	return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z])([A-Z][a-z])/g, "$1_$2").toLowerCase();
-}
-function applyCasing(name, casing) {
-	return casing === "camel" ? toCamel(name) : name;
-}
-//#endregion
-export { toCamel as n, toSnake as r, applyCasing as t };

package/dist/claims-CoTobNC-.js

@@ -1,25 +0,0 @@
-//#region src/core/claims.ts
-const DEFAULT_CLAIMS = {
-	tenant: "tenant_id",
-	scope: "tenant",
-	features: "features"
-};
-/** The configured claim names, with defaults for the ones codegen left out. */
-function claimsOf(meta) {
-	return {
-		...DEFAULT_CLAIMS,
-		...meta?.claims
-	};
-}
-/** Where the active tenant is read from: the top-level claim, then `app_metadata`. */
-function tenantClaimPaths(tenant = DEFAULT_CLAIMS.tenant) {
-	return [tenant, `app_metadata.${tenant}`];
-}
-/** The string at a dotted claim path, if any. */
-function claimAt(claims, path) {
-	let value = claims;
-	for (const segment of path.split(".")) value = typeof value === "object" && value !== null ? value[segment] : void 0;
-	return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-//#endregion
-export { tenantClaimPaths as i, claimAt as n, claimsOf as r, DEFAULT_CLAIMS as t };