permdock 0.1.0 → 0.3.0

package/dist/testing/saas/index.d.ts

@@ -1,7 +1,7 @@
-import { Qt as PermDockOptions, at as LimitStore, cr as CustomRole, ft as RelationSource, hr as Subject, ir as Actor, mr as Principal, pr as Membership, ur as Delegation } from "../../policy-CInmNGkM.js";
-import { d as Permission } from "../../permissions-B4apnahQ.js";
-import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-B8vCg_bI.js";
-import { n as saasPolicy, t as SAAS_API_KEY_LIMIT } from "../../policy-Cq2fB8Q5.js";
+import { Cr as Actor, Dr as CustomRole, Mr as Membership, Nr as Principal, Pr as Subject, bt as RelationSource, dt as LimitStore, kr as Delegation, un as PermDockOptions } from "../../policy-IB6yxpC3.js";
+import { f as Permission } from "../../permissions-DttnqqxC.js";
+import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-CDgvKG5L.js";
+import { n as saasPolicy, t as SAAS_API_KEY_LIMIT } from "../../policy-D2W7uv19.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/testing/saas/schema.d.ts
 type FieldKind = "string" | "boolean" | "nullable-string";

package/dist/testing/saas/index.js

@@ -1,3 +1,3 @@
-import { a as saasPlans, c as rowSchema, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-CofRqesP.js";
-import { C as saasOrg, D as saasUsers, E as saasSeed, O as SAAS_API_KEY_LIMIT, S as saasMemberships, T as saasRelations, _ as verifySaasToken, a as saasProject, b as SAAS_EXPIRED_AT, c as saasUser, d as saasIssuer, f as saasJwks, g as verifySaasSession, h as signSaasToken, i as saasLimitStore, k as saasPolicy, l as SAAS_TOKEN_TTL_SECONDS, m as saasPublicJwk, n as saasFolder, o as saasScenarioOptions, p as saasPrivateJwk, r as saasFolderScenarios, s as saasScenarios, t as saasDoc, u as saasAudience, v as saasSchemaSql, w as saasPrincipal, x as saasCustomRoles, y as saasSeedSql } from "../../saas-BRrZzJkM.js";
+import { a as saasPlans, c as rowSchema, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-RJrovw98.js";
+import { C as saasOrg, D as saasUsers, E as saasSeed, O as SAAS_API_KEY_LIMIT, S as saasMemberships, T as saasRelations, _ as verifySaasToken, a as saasProject, b as SAAS_EXPIRED_AT, c as saasUser, d as saasIssuer, f as saasJwks, g as verifySaasSession, h as signSaasToken, i as saasLimitStore, k as saasPolicy, l as SAAS_TOKEN_TTL_SECONDS, m as saasPublicJwk, n as saasFolder, o as saasScenarioOptions, p as saasPrivateJwk, r as saasFolderScenarios, s as saasScenarios, t as saasDoc, u as saasAudience, v as saasSchemaSql, w as saasPrincipal, x as saasCustomRoles, y as saasSeedSql } from "../../saas-DhpJjnBA.js";
 export { SAAS_API_KEY_LIMIT, SAAS_EXPIRED_AT, SAAS_TOKEN_TTL_SECONDS, SaasDocSchema, SaasFolderSchema, SaasProjectSchema, rowSchema, saasAudience, saasCustomRoles, saasDoc, saasFolder, saasFolderScenarios, saasIssuer, saasJwks, saasLimitStore, saasMemberships, saasOrg, saasPermissions, saasPlans, saasPolicy, saasPrincipal, saasPrivateJwk, saasProject, saasPublicJwk, saasRelations, saasRoles, saasScenarioOptions, saasScenarios, saasSchemaSql, saasSeed, saasSeedSql, saasTenantRoleNames, saasUser, saasUsers, signSaasToken, verifySaasSession, verifySaasToken };

package/dist/testing/saas/permissions.d.ts

@@ -1,2 +1,2 @@
-import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-B8vCg_bI.js";
+import { a as SaasProject, c as saasPlans, i as SaasFolderSchema, l as saasRoles, n as SaasDocSchema, o as SaasProjectSchema, r as SaasFolder, s as saasPermissions, t as SaasDoc, u as saasTenantRoleNames } from "../../permissions-CDgvKG5L.js";
 export { SaasDoc, SaasDocSchema, SaasFolder, SaasFolderSchema, SaasProject, SaasProjectSchema, saasPermissions, saasPlans, saasRoles, saasTenantRoleNames };

package/dist/testing/saas/permissions.js

@@ -1,2 +1,2 @@
-import { a as saasPlans, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-CofRqesP.js";
+import { a as saasPlans, i as saasPermissions, n as SaasFolderSchema, o as saasRoles, r as SaasProjectSchema, s as saasTenantRoleNames, t as SaasDocSchema } from "../../permissions-RJrovw98.js";
 export { SaasDocSchema, SaasFolderSchema, SaasProjectSchema, saasPermissions, saasPlans, saasRoles, saasTenantRoleNames };

package/dist/token-CIWxJOCh.js

@@ -0,0 +1,50 @@
+import { t as canonicalJson } from "./canonical-json-DemiK4Vp.js";
+import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+//#region src/core/token.ts
+/**
+* Only stable identity goes into the token, so refreshing a session (new
+* roles, assurance or claims) does not orphan an outstanding approval.
+*/
+function principalIdentity(principal) {
+	if (principal === null) return null;
+	return {
+		id: principal.id,
+		tenant: principal.tenant ?? null,
+		issuer: principal.issuer ?? null
+	};
+}
+/** A row's `version` field as token input; `null` when it is missing or not a scalar. */
+function versionOf(row, field) {
+	if (row === null || typeof row !== "object" || !Object.hasOwn(row, field)) return null;
+	const value = row[field];
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+	return typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" ? String(value) : null;
+}
+/** The digest that binds a token to the call's data when no row id does. */
+function payloadDigest(data) {
+	return bytesToBase64Url(sha256(canonicalJson(data)));
+}
+/**
+* `version` is set only for an approval that goes stale on a resource
+* change; without it the payload, and so every other token, is unchanged.
+* `payload` is set when `resourceId` is `*` (a collection action or a row
+* without an id), so an approval covers the arguments it was given and no
+* others.
+*/
+function decisionToken(input) {
+	const payload = JSON.stringify({
+		key: input.key,
+		resourceId: input.resourceId,
+		principal: principalIdentity(input.principal),
+		actor: input.actor === void 0 ? null : {
+			id: input.actor.id,
+			kind: input.actor.kind
+		},
+		fingerprint: input.fingerprint,
+		...input.version === void 0 ? {} : { version: input.version },
+		...input.payload === void 0 ? {} : { payload: input.payload }
+	});
+	return `pd1.${bytesToBase64Url(sha256(payload))}`;
+}
+//#endregion
+export { payloadDigest as n, versionOf as r, decisionToken as t };

package/dist/trpc/index.d.ts

@@ -1,10 +1,9 @@
-import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
-import { d as Permission } from "../permissions-B4apnahQ.js";
-import { f as ApprovalStore } from "../types-B8w5PFtS.js";
+import { C as Policy, Nr as Principal } from "../policy-IB6yxpC3.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
 import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
-import { r as PdpFactory } from "../types-BvBk1wgn.js";
-import { S as ConnectionOptions, b as Connection, h as WebBotAuthVerifier, n as OpenApiHooks, o as TenantOption } from "../create-BKF3dgFk.js";
-import { t as StreamProtectOptions } from "../stream-BhMfZOwr.js";
+import { A as ConnectionOptions, O as Connection, n as OpenApiHooks } from "../create-B1d519XK.js";
+import { t as ServerAdapterOptions } from "../bind-C_ob3LKa.js";
+import { t as StreamProtectOptions } from "../stream-D1RXubw2.js";
 import { AnyTRPCMiddlewareFunction } from "@trpc/server";
 //#region src/trpc/create.d.ts
 type TrpcMiddlewareOpts<TCtx = object, TInput = unknown> = {
@@ -17,27 +16,9 @@ type TrpcMiddlewareOpts<TCtx = object, TInput = unknown> = {
   }) => Promise<unknown>;
 };
 type TrpcMiddleware = AnyTRPCMiddlewareFunction;
-type TrpcPermDockOptions<TCtx = object, TUser = unknown> = {
-  readonly subject: (opts: TrpcMiddlewareOpts<TCtx>) => TUser | Promise<TUser>;
-  readonly tenant?: TenantOption<TrpcMiddlewareOpts<TCtx>>;
+type TrpcPermDockOptions<TCtx = object, TUser = unknown> = ServerAdapterOptions<TrpcMiddlewareOpts<TCtx>, TUser> & {
   /** The Web `Request` behind a context; defaults to `ctx.request` or `ctx.req`. */
   readonly request?: (ctx: TCtx) => Request | null | undefined;
-  readonly memberships?: MembershipSource | readonly MembershipSource[];
-  /** The object graph for relation grants that walk a parent chain; without it they deny. */
-  readonly relations?: RelationSource;
-  readonly entitlements?: EntitlementSource;
-  readonly customRoles?: RoleSource;
-  /** Hosted grants, read once per instance; see `PolicySource`. */
-  readonly policies?: PolicySource;
-  readonly store?: ApprovalStore;
-  readonly sink?: DecisionSink;
-  readonly limits?: LimitStore;
-  /** `createPermDock` from `permdock/pdp`; `protect` then decides delegated permissions remotely. */
-  readonly pdp?: PdpFactory;
-  /** Accepted for adapter parity; not read by this adapter. */
-  readonly snapshots?: SnapshotSource;
-  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
-  readonly webBotAuth?: WebBotAuthVerifier;
   /** Ends or revalidates open subscriptions. */
   readonly revocations?: RevocationFeed;
 };
@@ -53,7 +34,7 @@ type TrpcOpenApiHooks = {
 };
 type TrpcPermDock<TCtx = object> = {
   readonly permdock: () => TrpcMiddleware;
-  readonly protect: (permission: Permission, loadData?: (opts: TrpcMiddlewareOpts<TCtx>) => unknown, protectOptions?: StreamProtectOptions) => TrpcMiddleware;
+  readonly protect: (permission: Permission | null, loadData?: (opts: TrpcMiddlewareOpts<TCtx>) => unknown, protectOptions?: StreamProtectOptions) => TrpcMiddleware;
   /** A long-lived connection for the request behind `ctx`. */
   readonly connection: (opts: TrpcMiddlewareOpts<TCtx>, connectionOptions?: ConnectionOptions) => Promise<Connection>;
   readonly permdockHandler: (request: Request) => Promise<Response>;

package/dist/trpc/index.js

@@ -1,29 +1,11 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { o as invalidSignatureResponse } from "../evaluations-DsAU9ppl.js";
-import { r as tenantScope, t as createKernel } from "../create-CSkhDU9T.js";
-import { t as problemFromError } from "../map-error-RJ3ZsUyA.js";
-import { n as guardIterable, r as isAsyncIterable } from "../stream-Q_xlB6Ko.js";
+import { a as problemMessage } from "../http-SO7qGttf.js";
+import { t as problemFromError } from "../map-error-pgUWNNtG.js";
+import { n as attached } from "../bind-CuzGytRf.js";
+import { a as reloadAfter, r as isAsyncIterable } from "../stream-DDpvynSB.js";
+import { i as rpcCode, n as guardStream, r as problemBody, t as bindRpcKernel } from "../rpc-DL9Sqvb1.js";
 import { TRPCError, isTrackedEnvelope } from "@trpc/server";
 //#region src/trpc/create.ts
-function requestFromCtx(ctx) {
-	if ("request" in ctx && ctx.request instanceof Request) return ctx.request;
-	if ("req" in ctx && ctx.req instanceof Request) return ctx.req;
-}
-function problemMessage(cause, fallback) {
-	if (cause !== null && typeof cause === "object" && "detail" in cause && typeof cause.detail === "string" && cause.detail.length > 0) return cause.detail;
-	return fallback;
-}
 const PROBLEM = Symbol.for("permdock.problem");
-function trpcCode(status) {
-	switch (status) {
-		case 400: return "BAD_REQUEST";
-		case 401: return "UNAUTHORIZED";
-		case 404: return "NOT_FOUND";
-		case 429: return "TOO_MANY_REQUESTS";
-		case 503: return "SERVICE_UNAVAILABLE";
-		default: return "FORBIDDEN";
-	}
-}
 /** A `TRPCError` for a revoked subscription; the Problem Details body rides on `cause`. */
 function trpcErrorFrom(error) {
 	const problem = error.toProblemDetails();
@@ -33,23 +15,18 @@ function trpcErrorFrom(error) {
 		enumerable: true
 	});
 	return new TRPCError({
-		code: trpcCode(problem.status),
+		code: rpcCode(problem.status),
 		message: error.code,
 		cause
 	});
 }
 async function throwTrpcError(response) {
-	let cause;
-	try {
-		cause = await response.json();
-	} catch {
-		cause = { status: response.status };
-	}
+	const cause = await problemBody(response);
 	if (cause !== null && typeof cause === "object") Object.defineProperty(cause, PROBLEM, {
 		value: true,
 		enumerable: true
 	});
-	const code = trpcCode(response.status);
+	const code = rpcCode(response.status);
 	throw new TRPCError({
 		code,
 		message: problemMessage(cause, code),
@@ -80,84 +57,27 @@ function errorFormatter(opts) {
 	};
 }
 function createPermDock(policy, options) {
-	const optsByRequest = /* @__PURE__ */ new WeakMap();
-	const requestByCtx = /* @__PURE__ */ new WeakMap();
-	const kernel = createKernel(policy, compact({
-		subject: (request) => {
-			const opts = optsByRequest.get(request);
-			return opts === void 0 ? null : options.subject(opts);
-		},
-		memberships: options.memberships,
-		relations: options.relations,
-		entitlements: options.entitlements,
-		customRoles: options.customRoles,
-		policies: options.policies,
-		store: options.store,
-		sink: options.sink,
-		limits: options.limits,
-		pdp: options.pdp,
-		webBotAuth: options.webBotAuth,
-		revocations: options.revocations,
-		adapter: "trpc"
-	}));
-	const requestOf = (ctx) => {
-		if (options.request !== void 0) try {
-			return options.request(ctx) ?? void 0;
-		} catch {
-			return;
-		}
-		return requestFromCtx(ctx);
-	};
-	/**
-	* One `Request` per HTTP request, shared by every procedure in a batch. The
-	* subject reads the first procedure's opts; the tenant is resolved from each
-	* procedure's own opts in `scopeOf`, never through the shared `Request`.
-	*/
-	const bind = (opts) => {
-		const ctx = opts.ctx;
-		const hit = requestByCtx.get(ctx);
-		if (hit !== void 0) return hit;
-		const request = requestOf(opts.ctx) ?? new Request(`http://localhost/trpc/${opts.path}`, { method: "POST" });
-		requestByCtx.set(ctx, request);
-		if (!optsByRequest.has(request)) optsByRequest.set(request, opts);
-		return request;
-	};
-	const scopeOf = (opts) => tenantScope(options.tenant, opts);
-	const attach = (ctx, request) => {
-		requestByCtx.set(ctx, request);
-	};
+	const { kernel, bind, attach, scopeOf, connection, evaluate } = bindRpcKernel(policy, options, "trpc", (opts) => opts.ctx, (opts) => opts.path);
 	const permdock = () => (async (opts) => {
 		const request = bind(opts);
-		let instance;
-		try {
-			instance = await kernel.permdock(request, await scopeOf(opts));
-		} catch (error) {
-			const response = invalidSignatureResponse(error);
-			if (response !== void 0) return throwTrpcError(response);
-			throw error;
-		}
+		const instance = await attached(async () => kernel.permdock(request, await scopeOf(opts)));
+		if (!instance.ok) return throwTrpcError(instance.response);
 		const nextCtx = {
 			...opts.ctx,
-			permdock: instance
+			permdock: instance.permdock
 		};
 		attach(nextCtx, request);
 		return mapDownstream(await opts.next({ ctx: nextCtx }));
 	});
-	const connection = async (opts, connectionOptions) => kernel.connection(bind(opts), connectionOptions, await scopeOf(opts));
 	/** Wraps a subscription's iterable so revocation ends it and unreadable items drop. */
 	const guardSubscription = async (result, opts, permission, loadData, protectOptions) => {
 		if (result === null || typeof result !== "object" || result.ok !== true || !isAsyncIterable(result.data)) return result;
-		const conn = await connection(opts, compact({
-			permission,
-			data: loadData
-		}));
 		return {
 			...result,
-			data: guardIterable(result.data, conn, compact({
-				items: protectOptions?.items,
+			data: await guardStream(result.data, (connectionOptions) => connection(opts, connectionOptions), permission, loadData, protectOptions, {
 				unwrap: (item) => isTrackedEnvelope(item) ? item[1] : item,
 				onRevoked: trpcErrorFrom
-			}))
+			})
 		};
 	};
 	const protect = (permission, loadData, protectOptions) => (async (opts) => {
@@ -170,20 +90,17 @@ function createPermDock(policy, options) {
 				permdockData: guard.data
 			};
 			attach(nextCtx, request);
-			return guardSubscription(await mapDownstream(await opts.next({ ctx: nextCtx })), opts, permission, loadData === void 0 ? void 0 : () => loadData(opts), protectOptions);
+			return guardSubscription(await mapDownstream(await opts.next({ ctx: nextCtx })), opts, permission, loadData === void 0 ? void 0 : reloadAfter(guard.data, () => loadData(opts)), protectOptions);
 		}
 		return throwTrpcError(guard.response);
 	});
 	const permdockHandler = (request) => {
-		const opts = {
+		return evaluate(request, {
 			ctx: { req: request },
 			path: "permdock",
 			type: "unknown",
 			next: (nextOpts) => Promise.resolve(nextOpts ?? { ctx: { req: request } })
-		};
-		bind(opts);
-		const { POST, GET } = kernel.permdockHandler(() => scopeOf(opts));
-		return Promise.resolve(request.method === "GET" ? GET(request) : POST(request));
+		});
 	};
 	const kernelOpenApi = kernel.openapi;
 	return {

package/dist/types-BnIEz1sU.d.ts

@@ -0,0 +1,48 @@
+import { Ft as TokenVerifier, Tt as Snapshot, Yn as Decision } from "./policy-IB6yxpC3.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+import { ReactNode } from "react";
+//#region src/react/types.d.ts
+type PermDockProviderProps = ({
+  readonly snapshot: Snapshot | string;
+  readonly snapshotPromise?: never;
+} | {
+  /**
+   * An unawaited snapshot from a Server Component. Hooks never suspend on it: until it
+   * resolves they deny with `status: 'pending'`, then re-render. A rejection fails closed
+   * (`server-only`). Set `suspend` to suspend readers through `use()` instead.
+   */
+  readonly snapshotPromise: PromiseLike<Snapshot | string>;
+  readonly snapshot?: never;
+}) & {
+  /**
+   * With `snapshotPromise`: `true` suspends every hook to the nearest Suspense boundary until it
+   * resolves, and a rejection reaches the nearest error boundary. Defaults to `false`.
+   */
+  readonly suspend?: boolean;
+  /**
+   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer. `false` never
+   * fetches: those checks answer `denied` with reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  readonly tenant?: string;
+  readonly fetch?: typeof fetch;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly maxAge?: number;
+  readonly verifier?: TokenVerifier;
+  readonly children: ReactNode;
+};
+type ProtectedProps = {
+  readonly permission: Permission;
+  readonly data?: unknown;
+  readonly tenant?: string;
+  readonly pending?: ReactNode;
+  readonly fallback?: ReactNode | ((decision: Decision) => ReactNode);
+  readonly children: ReactNode | ((decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>) => ReactNode);
+};
+//#endregion
+export { ProtectedProps as n, PermDockProviderProps as t };

package/dist/{types-CxquUByI.d.ts → types-Bvc4oWT6.d.ts}

@@ -1,4 +1,4 @@
-import { d as Permission } from "./permissions-B4apnahQ.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
 //#region src/agent/types.d.ts
 type ToolBinding = {
   readonly permission: Permission;

package/dist/{sources-DOpW5Ila.d.ts → types-C97IskBw.d.ts}

@@ -1,5 +1,5 @@
-import { J as AuthEvent, ct as MembershipSource, mr as Principal } from "./policy-CInmNGkM.js";
-import { a as SupabaseManifestMembership } from "./manifest-DDQbC6K0.js";
+import { Nr as Principal, et as AuthEvent } from "./policy-IB6yxpC3.js";
+import { t as ClientNames } from "./clients-C7zLFuWT.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/supabase/claims.d.ts
 /** One entry of the `memberships` claim, as `schemas/supabase-claims-v1.json` defines it. */
@@ -27,6 +27,8 @@ type SupabaseMembershipClaim = {
   };
   readonly managedBy?: "idp";
   readonly entitlements?: readonly string[];
+  /** The instance or an ancestor is suspended: the permission keys the membership still grants. */
+  readonly keep?: readonly string[];
   /** Custom roles in compact form, read by the RLS helpers in `jwt` mode. */
   readonly grants?: Readonly<Record<string, unknown>>;
 };
@@ -96,16 +98,36 @@ type SupabasePrincipal = Principal & {
   readonly is_anonymous?: boolean;
 };
 type SupabaseInclude = "email" | "phone" | "is_anonymous";
+/**
+ * A column that holds a foreign key: the value is `column` of `through`,
+ * joined on `on`. A role reads its key from a roles table
+ * (`{ through: 'roles', on: { role_id: 'id' }, column: 'key' }`); a
+ * membership source's user can read its user id from a profile table
+ * (`{ through: 'contact_profiles', on: { contact_profile_id: 'id' }, column: 'user_id' }`).
+ */
+type RoleThrough = {
+  /** The referenced table; unqualified, it is in the schema of the table that references it. */
+  readonly through: string;
+  /** One entry: the referencing column to the column of `through` it references. */
+  readonly on: Readonly<Record<string, string>>;
+  /** The column of `through` that holds the value: the role key, or the user id. */
+  readonly column: string;
+};
 type SupabaseMembershipTable = {
   readonly table: string;
   readonly user: string;
-  readonly role: string;
+  /**
+   * The role key column, a reference to a roles table that holds the key, or
+   * several of them: the row holds every non-null key.
+   */
+  readonly role: string | RoleThrough | readonly (string | RoleThrough)[];
   /** Per scope name, the column holding that scope's id: the table's own scope and its ancestors. */
   readonly columns?: Readonly<Record<string, string>>;
   readonly tenant?: string;
   readonly team?: string;
   readonly id?: string;
   readonly expiresAt?: string;
+  readonly disabledAt?: string;
 };
 /** A table whose row says whether a user or a scope instance is active. A missing row counts as suspended. */
 type SupabaseActiveRow = {
@@ -118,11 +140,28 @@ type SupabaseActiveRow = {
   readonly status?: string;
   readonly active?: readonly string[];
 };
+/** A scope's active-row table, with the permissions its suspended instances keep. */
+type SupabaseSuspendedScope = SupabaseActiveRow & {
+  /**
+   * Permissions (references or keys) members of a suspended instance, and of
+   * every instance nested in it, still hold; such a membership carries them
+   * as `keep`.
+   */
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
+type SupabaseSuspendedMembership = {
+  readonly keep?: readonly (string | {
+    readonly key: string;
+  })[];
+};
 type SupabaseSuspension = {
   /** A suspended user holds no role and no membership. */
   readonly users?: SupabaseActiveRow;
-  /** Per scope name: a suspended instance voids its memberships and every membership nested under it. */
-  readonly scopes?: Readonly<Record<string, SupabaseActiveRow>>;
+  /** Per scope name: a suspended instance voids its memberships and every membership nested under it, except for `keep`. */
+  readonly scopes?: Readonly<Record<string, SupabaseSuspendedScope>>;
+  readonly memberships?: SupabaseSuspendedMembership;
 };
 type SupabaseMemberships = {
   /** The membership table of each named scope. */
@@ -147,10 +186,38 @@ type AuthorizeSqlOptions = {
    */
   readonly customRoles?: {
     readonly declared: readonly string[];
+    /** Stored allows may carry a level (`custom_role_permissions.level`). */
+    readonly levels?: true;
   };
   /** A suspended user, or a suspended instance of `scope` for a tenant request, answers `false`. */
   readonly suspension?: SupabaseSuspension;
 };
+/** A permission reference; `rls generate` reads only its `key`. */
+type SupabasePermissionRef = {
+  readonly key: string;
+};
+/**
+ * Private Realtime channels: topic patterns such as `org:{organization}:chat`,
+ * with one `{<scope>}` segment that holds a scope instance id.
+ */
+type SupabaseRealtime = {
+  readonly topics: Readonly<Record<string, {
+    /** Receive broadcast and presence: `select` on `realtime.messages`. */
+    readonly read: SupabasePermissionRef;
+    /** Send broadcast and track presence: `insert`. */
+    readonly write?: SupabasePermissionRef;
+  }>>;
+};
+/** Storage buckets whose object paths hold a scope instance id in folder `folder` (default 1). */
+type SupabaseStorage = {
+  readonly buckets: Readonly<Record<string, {
+    readonly scope: string;
+    readonly folder?: number;
+    readonly read?: SupabasePermissionRef;
+    readonly write?: SupabasePermissionRef;
+    readonly delete?: SupabasePermissionRef;
+  }>>;
+};
 type SupabaseRlsOptions = {
   readonly roleClaim?: string;
   readonly tenantClaim?: string;
@@ -158,6 +225,8 @@ type SupabaseRlsOptions = {
   readonly tenantType?: string;
   readonly memberships?: SupabaseMembershipTable | SupabaseMemberships;
   readonly suspension?: SupabaseSuspension;
+  readonly realtime?: SupabaseRealtime;
+  readonly storage?: SupabaseStorage;
 };
 type SupabaseRlsConfig = {
   readonly dialect: "supabase";
@@ -166,10 +235,12 @@ type SupabaseRlsConfig = {
   readonly tenantType?: string;
   readonly memberships?: SupabaseMemberships;
   readonly suspension?: SupabaseSuspension;
+  readonly realtime?: SupabaseRealtime;
+  readonly storage?: SupabaseStorage;
 };
 /**
  * The structural shape `subjectFromSupabaseSession` reads: a discriminant and the verified JWT claims.
- * Matches better-supabase's `AuthSession` and similar session objects without importing them.
+ * Matches any session object of that shape without importing its library.
  */
 type SupabaseSessionLike = {
   readonly kind: string;
@@ -184,8 +255,16 @@ type SupabaseSubjectOptions = {
   readonly declared?: readonly string[];
   /** Claim holding plan names per tenant id; the active tenant's entry becomes `principal.plans`. */
   readonly plans?: string;
+  /** Names for OAuth client ids: an `oauth-client` actor gets `client` set to the name of its id, which a policy delegation matches with `to: { kind: 'oauth-client', client }`. */
+  readonly clients?: ClientNames;
   /** `'deny'` maps a token with `is_anonymous: true` (`signInAnonymously()`) to the anonymous subject, as `rls.anonymousSignIns: 'deny'` does in RLS. */
   readonly anonymousSignIns?: "deny";
+  /**
+   * `true` once the caller checked the session against the Auth server for this request
+   * (`auth.getUser()` or an equivalent session check): a token with a `session_id` gets
+   * `subject.liveSession`, which `{ subject: { session: { live: true } } }` requires. Never read from claims.
+   */
+  readonly liveSession?: boolean;
   /** Audit hook: `membership-dropped` for a `memberships` entry that could not be read, `invalid-chain` for a malformed `act`. */
   readonly onAuth?: (event: AuthEvent) => void;
 };
@@ -224,124 +303,4 @@ type SupabaseDelegation = {
   readonly scopes: readonly string[];
 };
 //#endregion
-//#region src/supabase/sources.d.ts
-/**
- * Runs one parameterised statement: `pg`'s `client.query` (which resolves
- * `{ rows }`) and `postgres`'s `sql.unsafe` (which resolves the rows) both fit.
- */
-type SqlQuery = (text: string, values: readonly unknown[]) => Promise<readonly Record<string, unknown>[] | {
-  readonly rows: readonly Record<string, unknown>[];
-}>;
-type Common = {
-  readonly table: string;
-  /** Runs the lookups; without it the source only describes SQL (for `permdock supabase hook generate`). */
-  readonly query?: SqlQuery;
-  /** Drop suspended users and memberships under suspended instances, like `rls.suspension`. */
-  readonly suspension?: SupabaseSuspension;
-};
-type MembershipTableOptions = Common & {
-  /** Column names; `user`, `scope`, `id` and `role` default to `user_id`, `scope`, `scope_id`, `role`. */
-  readonly columns?: {
-    readonly user?: string;
-    readonly scope?: string;
-    readonly id?: string;
-    /** A `jsonb` column of ancestor ids keyed by scope name. */
-    readonly within?: string;
-    readonly role?: string;
-    readonly via?: string;
-    readonly expiresAt?: string;
-    /** The principal id that wrote the membership (`grantedBy`). */
-    readonly grantedBy?: string;
-    /** Free-text justification recorded on the membership (`reason`). */
-    readonly reason?: string;
-    /** A subgroup column filling `member.group`. */
-    readonly group?: string;
-    /** A text column; the value `idp` marks the row as owned by the identity provider. */
-    readonly managedBy?: string;
-    /** A `text[]` column of seats. */
-    readonly seats?: string;
-  };
-};
-type MembershipJunctionOptions = Common & {
-  /** The declared scope every row is a membership of. */
-  readonly scope: string;
-  /** Default `user_id`. */
-  readonly user?: string;
-  /** The column holding the scope instance id. Default `<scope>_id`. */
-  readonly id?: string;
-  /** Ancestor id columns keyed by scope name. */
-  readonly within?: Readonly<Record<string, string>>;
-  /** A role column, or fixed roles every row holds (a contact table with no role column). */
-  readonly roles: string | readonly string[];
-  /** The membership kind every row has (`contact`, `staff`, `partner`). */
-  readonly via?: string;
-  readonly expiresAt?: string;
-  /** The principal id that wrote the membership (`grantedBy`). */
-  readonly grantedBy?: string;
-  /** Free-text justification recorded on the membership (`reason`). */
-  readonly reason?: string;
-  /** A subgroup filling `member.group`: a fixed name every row has, or a column. */
-  readonly group?: string | {
-    readonly column: string;
-  };
-  /** `idp` when the identity provider owns every row, or a text column holding `idp` per row. */
-  readonly managedBy?: "idp" | {
-    readonly column: string;
-  };
-  /** A `text[]` column of seats. */
-  readonly seats?: string;
-};
-/** What `permdock supabase hook generate` compiles; the same SQL the source runs. */
-type MembershipSql = {
-  readonly table: string;
-  /** Columns of the table that decide a membership; triggers bump the authorization version on them. */
-  readonly user: string;
-  /** `<table>.<user>%type`: the PL/pgSQL type of the user column, for a variable `select` compares with. */
-  readonly userType: string;
-  /**
-   * The `select` of claim rows for one user, with every filter applied.
-   * `user` must have the column's type (a `userType` variable, or an untyped
-   * `$1` Postgres infers): the column is compared uncast so its index applies.
-   */
-  select(user: string): string;
-  /** The `select` of member rows for one scope instance (`$1` scope, `$2` id). */
-  list(): string;
-  /** A text column holding `idp` for rows the identity provider owns; `''` when every row is owned. */
-  readonly managed?: string;
-  /** Other tables the `select` reads (suspension tables). */
-  readonly reads: readonly string[];
-  /** Every column that decides who holds which membership: user, scope, id, `within`, role, `via` and expiry. */
-  readonly columns: readonly string[];
-  /** For a single-scope source: its scope and the scopes whose ids each row carries. */
-  readonly scope?: string;
-  readonly holds?: readonly string[];
-  /** The source's entry in the hook manifest's `memberships`. */
-  readonly manifest: SupabaseManifestMembership;
-};
-type SqlMembershipSource = MembershipSource & {
-  readonly sql: MembershipSql;
-};
-/**
- * Memberships from one table holding every scope: a row per user, scope,
- * instance and role (`user_id, scope, scope_id, role`), with optional
- * `within`, `via`, expiry, owner and seat columns. Rows of the same instance
- * merge into one membership.
- */
-declare function fromTable(options: MembershipTableOptions): SqlMembershipSource;
-/**
- * Memberships from a table of one scope (`customer_contacts`): every row is a
- * membership of `scope`, with roles from a column or fixed (`['contact']`), a
- * fixed `via`, and ancestor ids from `within` columns.
- */
-declare function fromJunction(options: MembershipJunctionOptions): SqlMembershipSource;
-declare const AUTHZ_VERSION_TABLE = "permdock_authz_version";
-/**
- * Reads the authorization version `permdock supabase hook generate` keeps in
- * `<schema>.permdock_authz_version`: pass it to `claimsFirst(sources, { version })`.
- */
-declare function authzVersion(options: {
-  readonly query: SqlQuery;
-  readonly schema?: string;
-}): NonNullable<MembershipSource["version"]>;
-//#endregion
-export { SupabaseActClaim as C, SupabaseMembershipClaim as D, SupabaseClaimsSchema as E, SupabasePermDockClaims as O, SupabaseSuspension as S, SupabaseClaimsOptions as T, SupabasePrincipal as _, SqlMembershipSource as a, SupabaseSessionLike as b, fromJunction as c, SupabaseActiveRow as d, SupabaseActor as f, SupabaseMembershipTable as g, SupabaseInclude as h, MembershipTableOptions as i, supabaseClaims as k, fromTable as l, SupabaseDelegation as m, MembershipJunctionOptions as n, SqlQuery as o, SupabaseActorResult as p, MembershipSql as r, authzVersion as s, AUTHZ_VERSION_TABLE as t, AuthorizeSqlOptions as u, SupabaseRlsConfig as v, SupabaseClaims as w, SupabaseSubjectOptions as x, SupabaseRlsOptions as y };
+export { SupabaseClaimsSchema as C, supabaseClaims as E, SupabaseClaimsOptions as S, SupabasePermDockClaims as T, SupabaseSuspendedMembership as _, SupabaseActorResult as a, SupabaseActClaim as b, SupabaseMembershipTable as c, SupabaseRealtime as d, SupabaseRlsConfig as f, SupabaseSubjectOptions as g, SupabaseStorage as h, SupabaseActor as i, SupabasePermissionRef as l, SupabaseSessionLike as m, RoleThrough as n, SupabaseDelegation as o, SupabaseRlsOptions as p, SupabaseActiveRow as r, SupabaseInclude as s, AuthorizeSqlOptions as t, SupabasePrincipal as u, SupabaseSuspendedScope as v, SupabaseMembershipClaim as w, SupabaseClaims as x, SupabaseSuspension as y };