@protobase/server 0.28.4 → 0.29.0

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.0",
   "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.0",
+    "@protobase/query": "0.29.0",
+    "@protobase/schema": "0.29.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",