better-supabase 0.3.0 → 0.4.0

package/skills/better-supabase-api/references/adapters.md

@@ -1,56 +1,57 @@
 # Adapter setup
 
-Each adapter wraps the same `sb` from `src/lib/supabase.ts`:
+Each adapter wraps the same `betterSupabase` from `src/lib/supabase/index.ts`:
 
-```ts title="src/lib/supabase.ts"
+```ts title="src/lib/supabase/index.ts"
 import { defineSupabase } from "better-supabase";
 
-import { schema } from "./supabase/generated";
+import { schema } from "./generated";
 
-export type { Functions, Models } from "./supabase/generated";
+export type { Functions, Models } from "./generated";
 
-export const sb = defineSupabase(schema);
+export const betterSupabase = defineSupabase(schema);
 ```
 
 ## Next.js
 
-```ts title="src/lib/supabase.server.ts"
+```ts title="src/lib/supabase/server.ts"
 import { createNext } from "better-supabase/next";
 
-import { sb } from "./supabase";
+import { betterSupabase } from "./index";
 
-export const next = createNext(sb);
+export const bs = createNext(betterSupabase);
 ```
 
 ```ts title="src/proxy.ts"
 import type { NextRequest } from "next/server";
 
-import { next } from "./lib/supabase.server";
+import { bs } from "./lib/supabase/server";
 
-export const proxy = (request: NextRequest) => next.proxy(request);
+export const proxy = (request: NextRequest) => bs.proxy(request);
 ```
 
 The proxy is the only place that refreshes sessions. Server Components,
 route handlers and actions read the verified token:
 
 ```ts
-const { db } = await next.server();
-export const GET = next.route((request, { db }) =>
-  db.customers.findMany({ limit: 20 }),
+const { db } = await bs.context();
+export const GET = bs.route(
+  (request, { db }) => db.customers.findMany({ limit: 20 }),
+  { scopes: ["customers:read"] }, // only limits OAuth clients and agents
 );
 ```
 
 ## Hono
 
 ```ts title="src/server.ts"
-import { type BetterEnv, createHono } from "better-supabase/hono";
+import { type HonoEnv, createHono } from "better-supabase/hono";
 import { Hono } from "hono";
 
-import { type Functions, type Models, sb } from "./lib/supabase";
+import { type Functions, type Models, betterSupabase } from "./lib/supabase";
 
-const bs = createHono(sb);
+const bs = createHono(betterSupabase);
 
-const app = new Hono<BetterEnv<Models, Functions, unknown>>()
+const app = new Hono<HonoEnv<Models, Functions, unknown>>()
   .onError(bs.onError)
   .use("/api/*", bs.middleware())
   .get("/api/me", (c) => c.json({ kind: c.var.auth.kind }))
@@ -68,9 +69,9 @@ export default app;
 import { os } from "@orpc/server";
 import { createOrpc, type OrpcRequestContext } from "better-supabase/orpc";
 
-import { sb } from "./lib/supabase";
+import { betterSupabase } from "./lib/supabase";
 
-export const bs = createOrpc(sb);
+export const bs = createOrpc(betterSupabase);
 const authed = os.$context<OrpcRequestContext>().use(bs.middleware());
 
 export const router = {
@@ -85,9 +86,9 @@ export const router = {
 ```ts title="supabase/functions/api/index.ts"
 import { createEdge } from "better-supabase/edge";
 
-import { sb } from "../_shared/supabase.ts";
+import { betterSupabase } from "../_shared/supabase.ts";
 
-const bs = createEdge(sb, { cors: true });
+const bs = createEdge(betterSupabase, { cors: true });
 
 Deno.serve(
   bs.resources({ customers: { select: ["id", "name"] } }, { basePath: "/api" }),
@@ -98,16 +99,33 @@ Deno.serve(
 
 ```ts title="supabase/functions/mcp/index.ts"
 import { createMcp } from "better-supabase/mcp";
+import { toSession } from "better-supabase/server";
 
-import { sb } from "../_shared/supabase.ts";
+import { betterSupabase } from "../_shared/supabase.ts";
 
-const mcp = createMcp(sb, {
+const bs = createMcp(betterSupabase, {
   name: "crm",
   version: "0.1.0",
-  resources: { customers: { select: ["id", "name"] } },
+  scopes: ["openid", "crm.read"],
+  allowedOrigins: ["https://claude.ai"],
+  allowedHosts: ["crm.example.com", "localhost"],
+  resourceDocumentation: "https://crm.example.com/docs/mcp",
+  resources: {
+    customers: { select: ["id", "name"], pagination: "cursor" },
+  },
+  authorize: (ctx) => {
+    const session = toSession(ctx.auth);
+    const granted =
+      session.kind === "user" ? session.delegation?.scopes : undefined;
+    return !granted || granted.includes("crm.read")
+      ? { allowed: true }
+      : { allowed: false, reason: "Needs crm.read", scopes: ["crm.read"] };
+  },
 });
 
-Deno.serve(mcp.fetch);
+Deno.serve(bs.fetch);
 ```
 
-Tools run as the calling user, so RLS applies to every tool call.
+Tools run as the calling user, so RLS applies to every tool call. `scopes`
+on `createMcp` only advertises scopes; `authorize` refuses the call. A
+`delegation` that is unset means the user's own token, which no scope limits.

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
@@ -31,9 +31,9 @@ again once you restore it.
 
 ```ts
 import { defineSeed } from "better-supabase/testing";
-import { sb } from "../src/lib/supabase.ts";
+import { betterSupabase } from "../src/lib/supabase/index.ts";
 
-export const seed = defineSeed(sb, {
+export const seed = defineSeed(betterSupabase, {
   organizations: { acme: { id: ACME, name: "Acme" } },
   customers: { first: { id: FIRST, organizationId: ACME, name: "First" } },
 });
@@ -45,7 +45,11 @@ 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,
@@ -61,6 +65,56 @@ expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({
 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/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 };