@protobase/server 0.28.4 → 0.29.1

package/dist/auth/jwt.js

@@ -32,8 +32,8 @@ const jwtVerifier = (options) => {
 		})).payload;
 	};
 };
-/** Verifies `Authorization: Bearer <jwt>` against a JWKS; `sub` is the user id. Without the header, `MissingCredentials`. */
-const jwtAuthenticator = (options) => {
+/** Like `jwtAuthenticator`, and also returns the verified claims, for an authenticator that checks more of them. */
+const jwtSessions = (options) => {
 	const { rolesClaim = "roles", tenantClaim = "tenant" } = options;
 	const verify = jwtVerifier(options);
 	return async (request) => {
@@ -48,13 +48,21 @@ const jwtAuthenticator = (options) => {
 		const claimed = typeof tenant === "string" || typeof tenant === "number" ? tenant : void 0;
 		const tenantValue = options.tenant === void 0 ? claimed : typeof options.tenant === "function" ? await options.tenant() : options.tenant;
 		return {
-			user: {
-				id: sub,
-				roles: [.../* @__PURE__ */ new Set([...rolesOf(roles), ...extraRoles])]
-			},
-			...tenantValue !== void 0 && { tenant: tenantValue }
+			payload,
+			session: {
+				user: {
+					id: sub,
+					roles: [.../* @__PURE__ */ new Set([...rolesOf(roles), ...extraRoles])]
+				},
+				...tenantValue !== void 0 && { tenant: tenantValue }
+			}
 		};
 	};
 };
+/** Verifies `Authorization: Bearer <jwt>` against a JWKS; `sub` is the user id. Without the header, `MissingCredentials`. */
+const jwtAuthenticator = (options) => {
+	const sessions = jwtSessions(options);
+	return async (request) => (await sessions(request)).session;
+};
 //#endregion
-export { jwtAuthenticator, jwtVerifier };
+export { jwtAuthenticator, jwtSessions, jwtVerifier };

package/dist/better-auth/authenticator.d.ts

@@ -28,7 +28,10 @@ export declare const betterAuthTokens: (options: Pick<BetterAuthAuthenticatorOpt
  * Verifies the bearer JWT that Better Auth's jwt plugin issues. `sub` is the user id, the `role` claim (a comma
  * separated string from the admin plugin) becomes `roles`. With organizations, the `org` claim is the tenant and the
  * organization, and the membership's `app_roles` are added to the global roles; `user`, which stands for no global
- * role, is left out. With `apps`, the tokens of those apps are admitted too, with the roles each gives its users here.
+ * role, is left out. With `auth`, every request also reads the store to check that the token still stands
+ * (`checkTokenStanding`), so a ban, a lowered role, a deleted user or a sign-out ends it at once; with `jwksUrl` alone
+ * a token works until it expires. With `apps`, the tokens of those apps are admitted too, with the roles each gives
+ * its users here.
  */
 export declare const betterAuthAuthenticator: (options: BetterAuthAuthenticatorOptions) => Authenticator;
 //#endregion

package/dist/better-auth/authenticator.js

@@ -1,7 +1,8 @@
-import { jwtAuthenticator } from "../auth/jwt.js";
+import { jwtSessions } from "../auth/jwt.js";
 import { noGlobalRole } from "./organizations/role-definitions.js";
 import { cachedKeys } from "./jwks-cache.js";
 import { withTrustedApps } from "./app-tokens.js";
+import { checkTokenStanding, tokenClaims } from "./token-standing.js";
 //#region src/better-auth/authenticator.ts
 /** How the tokens of this Better Auth instance verify: its key set, and its issuer as both issuer and audience. */
 const betterAuthTokens = (options) => {
@@ -18,13 +19,16 @@ const betterAuthTokens = (options) => {
 * Verifies the bearer JWT that Better Auth's jwt plugin issues. `sub` is the user id, the `role` claim (a comma
 * separated string from the admin plugin) becomes `roles`. With organizations, the `org` claim is the tenant and the
 * organization, and the membership's `app_roles` are added to the global roles; `user`, which stands for no global
-* role, is left out. With `apps`, the tokens of those apps are admitted too, with the roles each gives its users here.
+* role, is left out. With `auth`, every request also reads the store to check that the token still stands
+* (`checkTokenStanding`), so a ban, a lowered role, a deleted user or a sign-out ends it at once; with `jwksUrl` alone
+* a token works until it expires. With `apps`, the tokens of those apps are admitted too, with the roles each gives
+* its users here.
 */
 const betterAuthAuthenticator = (options) => {
 	const tokens = betterAuthTokens(options);
 	const { issuer } = tokens;
 	const organizations = options.organizations ?? Boolean(options.auth?.organizations);
-	const verify = jwtAuthenticator({
+	const sessions = jwtSessions({
 		...tokens,
 		rolesClaim: "role",
 		...organizations && {
@@ -33,6 +37,12 @@ const betterAuthAuthenticator = (options) => {
 		},
 		...options.tenant !== void 0 && { tenant: options.tenant }
 	});
+	const { auth } = options;
+	const verify = async (request) => {
+		const { payload, session } = await sessions(request);
+		if (auth) await checkTokenStanding(await auth.$context, tokenClaims(payload, session.user.roles, organizations ? session.tenant : void 0), organizations);
+		return session;
+	};
 	return withTrustedApps(!organizations ? verify : async (request) => {
 		const session = await verify(request);
 		const user = {

package/dist/better-auth/create-auth.d.ts

@@ -1165,24 +1165,28 @@ export declare const createAuth: (options: CreateAuthOptions) => import("better-
         }) => Promise<{
           role: any;
           email: string;
+          sid: string;
         } | {
           org?: undefined;
           org_role?: undefined;
           app_roles?: undefined;
           role: any;
           email: string;
+          sid: string;
         } | {
           org: string;
           org_role: OrganizationRole;
           app_roles: string[];
           role: any;
           email: string;
+          sid: string;
         } | {
           org: string;
           org_role?: undefined;
           app_roles?: undefined;
           role: any;
           email: string;
+          sid: string;
         }>;
       };
       disableSettingJwtHeader: true;

package/dist/better-auth/create-auth.js

@@ -94,6 +94,7 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 				};
 				return {
 					email: user.email,
+					sid: session.id,
 					...narrowClaims(claims, [activeRole, user.lastRole], Boolean(organizations))
 				};
 			}

package/dist/better-auth/token-standing.js

@@ -0,0 +1,55 @@
+import { unauthorized } from "../problem.js";
+import { noGlobalRole } from "./organizations/role-definitions.js";
+import { parseRoles } from "./parse-roles.js";
+import { effectiveRoles, globalRoles } from "./organizations/app-roles.js";
+import { findMember, findOrganization } from "./organizations/store.js";
+//#region src/better-auth/token-standing.ts
+const tokenClaims = (payload, roles, tenant) => ({
+	userId: payload.sub,
+	...typeof payload.sid === "string" && { sessionId: payload.sid },
+	roles: roles.filter((role) => role !== noGlobalRole),
+	...typeof tenant === "string" && { organizationId: tenant }
+});
+const revoked = () => unauthorized("The bearer token was revoked: get a new one");
+const bannedNow = (user, now) => Boolean(user.banned) && (!user.banExpires || user.banExpires > now);
+const heldWhere = async ({ adapter }, user, organizations, organizationId) => {
+	if (!organizations) return parseRoles(user.role);
+	const global = globalRoles(user.role);
+	if (!organizationId) return global;
+	const member = await findMember(adapter, {
+		organizationId,
+		userId: user.id
+	});
+	if (member) return effectiveRoles(global, member.appRoles);
+	return global.length > 0 && await findOrganization(adapter, organizationId) !== null ? global : void 0;
+};
+/**
+* Whether a token still stands, read from the store on every request: its user exists and is not banned, its session
+* is not signed out or expired, and each role it carries is one the user still holds there. A token that fails is a
+* 401, so the client asks its session for a new one, which carries the roles as they are now or is refused.
+*/
+const checkTokenStanding = async (context, claims, organizations, now = /* @__PURE__ */ new Date()) => {
+	const { adapter } = context;
+	if (claims.sessionId !== void 0) {
+		const session = await adapter.findOne({
+			model: "session",
+			where: [{
+				field: "id",
+				value: claims.sessionId
+			}]
+		});
+		if (!session || session.userId !== claims.userId || session.expiresAt <= now) throw revoked();
+	}
+	const user = await adapter.findOne({
+		model: "user",
+		where: [{
+			field: "id",
+			value: claims.userId
+		}]
+	});
+	if (!user || bannedNow(user, now)) throw revoked();
+	const held = await heldWhere(context, user, organizations, claims.organizationId);
+	if (!held || claims.roles.some((role) => !held.includes(role))) throw revoked();
+};
+//#endregion
+export { checkTokenStanding, tokenClaims };

package/dist/create-admin.js

@@ -270,6 +270,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		basePath: `${systemPath}/functions`,
 		functions: apiFunctions,
 		authenticate,
+		access: deps.accessOptions,
 		db,
 		records: (session) => callerRecords(deps, session),
 		onError,

package/dist/functions/define-function.d.ts

@@ -1,5 +1,6 @@
 import { Session } from "../types.js";
 import { FunctionRecords } from "./records.js";
+import { Capability } from "@protobase/schema";
 import { Db } from "@protobase/query";
 //#region src/functions/define-function.d.ts
 /** What every function gets: its name and the raw database. */
@@ -47,6 +48,11 @@ export type ProtectedFunctionOptions = SharedOptions & {
   public?: false;
   /** The caller needs one of these roles, otherwise the call is a 403 problem. */
   roles?: string[];
+  /**
+   * The caller's roles must grant all of this capability (`roles.holds`), such as `vms.update`, otherwise the call is a
+   * 403 problem. Needs the app's `roles`; not together with `roles` here.
+   */
+  capability?: Capability;
 };
 export type FunctionOptions = PublicFunctionOptions | ProtectedFunctionOptions;
 /** A function as `createAdmin` serves it: its options and what answers its requests. */
@@ -63,7 +69,8 @@ export type ApiFunction = {
 export type FunctionSource = ApiFunction | FunctionHandler | FunctionApp;
 /**
  * A function of your own, served at `/api/functions/<name>`. Without options it needs a signed-in caller, through the
- * app's `authenticate`; `{ public: true }` opens it to anyone, as for a webhook.
+ * app's `authenticate`, and with the app's `roles` one whose roles hold `*`; `{ roles }` or `{ capability }` opens it
+ * to more, `{ public: true }` to anyone, as for a webhook.
  */
 export declare function defineFunction(handler: FunctionHandler | FunctionApp): ApiFunction;
 export declare function defineFunction(options: PublicFunctionOptions, handler: PublicFunctionHandler | FunctionApp<PublicFunctionContext>): ApiFunction;

package/dist/functions/function-gate.js

@@ -0,0 +1,36 @@
+import { forbidden } from "../problem.js";
+import { parseCapability } from "@protobase/schema/internal";
+//#region src/functions/function-gate.ts
+const open = () => true;
+const holdsOf = (name, access) => {
+	const holds = access.roles?.holds;
+	if (!holds) throw new Error(`The function "${name}" is gated by the app's roles, but they have no holds(user, capability): define them with defineRoles`);
+	return holds;
+};
+/**
+* Who may call a function, checked at startup: anyone, for a public one; one of its `roles`, or a caller holding all of its
+* `capability`. Without either, an app with roles lets in only callers holding `*`, unless `defaultAccess` is `allow`;
+* an app without roles lets in every signed-in caller.
+*/
+const functionGate = (name, options, access) => {
+	if (options.public) return open;
+	const { roles, capability } = options;
+	if (roles && capability) throw new Error(`The function "${name}" has both roles and a capability: give one`);
+	if (roles) return (session) => roles.some((role) => session.user.roles.includes(role));
+	if (capability) {
+		if (!access.roles) throw new Error(`The function "${name}" needs the capability "${capability}", but the app defines no roles`);
+		parseCapability(capability);
+		const holds = holdsOf(name, access);
+		return (session) => holds(session.user, capability);
+	}
+	if (!access.roles || access.defaultAccess === "allow") return open;
+	const holds = holdsOf(name, access);
+	return (session) => holds(session.user, "*");
+};
+/** Throws the 403 problem for a caller the gate refuses. */
+const requireGate = (name, gate, session) => {
+	if (gate(session)) return;
+	throw forbidden("function-forbidden", `You may not call the function "${name}"`);
+};
+//#endregion
+export { functionGate, requireGate };

package/dist/functions/routes.js

@@ -1,6 +1,7 @@
-import { forbidden, notFound } from "../problem.js";
+import { notFound } from "../problem.js";
 import { invokeFunction } from "./define-function.js";
 import { runInBackground } from "../background-work.js";
+import { functionGate, requireGate } from "./function-gate.js";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 //#region src/functions/routes.ts
@@ -9,17 +10,13 @@ const relativeRequest = (request, prefix) => {
 	url.pathname = url.pathname.slice(prefix.length) || "/";
 	return new Request(url, request);
 };
-const requireRoles = (name, session, roles) => {
-	if (!roles || roles.some((role) => session.user.roles.includes(role))) return;
-	throw forbidden("function-forbidden", `You may not call the function "${name}"`);
-};
 /**
 * Every function at `<basePath>/<name>` and below, any method. A protected function authenticates the request first, so
-* a call without a valid token is the authenticator's 401 problem; a public one gets the caller only when it asks. Each
+* a call without a valid token is the authenticator's 401 problem, and one its gate refuses a 403; a public one gets the caller only when it asks. Each
 * call runs as background work, so calls that hold the database for long leave a connection to page requests. Once a
 * call ends, failed or not, `wake` runs, so what it wrote reaches open pages without waiting for the dispatcher's poll.
 */
-const functionRoutes = ({ basePath, functions, authenticate, db, records, onError, wake }) => {
+const functionRoutes = ({ basePath, functions, authenticate, access, db, records, onError, wake }) => {
 	const app = new Hono().basePath(basePath);
 	app.onError(onError);
 	const callerOf = async (request) => {
@@ -33,6 +30,7 @@ const functionRoutes = ({ basePath, functions, authenticate, db, records, onErro
 	for (const [name, fn] of Object.entries(functions)) {
 		const prefix = `${basePath}/${name}`;
 		const { options } = fn;
+		const gate = functionGate(name, options, access);
 		if (options.cors) app.use(`/${name}/*`, cors(options.cors));
 		app.all(`/${name}/*`, (c) => runInBackground(() => call(async () => {
 			const request = relativeRequest(c.req.raw, prefix);
@@ -45,7 +43,7 @@ const functionRoutes = ({ basePath, functions, authenticate, db, records, onErro
 				});
 			}
 			const caller = await callerOf(c.req.raw);
-			requireRoles(name, caller.session, options.roles);
+			requireGate(name, gate, caller.session);
 			const context = {
 				name,
 				db,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.28.4",
+  "version": "0.29.1",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,9 +32,9 @@
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
     "@better-auth/sso": "^1.7.7",
-    "@protobase/layout": "0.28.4",
-    "@protobase/query": "0.28.4",
-    "@protobase/schema": "0.28.4",
+    "@protobase/layout": "0.29.1",
+    "@protobase/query": "0.29.1",
+    "@protobase/schema": "0.29.1",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",