better-supabase 0.5.0 → 0.6.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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 authorization providers. 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 better-supabase.config.ts has an authorization key.
 ---
 
 # Auth with better-supabase
@@ -50,7 +50,8 @@ path treats `invalid` as `anon`.
    `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.
+   request body. A tenant from the URL or input is only safe through the
+   `tenant` resolver or the `{ tenant }` option, which check membership.
 
 Done when `session.claims` is typed without casts, and a token whose claims
 fail the schema gets a 401 with code `CLAIMS_INVALID`.
@@ -61,16 +62,22 @@ 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 }`  |
+| 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 }`  |
+| `act: { kind: "support", sub, session_id, ... }` | `{ kind: "support", id, sessionId, readOnly }` | not set              |
+| `act: { kind: "impersonation", sub, reason }`    | `{ kind: "impersonation", id, reason }`        | not set              |
 
 - 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.
+  scope answers 403 with an `insufficient_scope` challenge. Only an
+  `oauth-client` actor is limited: the user's own token, a support session
+  and an impersonated session are not.
+- Switch on `session.actor.kind` with a `never` default: it is
+  `oauth-client`, `support` or `impersonation`. An `act` with another `kind`
+  resolves to `invalid` with reason `actor`.
 - 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
@@ -95,22 +102,40 @@ 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.
 
+When RLS checks the session (so an ended session sees no rows), sign the
+browser out on page loads instead of showing an empty app. Next.js:
+`bs.proxy(request, { endedSession: { redirect: "/login" } })` asks Auth on
+document loads (and on `paths`), clears the cookies and redirects with
+`?reason=session_ended`.
+A proxy or middleware with its own Supabase client calls
+`sessionStatus(request, { url, publishableKey })` from `better-supabase/ssr`
+(`"ended"` on a 401 or 403 from Auth; treat `"unknown"` as active) and
+`clearSessionCookies(request, response, { url })` before redirecting.
+
 Done when the irreversible action returns `SESSION_REVOKED` for a signed-out
 session in a test.
 
+To lock a user out, call `bs.suspendAccount(userId, { suspended: true })`
+(it bans the user in Auth and ends every session and refresh token), or
+`bs.endSessions(userId)` to sign them out everywhere without a ban. A ban
+alone leaves the refresh tokens, which work again once the ban is lifted. To
+switch a member off in one organization only, use the organizations block's
+`suspendMember`.
+
 ## 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
+  `organization_id in (select better_supabase.member_organization_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.
+  `supabase.auth.refreshSession()` in the browser (in Next.js, through
+  `useSessionChange`'s `refreshToken`, below).
 - In Next.js, drop the user's cached views with
   `bs.invalidateSession(userId, { tags })`.
 
@@ -120,16 +145,33 @@ membership lasts until the next refresh. When that window matters:
   `'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.
+  further, for example for a permission snapshot.
+- `bs.cached({ tables: ["customers"] })` tags the entry by table, so an
+  action that writes the table drops it without a hand-written tag.
+- `bs.invalidateSession(userId)` reaches the server caches and the caller's
+  router only; another user's browser keeps its private entries until they
+  go stale.
+- After signing in or out: `useSessionChange(sessionChanged)` from
+  `better-supabase/next/client`. After switching the active organization:
+  `useSessionChange(sessionChanged, router, { refreshToken: supabase })`, so
+  the new token reaches the server before it renders.
+- For a tenant from the route params, call `bs.cached({ tenant })` and take
+  the tenant as an argument of the `'use cache: private'` function, so it is
+  part of the cache key. Outside a cache, use `bs.context({ tenant })`.
+- In the proxy, set `bs.proxy(request, { protect, expiredPrefetch: "render" })`
+  instead of returning early for `{ kind: "anon", reason: "expired" }` in
+  `protect`. A prefetch never refreshes, so without it the prefetch caches a
+  redirect to sign-in.
 - Keep layouts synchronous: pass the `bs.session()` promise to
   `<SessionProvider>` and read it with `useSession()`.
 
-## PermDock
+## Authorization providers
 
-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.
+When `better-supabase.config.ts` has an `authorization` key, another package
+answers permission checks and may own the access token hook, roles,
+memberships and the tenant claim. Read
+[references/authorization-providers.md](references/authorization-providers.md)
+before touching the hook, claims, tenant or entitlements.
 
 ## Don't
 
@@ -139,6 +181,8 @@ claims, tenant or entitlements.
 - 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`.
+- Don't use `allow: ['anon']` for users from `signInAnonymously()`: `'anon'`
+  means no session, and only `'anonymous'` admits anonymous sign-ins.
 
 ## Docs
 
@@ -146,4 +190,4 @@ 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.
+https://bettersupabase.com/docs/extending/authorization-providers.md.

package/skills/better-supabase-auth/references/authorization-providers.md

@@ -0,0 +1,51 @@
+# Authorization providers
+
+An authorization provider is a plain object in the `authorization` key of
+`better-supabase.config.ts`. The authorization package builds it; you don't
+write it by hand. It names the SQL functions that answer permission checks,
+the scopes, the permission keys those functions answer completely, the
+membership tables and the access token hook the provider generates.
+
+```ts
+export default defineConfig({
+  authorization: authorizationProvider(), // from the authorization package
+  sql: { modules: { access: { model: "provider" } } },
+});
+```
+
+## Rules
+
+- When `authorization.tokenHook.ownedClaims` has `memberships`, the
+  provider's hook owns the memberships and the tenant claim. Don't run
+  `better-supabase sql add tenant` (it stops without `--force`), don't call
+  `membership_claims()` from a hook, and don't write the claims in
+  `ownedClaims` yourself. Doctor reports BS407 when a hook does.
+- `sql add entitlements` is fine. With a provider it reads memberships through
+  the provider's `memberIds` and `memberIdsFor` (`entitlements.memberships`
+  defaults to `"provider"`). For `hasEntitlement(session, ...)`, the
+  provider's hook must fill `features` from `better_supabase.feature_claims`;
+  doctor reports BS408 otherwise.
+- Name the same tenant claim on both sides: `claims.tenant` must equal
+  `authorization.tokenHook.tenantClaim` (BS409).
+- `sql.modules.access.model: "provider"` makes `can()`, `tenant_ids_with()`
+  and `platform_can()` call the provider's `idsWith` and `isPlatform`. Every
+  permission key a SQL module checks must be `sqlComplete: true` in
+  `authorization.permissions`; map an action to another key with
+  `sql.modules.<module>.permissions`. Doctor reports BS411.
+- Bucket and topic `access` policies call the access contract by default.
+  For another scope, copy the provider's `idsWith` and `isPlatform` into the
+  policy's `sql`. Use only keys marked `sqlComplete: true`: the policies check
+  role and scope, never row conditions. `gen` refuses other keys and doctor
+  reports BS214.
+- A scope id in a path or topic is compared as text, so the segment must be
+  the id's lowercase form.
+- For API keys, pass `claim: { name, tenant?, roles?, scopes?, serviceRoles? }`
+  to `apiKeyResolver` or `apiKeyClaims` so the request carries the claim the
+  provider's functions read.
+- In MCP servers, put the permission in each tool's `meta`, narrow it in
+  `authorize` and `visible`, and treat a tool without one as hidden and
+  refused.
+- Doctor `--as <user id>` measures the claims in `tokenHook.budget` against
+  its byte budget (BS405).
+
+Docs: https://bettersupabase.com/docs/extending/authorization-providers.md

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

@@ -51,7 +51,9 @@ const alice = await asUser(
   { postgres },
 );
 expect(await alice.db.customers.count().orThrow()).toBe(1);
-expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({
+expect(
+  await alice.db.customers.findById(OTHER_ORGANIZATION_CUSTOMER),
+).toMatchObject({
   ok: false,
 });
 ```

package/dist/cli/config-dtoekM0v.js

@@ -1,2 +0,0 @@
-import { a as loadConfig, i as importModule, n as findConfig, o as readSupabasePort, r as importExport, s as stdinDatabaseUrl, t as databaseUrl } from "./config-CPVpXP5I.js";
-export { databaseUrl, findConfig, importExport, importModule, loadConfig, readSupabasePort, stdinDatabaseUrl };

package/dist/cli/gen-BJc9vdyu.js

@@ -1,2 +0,0 @@
-import { n as genCommand } from "./gen-C2osRcr5.js";
-export { genCommand };