better-supabase 0.5.0 → 0.5.1

package/dist/testing/index.js

@@ -970,6 +970,146 @@ async function expectTenantIsolation(betterSupabase, options) {
 	}
 }
 //#endregion
+//#region src/testing/claims-fixtures.ts
+const base = {
+	sub: "6f1c2c1e-5d0a-4d9e-9a51-6b1f0e7c2a10",
+	aud: "authenticated",
+	role: "authenticated",
+	iss: "https://project.supabase.co/auth/v1",
+	aal: "aal1",
+	session_id: "b7a8f9c0-1111-4222-8333-944455556666",
+	is_anonymous: false
+};
+const admin = "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d";
+const supportSessionId = "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b";
+const client = "5f0e4d3c-2b1a-4098-8776-655443322110";
+const chain = {
+	sub: "agent-runner",
+	act: { sub: "mcp-client-42" }
+};
+/**
+* `supportSession` and `supportSessionReadOnly` are what `supportClaims`
+* mints (`act.kind: "support"`), `impersonation` what `actingAs` mints
+* (`act.kind: "impersonation"`), `oauthClient` a Supabase OAuth server token
+* and `agentChain` an RFC 8693 chain without `kind`.
+*/
+const supabaseClaimFixtures = {
+	supportSession: {
+		claims: {
+			...base,
+			act: {
+				kind: "support",
+				sub: admin,
+				reason: "ticket 42",
+				session_id: supportSessionId,
+				read_only: false
+			}
+		},
+		expect: {
+			actor: {
+				kind: "support",
+				id: admin,
+				sessionId: supportSessionId,
+				readOnly: false,
+				reason: "ticket 42"
+			},
+			impersonator: {
+				kind: "support",
+				id: admin,
+				sessionId: supportSessionId,
+				readOnly: false,
+				reason: "ticket 42"
+			}
+		}
+	},
+	supportSessionReadOnly: {
+		claims: {
+			...base,
+			act: {
+				kind: "support",
+				sub: admin,
+				reason: "ticket 42",
+				session_id: supportSessionId,
+				read_only: true
+			}
+		},
+		expect: {
+			actor: {
+				kind: "support",
+				id: admin,
+				sessionId: supportSessionId,
+				readOnly: true,
+				reason: "ticket 42"
+			},
+			impersonator: {
+				kind: "support",
+				id: admin,
+				sessionId: supportSessionId,
+				readOnly: true,
+				reason: "ticket 42"
+			}
+		}
+	},
+	impersonation: {
+		claims: {
+			...base,
+			act: {
+				kind: "impersonation",
+				sub: admin,
+				reason: "ticket 42"
+			}
+		},
+		expect: {
+			actor: {
+				kind: "impersonation",
+				id: admin,
+				reason: "ticket 42"
+			},
+			impersonator: {
+				kind: "impersonation",
+				id: admin,
+				reason: "ticket 42"
+			}
+		}
+	},
+	oauthClient: {
+		claims: {
+			...base,
+			client_id: client,
+			scope: "openid email posts:read"
+		},
+		expect: {
+			actor: {
+				kind: "oauth-client",
+				id: client
+			},
+			delegation: { scopes: [
+				"openid",
+				"email",
+				"posts:read"
+			] }
+		}
+	},
+	agentChain: {
+		claims: {
+			...base,
+			scope: "posts:read",
+			act: chain
+		},
+		expect: {
+			actor: {
+				kind: "oauth-client",
+				id: "agent-runner",
+				chain
+			},
+			delegation: {
+				scopes: ["posts:read"],
+				chain
+			}
+		}
+	}
+};
+//#endregion
 //#region src/testing/seed.ts
 const SEED = Symbol.for("better-supabase.seed");
 function isSeed(value) {
@@ -1243,4 +1383,4 @@ function testWebhookSecretStore(store, options) {
 	]);
 }
 //#endregion
-export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectTenantIsolation, isSeed, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, testAuthResolver, testCacheAdapter, testEventSink, testExecutor, testGenerator, testNotificationChannel, testPlugin, testQueueBackend, testSupportSessionStore, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };
+export { ConformanceError, LOCAL_JWT_SECRET, asUser, createTestSigner, defineSeed, expectDbBudget, expectTenantIsolation, isSeed, localAuth, localSigningKey, signLocalJwt, signTestJwt, signTestJwtWithKey, supabaseClaimFixtures, testAuthResolver, testCacheAdapter, testEventSink, testExecutor, testGenerator, testNotificationChannel, testPlugin, testQueueBackend, testSupportSessionStore, testWebhookSecretStore, testWebhookSigner, testWebhookTransport };

package/dist/{version-DM_Roffb.js → version-DOYTYwHP.js}

@@ -1,4 +1,4 @@
 //#region src/core/version.ts
-const VERSION = "0.5.0";
+const VERSION = "0.5.1";
 //#endregion
 export { VERSION as t };

package/dist/{view-Bq64ki8-.js → view-Bn6HNKUe.js}

@@ -1,68 +1,9 @@
 import { n as dbError } from "./errors-DtwXa6b8.js";
 import { t as consoleLogger } from "./logger-glM28NVN.js";
 import { n as decodeJwtPayload } from "./base64-D2gsioCY.js";
-import { n as impersonatorOf, r as userContext } from "./impersonation-VfaGc4Q_.js";
+import { a as delegationOf, i as actorOf, n as impersonatorOf, r as userContext } from "./impersonation-BgSHAYLf.js";
 import { DEFAULT_COOKIE_OPTIONS, createChunks, isChunkLike, parseCookieHeader, serializeCookieHeader, stringFromBase64URL, stringToBase64URL } from "@supabase/ssr";
 import { extractCredentials, verifyCredentials } from "@supabase/server/core";
-//#region src/auth/actor.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function copyAct(level) {
-	const entries = Object.entries(level).map(([key, value]) => [key, key === "act" && isRecord(value) ? copyAct(value) : value]);
-	return Object.fromEntries(entries);
-}
-/**
-* Reads only `act` and `client_id`, the way PermDock's `actorOf` does. An
-* `act` that is not a chain of objects each with a non-empty `sub` is
-* `{ ok: false }`: the session must not pass as the user alone.
-*/
-function actorOf(claims) {
-	const outer = claims["act"];
-	if (outer !== void 0) {
-		let level = outer;
-		while (level !== void 0) {
-			if (!isRecord(level)) return {
-				ok: false,
-				reason: "invalid-chain"
-			};
-			const sub = level["sub"];
-			if (typeof sub !== "string" || sub === "") return {
-				ok: false,
-				reason: "invalid-chain"
-			};
-			level = level["act"];
-		}
-		if (!isRecord(outer) || typeof outer["sub"] !== "string") return {
-			ok: false,
-			reason: "invalid-chain"
-		};
-		return {
-			ok: true,
-			actor: {
-				id: outer["sub"],
-				kind: "oauth-client",
-				chain: copyAct(outer)
-			}
-		};
-	}
-	const client = claims["client_id"];
-	if (typeof client === "string" && client !== "") return {
-		ok: true,
-		actor: {
-			id: client,
-			kind: "oauth-client"
-		}
-	};
-	return { ok: true };
-}
-/** The OAuth `scope` claim (a space-separated string or a list); `undefined` when empty. */
-function delegationOf(claims) {
-	const scope = claims["scope"];
-	const scopes = typeof scope === "string" ? scope.split(/\s+/u).filter(Boolean) : Array.isArray(scope) ? scope.filter((item) => typeof item === "string") : [];
-	return scopes.length > 0 ? { scopes } : void 0;
-}
-//#endregion
 //#region src/auth/refresh.ts
 /**
 * How long a finished refresh is reused for requests still carrying the old
@@ -402,7 +343,7 @@ async function checkClaims(state, options) {
 	if (!actorOf(state.claims).ok) return {
 		kind: "invalid",
 		reason: "actor",
-		error: dbError("unauthorized", "The token's act claim is not a chain of actors with a sub", { code: "ACTOR_INVALID" })
+		error: dbError("unauthorized", "The token's act claim is not a chain of actors with a sub, or has a kind other than support or impersonation", { code: "ACTOR_INVALID" })
 	};
 	if (!options.claims) return state;
 	let outcome = options.claims["~standard"].validate(state.claims);
@@ -703,10 +644,11 @@ function toSession(auth) {
 			const impersonator = impersonatorOf(auth.claims);
 			const outcome = actorOf(auth.claims);
 			const actor = outcome.ok ? outcome.actor : void 0;
-			const scopes = actor ? delegationOf(auth.claims)?.scopes : void 0;
-			const delegation = actor && (scopes || actor.chain) ? {
+			const client = actor?.kind === "oauth-client" ? actor : void 0;
+			const scopes = client ? delegationOf(auth.claims)?.scopes : void 0;
+			const delegation = client && (scopes || client.chain) ? {
 				scopes: scopes ?? [],
-				...actor.chain ? { chain: actor.chain } : {}
+				...client.chain ? { chain: client.chain } : {}
 			} : void 0;
 			return {
 				kind: "user",
@@ -739,4 +681,4 @@ function toSession(auth) {
 	}
 }
 //#endregion
-export { writeSession as _, checkAal as a, delegationOf as b, prefetchJwks as c, AUTH_CACHE_HEADERS as d, applyCookieWrites as f, sessionCookieName as g, serializeCookie as h, amrOf as i, rememberVerified as l, readSession as m, toSession as n, authContext as o, parseCookies as p, aalOf as r, clientIp as s, isAnonymousUser as t, resolveAuth as u, refreshSession as v, actorOf as y };
+export { writeSession as _, checkAal as a, prefetchJwks as c, AUTH_CACHE_HEADERS as d, applyCookieWrites as f, sessionCookieName as g, serializeCookie as h, amrOf as i, rememberVerified as l, readSession as m, toSession as n, authContext as o, parseCookies as p, aalOf as r, clientIp as s, isAnonymousUser as t, resolveAuth as u, refreshSession as v };

package/dist/{view-BEf0diC5.d.ts → view-CbgObAeb.d.ts}

@@ -1,30 +1,8 @@
 import { _ as DbError } from "./executor-BunPOO-k.js";
-import { i as InvalidReason, r as AuthState } from "./resolve-C15TJq77.js";
-import { n as AmrEntry, s as Impersonator, t as Aal } from "./mfa-CusDgPaD.js";
+import { n as Impersonator, o as AuthState, s as InvalidReason } from "./impersonation-BmePsuxz.js";
+import { n as AmrEntry, t as Aal } from "./mfa-Cu96oJdw.js";
+import { n as SessionActor, r as SessionDelegation } from "./actor-DaJjqD5R.js";
 import { JWTClaims, UserClaims } from "@supabase/server";
-//#region src/auth/actor.d.ts
-/** One level of an RFC 8693 `act` chain: who acts, and who acted before it. */
-interface ActClaim {
-  readonly sub: string;
-  readonly act?: ActClaim;
-  readonly [claim: string]: unknown;
-}
-/**
- * The app acting for the user: the outermost `sub` of an RFC 8693 `act`
- * chain (prior actors stay on `chain`), else the OAuth `client_id` of a
- * Supabase OAuth server token.
- */
-interface SessionActor {
-  readonly id: string;
-  readonly kind: "oauth-client";
-  readonly chain?: ActClaim;
-}
-/** What the user delegated to the actor: the token's OAuth `scope`. */
-interface SessionDelegation {
-  readonly scopes: readonly string[];
-  readonly chain?: ActClaim;
-}
-//#endregion
 //#region src/auth/view.d.ts
 /**
  * The verified caller as plain data: no token, no clients. Safe to return
@@ -50,19 +28,27 @@ type AuthSession<C = unknown, P = unknown> = {
   readonly aal: Aal;
   /**
    * Signed in with `signInAnonymously()` (the `is_anonymous` claim). Guards
-   * refuse these users unless `allow` lists `'anonymous'`.
+   * refuse these users unless `allow` lists `'anonymous'`; `'anon'` means
+   * no session and never admits them.
    */
   readonly anonymous: boolean;
   /** How the user signed in (`password`, `totp`, `sso/saml`, ...). */
   readonly amr: readonly AmrEntry[];
-  /** Set when an admin acts as this user (the `act` claim), for a banner. */
+  /**
+   * Set when an admin acts as this user in a support session or an
+   * impersonated session (`act.kind`), for a banner. Matches `actor`.
+   */
   readonly impersonator?: Impersonator;
   /**
-   * The OAuth client or agent acting for the user (`client_id`, or the
-   * outermost `sub` of the `act` chain), as PermDock's `actorOf` reads it.
+   * Who acts for the user: an OAuth client or agent (`client_id`, or an
+   * `act` chain without `kind`), a support session or an impersonated
+   * session, as PermDock's `actorOf` reads it.
    */
   readonly actor?: SessionActor;
-  /** The scopes the user granted `actor`, plus its `act` chain. Set only with `actor`. */
+  /**
+   * The scopes the user granted an `oauth-client` actor, plus its `act`
+   * chain. Never set for a support or impersonated session.
+   */
   readonly delegation?: SessionDelegation;
 } | {
   readonly kind: "service";
@@ -81,4 +67,4 @@ type AnonReason = Extract<AuthState, {
 /** Drops the token from an `AuthState`, leaving only serializable fields. */
 declare function toSession<C, P>(auth: AuthState<C, P>): AuthSession<C, P>;
 //#endregion
-export { SessionDelegation as a, SessionActor as i, toSession as n, ActClaim as r, AuthSession as t };
+export { toSession as n, AuthSession as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-supabase",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue, framework integrations and the better-supabase CLI.",
   "keywords": [
     "cli",
@@ -190,12 +190,12 @@
     "provenance": true
   },
   "dependencies": {
-    "@standard-schema/spec": "1.1.0",
-    "@supabase/middleware": "1.0.0",
-    "@supabase/postgrest-js": "2.117.2",
-    "@supabase/postgrest-typegen": "0.3.1",
-    "@supabase/server": "1.9.0",
-    "@supabase/ssr": "0.12.7"
+    "@standard-schema/spec": "^1.1.0",
+    "@supabase/middleware": "^1.0.0",
+    "@supabase/postgrest-js": "^2.116.0",
+    "@supabase/postgrest-typegen": "0.4.0",
+    "@supabase/server": "^1.9.0",
+    "@supabase/ssr": "^0.12.7"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
@@ -204,13 +204,13 @@
     "@clack/prompts": "1.8.1",
     "@effect/platform-node": "4.0.0",
     "@opentelemetry/api": "1.9.1",
-    "@orpc/server": "2.0.0-beta.40",
+    "@orpc/server": "2.0.0-beta.41",
     "@supabase/config": "0.11.1",
     "@supabase/supabase-js": "2.117.2",
     "@t3-oss/env-core": "0.13.11",
-    "@tanstack/query-core": "5.104.0",
-    "@tanstack/react-query": "5.104.0",
-    "@types/node": "26.6.3",
+    "@tanstack/query-core": "5.104.1",
+    "@tanstack/react-query": "5.104.1",
+    "@types/node": "26.6.4",
     "@types/pg": "8.23.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -228,7 +228,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "pg": "8.23.1",
-    "publint": "0.3.24",
+    "publint": "0.3.25",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "smol-toml": "1.9.0",
@@ -248,7 +248,7 @@
     "@tanstack/query-core": "^5.62.0",
     "hono": ">=4 <5",
     "next": ">=16 <17",
-    "oxfmt": "0.66.0",
+    "oxfmt": ">=0.66.0 <1",
     "pg": ">=8.15 <9",
     "react": "^19",
     "temporal-polyfill": ">=1"

package/schemas/doctor-report-v1.json

@@ -91,6 +91,7 @@
               "BS408",
               "BS409",
               "BS410",
+              "BS411",
               "BS501",
               "BS502"
             ]

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

@@ -61,16 +61,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
@@ -139,6 +145,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
 

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

@@ -96,5 +96,27 @@ the other.
 
 - Doctor BS405 measures `memberships` plus `attrs` against PermDock's 1 KB
   budget and the whole token against 2 KB; run `doctor --as <user id>`.
+- For the SQL kit, set `kits.access.model: 'permdock'` and
+  `kits.access.functions.canAssign: 'permdock.permdock_can_assign({role}, {tenant}::text)'`
+  (use the manifest's `rls.schema`), then run `permdock supabase inspect --out`
+  before `sql add`. The kit reads the schema, the root scope and its id type
+  from `permdock.manifest.json`, and `sql add` stops instead of guessing when
+  the manifest can't give them. Every permission key the kit modules check
+  (`kitPermissionKeys` from `better-supabase/sql`) must be
+  `rowConditions: false` in `permissions.catalog.json`; map others with
+  `kits.<module>.permissions`. Doctor reports BS411.
+- Under that model `can_user()` and `member_can()` answer for the caller only
+  and raise SQLSTATE `0A000` for another user. Invitations skip the inviter
+  re-check at accept time and notifications don't filter recipients by read
+  permission; check both in the app when they matter.
+- The `act` claim says who acts: `kind: "support"` (support sessions,
+  `session.actor.kind === 'support'` with `sessionId` and `readOnly`),
+  `kind: "impersonation"` (`actingAs`), or no `kind` for an OAuth client or
+  agent chain (`oauth-client`, limited by `scopes`). Another `kind` makes the
+  session invalid. `session.impersonator` is set for the first two only.
+  `supabaseClaimFixtures` in `better-supabase/testing` has one token of each.
+- Only `allow: ['anonymous']` admits `signInAnonymously()` users; `'anon'`
+  means no session. Pair the default `allow` with PermDock's
+  `rls: { anonymousSignIns: 'deny' }` in `permdock.config.ts`.
 
 Docs: https://bettersupabase.com/docs/auth/permdock.md

package/dist/cli/gen-BJc9vdyu.js

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

package/dist/impersonation-VfaGc4Q_.js

@@ -1,41 +0,0 @@
-//#region src/auth/impersonation.ts
-/** The `act` claim for an impersonated session. */
-function actClaim(options) {
-	return {
-		sub: options.actor,
-		reason: options.reason
-	};
-}
-/** The impersonator in `claims.act`, or `undefined` for a normal session. */
-function impersonatorOf(claims) {
-	const act = claims["act"];
-	if (typeof act !== "object" || act === null) return void 0;
-	const { sub, reason, session_id, read_only } = act;
-	if (typeof sub !== "string" || sub === "") return void 0;
-	return {
-		id: sub,
-		...typeof reason === "string" ? { reason } : {},
-		...typeof session_id === "string" ? { sessionId: session_id } : {},
-		...typeof read_only === "boolean" ? { readOnly: read_only } : {}
-	};
-}
-/**
-* The repository context of a signed-in user: the actor, with the
-* impersonator from `act`, and the claims. Every adapter builds it here, so
-* plugins see the same actor on the server, in middleware and in the browser.
-*/
-function userContext(user, claims) {
-	const impersonator = impersonatorOf(claims);
-	return {
-		actor: {
-			id: user.id,
-			kind: "user",
-			...user.role ? { role: user.role } : {},
-			...user.email ? { email: user.email } : {},
-			...impersonator ? { impersonator: impersonator.id } : {}
-		},
-		claims
-	};
-}
-//#endregion
-export { impersonatorOf as n, userContext as r, actClaim as t };