better-supabase 0.3.0 → 0.5.0

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

@@ -1,28 +1,32 @@
 ---
 name: better-supabase-api
-description: Build HTTP APIs, Edge Functions and MCP servers on Supabase with better-supabase adapters. Use when adding a route, REST resource, oRPC procedure, Edge Function, MCP tool, webhook, background job or idempotent endpoint.
+description: Build HTTP APIs, Edge Functions and MCP servers on Supabase with better-supabase adapters. Use when adding a route, REST resource, oRPC procedure, Edge Function, MCP tool, OAuth or agent scopes, webhook, background job, cleanup cron or idempotent endpoint.
 ---
 
 # APIs with better-supabase
 
 Every adapter resolves the caller once and hands you `{ auth, db, supabase }`.
-`auth.kind` is `user`, `anon`, `service` or `invalid`.
+`auth.kind` is `user`, `anon`, `service` or `invalid`. For sessions, claims
+and the OAuth client or agent behind a token, see the `better-supabase-auth`
+skill.
 
 ## Workflow: add an endpoint
 
 1. Pick the adapter for the runtime (table below). Setup code for each is in
    [references/adapters.md](references/adapters.md).
-2. Decide who may call it with `allow` (see below).
+2. Decide who may call it with `allow`, and which scopes a delegated token
+   needs with `scopes` (see below).
 3. Use `db` from the handler context and return its `Result`, a plain value
    or a `Response`.
 4. For a table exposed as REST, prefer `bs.resource(...)` over hand-written
    routes, and regenerate `openapi.json` with `better-supabase openapi emit`.
-5. Add an API test that calls the endpoint as a user and as another tenant
-   (the `better-supabase-testing` skill).
+5. Add an API test that calls the endpoint as a user and as another tenant,
+   and with a delegated token that lacks the scope (the
+   `better-supabase-testing` skill).
 
-Done when the endpoint rejects callers outside `allow`, errors come back as
-Problem Details (no hand-built error JSON), and `openapi emit --check` passes
-if the project has an OpenAPI file.
+Done when the endpoint rejects callers outside `allow` and tokens without its
+`scopes`, errors come back as Problem Details (no hand-built error JSON), and
+`openapi emit --check` passes if the project has an OpenAPI file.
 
 ## Who gets in
 
@@ -30,15 +34,36 @@ if the project has an OpenAPI file.
 and `['service']` for machine callers. Rejected callers get a 401 with a
 `WWW-Authenticate` header, or a 403, as Problem Details.
 
+`scopes` limits what a delegated token may do: a token from the Supabase
+OAuth server (`client_id` and `scope`) or one exchanged for an agent (an
+RFC 8693 `act` chain). The guard options of `bs.route`, `bs.action`,
+`bs.handler` (edge) and `bs.middleware` (Hono, oRPC) take it, next to
+`allow`:
+
+```ts
+export const GET = bs.route(
+  (request, { db }) => db.customers.findMany({ limit: 20 }),
+  { scopes: ["customers:read"] },
+);
+```
+
+With `.claims(schema)` on the definition, `auth.claims` is typed in every
+adapter (`c.var.auth`, `context.auth`, the edge handler's `auth`, MCP's
+`ctx.auth`). Read roles from it; don't parse the claims again.
+
+A token without the scope gets a 403 with an `insufficient_scope`
+challenge. The user's own session holds no `client_id` or `act`, so `scopes`
+never limits it. RLS still decides the rows: the token's `sub` is the user.
+
 ## Adapters
 
-| Where          | Setup                                               | Handler                                                                                      |
-| -------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Next.js        | `createNext(sb)` in `lib/supabase.server.ts`        | `next.route((req, { db }) => ...)`, `next.action({ input: schema }, (input, { db }) => ...)` |
-| Hono           | `createHono(sb)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST                                       |
-| oRPC           | `createOrpc(sb)`, `base.use(bs.middleware())`       | `bs.unwrap(context.db.customers.findMany(...))`                                              |
-| Edge Functions | `createEdge(sb, { cors: true })`                    | `Deno.serve(bs.handler((req, { db }) => ...))`                                               |
-| MCP            | `createMcp(sb, { name, version, resources })`       | `.tool({ name, input, run: (args, { db }) => ... })`                                         |
+| Where          | Setup                                                           | Handler                                                                                  |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Next.js        | `createNext(betterSupabase)` in `lib/supabase/server.ts`        | `bs.route((req, { db }) => ...)`, `bs.action({ input: schema }, (input, { db }) => ...)` |
+| Hono           | `createHono(betterSupabase)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST                                   |
+| oRPC           | `createOrpc(betterSupabase)`, `base.use(bs.middleware())`       | `bs.unwrap(context.db.customers.findMany(...))`                                          |
+| Edge Functions | `createEdge(betterSupabase, { cors: true })`                    | `Deno.serve(bs.handler((req, { db }) => ...))`                                           |
+| MCP            | `createMcp(betterSupabase, { name, version, resources })`       | `.tool({ name, input, run: (args, { db }) => ... })`                                     |
 
 Don't build error JSON by hand; errors become Problem Details.
 
@@ -46,17 +71,45 @@ Don't build error JSON by hand; errors become Problem Details.
 
 `defineResource` / `bs.resource(table, { operations, list, input })` gives you
 list, get, create, update and delete, with validation and paging (`{ items, page }`).
-`createOpenApi(sb, { resources })` describes the same routes, and
+`createOpenApi(betterSupabase, { resources })` describes the same routes, and
 `better-supabase openapi emit --check` keeps `openapi.json` in sync.
 
+Pass `pagination: "cursor"` to a resource, `defineListQuery` or an MCP table
+for lists that clients read page by page: the list takes `after` instead of
+`page`, returns `nextCursor` and `hasMore`, and `size` stays capped by
+`maxPageSize`. The OpenAPI document and the JSON Schema describe the cursor.
+
+## MCP servers
+
+- Tools run as the calling user, so RLS applies to every call.
+- `authorize(ctx, tool, args)` refuses a call (`{ allowed: false, reason, scopes }`; with `scopes` it is a 403 `insufficient_scope`). `visible(ctx, tool)` hides tools from `tools/list`. Put a permission or a label in a tool's `meta`; clients never see it.
+- `scopes` on `createMcp` only advertises scopes. Refuse calls in `authorize`, reading `toSession(ctx.auth).delegation?.scopes`.
+- Set `allowedOrigins` and `allowedHosts` (every host the server answers on, previews and local included) against DNS rebinding, and `resourceDocumentation` to a page that explains how to connect.
+
 ## Background work (`better-supabase/jobs`, needs `sql add jobs idempotency webhook-inbox`)
 
-- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload)` uses pg_cron. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
+- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload, { timeZone })` uses pg_cron, or with `kits.jobs.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `kits.jobs.options.backend: "table"` runs without pgmq. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
 - `createIdempotency(postgres.admin).handle(request, handler)` for POST endpoints that clients retry.
 - `createInbox(postgres.admin, { source, secrets }).receive(request)` for webhooks; `process(handler)` later.
+- Times are `Temporal.Instant`: `EnqueueOptions.runAt`, `Job.enqueuedAt`, `Job.visibleUntil`, `InboxMessage.receivedAt` and webhook timestamps.
+- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()`, `purge_idempotency_keys()`, `purge_rate_limits()`, `purge_outbox()`, `purge_notifications()` and `purge_webhook_deliveries()`, for the modules you installed. Only `service_role` can execute them.
+- Audit a table with `better_supabase.audit('public.t', redact => '{secret}', event_prefix => 't')`; record non-row events with `better_supabase.audit_event(event_type, ...)` and an `idempotency_key`. For per-tenant retention, write an `audit_retention(tenant)` SQL function or call `purgeAuditLog(sql, { retention })` from `better-supabase/jobs`.
+- For a "view as user" support mode, add the `support-sessions` SQL module, pass `support: supportSessions({ store: sqlSupportStore(postgres) })` to `createServer`, call `bs.startSupport({ targetUserId, reason })` and `bs.stopSupport()` from server actions, and show a banner with `useSupportSession()`. Sessions are read-only by default; grant admins the `support.start` platform permission.
+- For teams, add the `organizations` and `invitations` SQL modules and call them through `createOrgs({ transport: sqlTransport(postgres.asUser(claims)), events: betterSupabase.events, onInvite })` from `better-supabase/orgs`. Send the invitation email in `onInvite`, show `previewInvitation(token)` on the accept page, and switch with `orgs.switch(id)`, refreshing the session when it returns `refresh: true`. Errors carry codes such as `ORG_SLUG_TAKEN` in `hint`. Existing tables work with `mode: 'adopt'`.
+- For user profiles, add the `profiles` SQL module: sign-up creates the row from auth metadata with a unique username and mirrors the email; users update only the `updatable` columns. Adopt an existing table with `mode: 'adopt'` and `syncTrigger: false` when your own trigger creates profiles. Use `avatarBucket()` and `orgLogoBucket()` from `better-supabase/storage` for uploads; `policy: { access: { read, write } }` checks any bucket through the access contract.
+- For events other systems must see, add the `outbox` SQL module and write events with `emit_event(type, payload, subject, tenant, key)` inside the same transaction as the change (the kit modules emit theirs automatically). Relay them with `createOutbox(postgres.admin, { source }).relayRoute({ secret, consumers: { name: httpSink(url) } })` from `better-supabase/jobs` after `outbox.register(name, { types })`. Delivery is at least once; receivers deduplicate on the CloudEvent `id`.
+- For in-app notifications, add the `notifications` SQL module and send with `createNotifications({ transport: sqlTransport(postgres.asUser(claims)), types })` from `better-supabase/notifications`, where `types` maps each notification type to a Standard Schema for its data. Pass a `key` so retries don't notify twice. Show them with `useNotifications({ topic, load })` from `better-supabase/react`; the topic defaults to `notifications:{userId}`. For email or push, pass `channels` and call `notifications.deliver()` from a cron route with a service connection.
+- For webhooks to customers' endpoints, add the `webhooks-out` SQL module and publish with `createWebhooks({ transport: sqlTransport(postgres.admin) }).publish({ type, data, tenant, id })` from `better-supabase/webhooks`. Pass an `id` so retries don't send twice. Send with `webhooks.deliverRoute({ secret: process.env.CRON_SECRET })` from a cron route; deliveries are signed with Standard Webhooks and only go to public HTTPS URLs by default.
 
 Done when a failing job is retried and then archived after `maxAttempts`,
-and a replayed webhook or POST doesn't run twice.
+a replayed webhook or POST doesn't run twice, and each kit table has a purge
+schedule.
+
+## Direct Postgres on the server
+
+- `createPostgres()` opens a pool; `createPostgres({ pool })` runs on an existing `pg.Pool`. `asUser` and `anon` transactions get Supabase's role timeouts (8 s and 3 s); `statementTimeout` takes a number or `{ admin, authenticated, anon }`.
+- `createMany` and `upsertMany` split inserts past 65,535 bind parameters into several statements in one transaction, so large batches don't need manual chunking.
+- In serverless functions, connect through the transaction pooler (port 6543), not a direct connection.
 
 ## Testing
 
@@ -64,4 +117,6 @@ Sign tokens with `signLocalJwt` or `asUser` from `better-supabase/testing`;
 the adapter verifies them against the local JWKS. See the `better-supabase-testing` skill.
 
 Docs: https://bettersupabase.com/docs/frameworks/hono.md (and `next`,
-`orpc`, `edge`, `mcp` under `/docs/frameworks/`).
+`orpc`, `edge`, `mcp` under `/docs/frameworks/`),
+https://bettersupabase.com/docs/kits/jobs.md and
+https://bettersupabase.com/docs/auth/postgres.md.

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

@@ -1,57 +1,59 @@
 # 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 "server-only";
 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 { Hono } from "hono";
+import { createHono } from "better-supabase/hono";
 
-import { type Functions, type Models, sb } from "./lib/supabase";
+import { betterSupabase } from "./lib/supabase";
 
-const bs = createHono(sb);
+const bs = createHono(betterSupabase);
 
-const app = new Hono<BetterEnv<Models, Functions, unknown>>()
-  .onError(bs.onError)
+// bs.app() is new Hono<typeof bs.Env>() with bs.onError installed.
+const app = bs
+  .app()
   .use("/api/*", bs.middleware())
   .get("/api/me", (c) => c.json({ kind: c.var.auth.kind }))
   .route(
@@ -68,9 +70,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 +87,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 +100,35 @@ 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"] } },
+  advertisedScopes: ["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.
+`advertisedScopes` only advertises scopes; `requiredScopes` refuses delegated
+tokens that lack one, and `authorize` refuses a single call. The session comes
+from the `Authorization` header only, never from a cookie. 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,149 @@
+---
+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.
+- For signed-out, banned or deleted users, add the `sessions` SQL module and a
+  restrictive policy with `using ((select better_supabase.session_active()))`
+  on the tables that guard sensitive data.
+- 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,100 @@
+# 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`. The scope is the
+  manifest's root scope (the `rls.scopes` entry without `within`); set
+  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for
+  another one.
+- 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` (`permdock` by default). Buckets
+  and topics in `permdock` mode call them in `permdock` unless their `schema`
+  option names another schema; it must equal `rls.schema`.
+- Use the scope names the manifest declares (`organization`, not PermDock's
+  `tenant` alias): the helpers are named after them, and doctor reports a
+  key checked at another scope than its catalog entry.
+- The entitlements module needs PermDock's hook to fill `claims.features`
+  from `better_supabase.feature_claims`
+  (`supabase.hook.claims: { features: 'better_supabase.feature_claims' }`).
+- The `permdock` policy mode checks role and scope only. Use it only for
+  permissions whose `rowConditions` is `false` in `permissions.catalog.json`.
+  A missing flag or a key the catalog doesn't list is unknown and refused;
+  regenerate the catalog with a current `permdock catalog`.
+  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`. A tool without a
+  PermDock permission in `meta` is denied: `visible` returns `false` and
+  `authorize` returns `{ allowed: false }`. Use `decide` instead of `can` to
+  put the denial reason in the refusal. `can` decides without a row, so check
+  row-conditioned permissions inside `run` or rely on RLS.
+- In oRPC and Hono, pass the adapter's auth state to PermDock:
+  `createPermDock(policy, { subject: ({ context }) => subjectFromSupabaseSession(context.auth) })`
+  from `permdock/orpc`, or `(c) => subjectFromSupabaseSession(c.get("auth"))`
+  from `permdock/hono`. Fail closed: export one builder that takes a
+  permission (`(permission) => authed.use(pd.protect(permission))`, or the
+  route helper `[bs.middleware(), pd.protect(permission)]` in Hono), and don't
+  install `bs.middleware()` app-wide, so a route without a permission has no
+  `db`.
+- In Next.js, cache the permission snapshot in a `'use cache: private'`
+  loader. The user id and the snapshot only exist after `bs.cached()`
+  returns, so pass it the static tags only, then tag and time the entry from
+  inside the loader with Next.js's `cacheTag` and `cacheLife`:
+
+  ```ts
+  import { cacheLife, cacheTag } from "next/cache";
+  import { snapshotFor } from "permdock";
+  import { cacheLifeFor, snapshotTag } from "permdock/next";
+  import { subjectFromSupabaseSession } from "permdock/supabase";
+
+  export async function loadSnapshot(orgId: string) {
+    "use cache: private";
+    const { session } = await bs.cached({ tags: [`org:${orgId}`] });
+    const snapshot = snapshotFor(policy, subjectFromSupabaseSession(session), {
+      tenant: orgId,
+    });
+    if (session.kind === "user") cacheTag(snapshotTag(session.user.id));
+    cacheLife(cacheLifeFor(snapshot));
+    return snapshot;
+  }
+  ```
+
+  `bs.cached()` already caps the stale time at the token's expiry, and Next.js
+  keeps the smaller `stale` of the two `cacheLife` calls. When a role or plan
+  changes, drop the user's entries and the snapshot with
+  `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`.
+
+- 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 };