@protobase/server 0.50.0 → 0.51.0

package/dist/assistant/delete-record-tool.js

@@ -1,7 +1,14 @@
 import { defineTool } from "./tools.js";
 import { keyOf, keyParameter, refused, resourceOf } from "./record-tool-args.js";
+import { deleteApproval } from "./write-prompts.js";
+import { approvalTexts, recordBefore } from "./record-before.js";
 import { onlyNote, outside, resourceParameterFor } from "./write-tool-limits.js";
 //#region src/assistant/delete-record-tool.ts
+/**
+* `delete_record`: deleting one record as the caller, through the REST API's delete path (its access rules, ETag check,
+* write hooks and soft delete), after the user approves it. Before asking it only reads: the resource's config and the
+* record the approval names, since MCP runs it again from the start with the user's answer.
+*/
 const parameterNames = [
 	"resource",
 	"key",
@@ -16,15 +23,6 @@ const deleteKeyOf = (value) => {
 };
 const etagOf = (value) => typeof value === "string" && /^"[\x21\x23-\x2b\x2d-\x7e]+"$/.test(value) ? value : void 0;
 const usage = "Pass only the resource, key and etag as { \"resource\": \"<name>\", \"key\": \"<key>\", \"etag\": \"<the etag get_record gave>\" }; nothing was deleted.";
-const approvalOf = (resource, shownKey, softDelete) => ({
-	title: softDelete ? `Delete this ${resource} record? It can be restored: the record is kept, marked deleted.` : `Delete this ${resource} record for good? This cannot be undone: the record is removed.`,
-	fields: [{
-		label: "Key",
-		value: shownKey
-	}],
-	tone: softDelete ? "warning" : "danger",
-	approveLabel: softDelete ? "Delete" : "Delete for good"
-});
 /** Deletes one record by its key and ETag once the user approves it, under the caller's access rules. */
 const deleteRecordTool = (input = {}) => defineTool({
 	name: "delete_record",
@@ -60,8 +58,10 @@ const deleteRecordTool = (input = {}) => defineTool({
 		if (refusal) return refusal;
 		const softDelete = await context.records.softDeleteField(resource).then((field) => ({ field }), refused);
 		if (typeof softDelete === "string") return softDelete;
-		const shownKey = Array.isArray(key) ? key.join(",") : String(key);
-		const answer = await context.approve(approvalOf(resource, shownKey, softDelete.field));
+		const before = await recordBefore(context, resource, key, etag);
+		if (typeof before === "string") return before;
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(deleteApproval(text, described, key, before?.record ?? {}, softDelete.field !== void 0));
 		if (answer !== "approved") return `The user did not approve this delete (${answer}); nothing was deleted.`;
 		const deleted = () => JSON.stringify({
 			deleted: true,

package/dist/assistant/record-before.js

@@ -0,0 +1,20 @@
+import { HttpProblem, preconditionFailed } from "../problem.js";
+import { ifMatchSatisfied } from "../etag.js";
+import { refused } from "./record-tool-args.js";
+import { writeText } from "./write-messages.js";
+import { describedResource } from "./write-prompts.js";
+//#region src/assistant/record-before.ts
+const hidden = (error) => error instanceof HttpProblem && (error.status === 403 || error.status === 404);
+/**
+* The record as the caller reads it now, for what an approval names and shows before a write: undefined when they may
+* not read it. A record changed since `etag` is refused before asking, as the write would refuse it after the user
+* approved; so is any other refusal of the read, as the model's to read.
+*/
+const recordBefore = (context, resource, key, etag) => context.records.get(resource, key).then((current) => etag && !ifMatchSatisfied(etag, current.etag) ? refused(preconditionFailed("The record changed since it was read; fetch it again")) : current, (error) => hidden(error) ? void 0 : refused(error));
+/** What an approval is written with: the texts of the user's language, and the resource as the caller may read it. */
+const approvalTexts = async (context, resource) => ({
+	text: writeText(context.locale ?? "en"),
+	described: describedResource(await context.resources(), resource)
+});
+//#endregion
+export { approvalTexts, recordBefore };

package/dist/assistant/tools.d.ts

@@ -2,6 +2,7 @@ import { Session } from "../types.js";
 import { ToolRecords } from "./records.js";
 import { Conversation } from "./conversations.js";
 import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
+import { Locale } from "@protobase/schema/internal";
 import { AssistantPart, ResourceModel, ViewModel } from "@protobase/schema";
 //#region src/assistant/tools.d.ts
 /** The resources a caller may read, each restricted to their fields, with their views. */
@@ -11,6 +12,8 @@ export type ReadableResources = {
 };
 export type ToolContext = {
   session: Session;
+  /** The language the user reads, for the texts a tool shows them such as its approvals; English when absent. */
+  locale?: Locale;
   /** The dock's conversation; absent over MCP. */
   conversation?: Conversation;
   /** Adds a part, such as a table of results, to the assistant message the turn is writing. */

package/dist/assistant/write-messages.js

@@ -0,0 +1,41 @@
+import { defineMessages } from "../locale/messages.js";
+//#region src/assistant/write-messages.ts
+/** The texts of the approvals the write tools ask for, which the user reads in their client. */
+const writeText = defineMessages({
+	en: {
+		createTitle: (resource, title) => `Create ${resource}${title === void 0 ? "" : ` "${title}"`}?`,
+		updateTitle: (record) => `Update ${record}?`,
+		deleteTitle: (record) => `Delete ${record}?`,
+		create: "Create",
+		update: "Update",
+		delete: "Delete",
+		deleteForGood: "Delete for good",
+		reject: "Cancel",
+		noChanges: "No field changes.",
+		restorable: "It can be restored: the record is kept, marked deleted.",
+		permanent: "This cannot be undone: the record is removed for good.",
+		empty: "empty",
+		hidden: "hidden",
+		yes: "Yes",
+		no: "No"
+	},
+	nl: {
+		createTitle: (resource, title) => `${resource}${title === void 0 ? "" : ` "${title}"`} aanmaken?`,
+		updateTitle: (record) => `${record} bijwerken?`,
+		deleteTitle: (record) => `${record} verwijderen?`,
+		create: "Aanmaken",
+		update: "Bijwerken",
+		delete: "Verwijderen",
+		deleteForGood: "Definitief verwijderen",
+		reject: "Annuleren",
+		noChanges: "Er verandert geen veld.",
+		restorable: "Het kan worden teruggezet: het record blijft bewaard, gemarkeerd als verwijderd.",
+		permanent: "Dit kan niet ongedaan worden gemaakt: het record wordt definitief verwijderd.",
+		empty: "leeg",
+		hidden: "verborgen",
+		yes: "Ja",
+		no: "Nee"
+	}
+});
+//#endregion
+export { writeText };

package/dist/assistant/write-prompts.js

@@ -0,0 +1,79 @@
+import { humanize, recordTitle } from "@protobase/schema/internal";
+import { enumLabel } from "@protobase/schema";
+//#region src/assistant/write-prompts.ts
+const describedResource = (readable, name) => ({
+	name,
+	model: readable.models.find((model) => model.name === name),
+	view: readable.views.find((view) => view.resource === name)
+});
+const hiddenCharacters = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+const longest = 200;
+/** `text` on one line with nothing hidden in it, cut at 200 characters. */
+const shown = (text) => {
+	const line = text.replace(hiddenCharacters, " ");
+	return line.length > longest ? `${line.slice(0, 199)}…` : line;
+};
+const resourceLabel = ({ name, view }) => shown(view?.names?.singular ?? humanize(name));
+const fieldLabel = ({ view }, name) => shown(view?.fields[name]?.label ?? humanize(name));
+const shownValue = (text, described, name, value) => {
+	const field = described.model?.fields[name];
+	if (field?.sensitive) return text.hidden;
+	if (value === null || value === void 0) return text.empty;
+	if (typeof value === "boolean") return value ? text.yes : text.no;
+	if (field?.type === "enum" && typeof value === "string") return shown(enumLabel(value, described.view?.fields[name]?.valueLabels));
+	if (typeof value === "string") return shown(value);
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	return shown(JSON.stringify(value));
+};
+/** `Task #42 "Fix the sign-in lockout"`: the resource's label, the record's key, and its title when it has one apart from the key. */
+const recordName = (described, key, record) => {
+	const shownKey = shown(Array.isArray(key) ? key.join(",") : String(key));
+	const title = described.model ? shown(recordTitle(described.model, described.view, record, shownKey)) : shownKey;
+	return `${resourceLabel(described)} #${shownKey}${title === shownKey ? "" : ` "${title}"`}`;
+};
+const titleOfNew = (described, data) => {
+	if (!described.model) return void 0;
+	const title = shown(recordTitle(described.model, described.view, data, ""));
+	return title === "" ? void 0 : title;
+};
+const same = (before, after) => JSON.stringify(before ?? null) === JSON.stringify(after ?? null);
+/** `Create Task "Fix the sign-in lockout"?`, with each field the new record is given by its label. */
+const createApproval = (text, described, data) => ({
+	title: text.createTitle(resourceLabel(described), titleOfNew(described, data)),
+	fields: Object.entries(data).map(([name, value]) => ({
+		label: fieldLabel(described, name),
+		value: shownValue(text, described, name, value)
+	})),
+	approveLabel: text.create,
+	rejectLabel: text.reject
+});
+/**
+* `Update Task #42 "Fix the sign-in lockout"?`, with each field that changes as `In flight -> Done`. A field the
+* caller cannot read before, such as a sensitive one, shows its new value alone.
+*/
+const updateApproval = (text, described, key, current, data) => {
+	const fields = Object.entries(data).filter(([name, value]) => !Object.hasOwn(current, name) || !same(current[name], value)).map(([name, value]) => {
+		const after = shownValue(text, described, name, value);
+		const before = Object.hasOwn(current, name) ? `${shownValue(text, described, name, current[name])} -> ` : "";
+		return {
+			label: fieldLabel(described, name),
+			value: `${before}${after}`
+		};
+	});
+	return {
+		title: text.updateTitle(recordName(described, key, current)),
+		...fields.length > 0 ? { fields } : { body: text.noChanges },
+		approveLabel: text.update,
+		rejectLabel: text.reject
+	};
+};
+/** `Delete Task #42 "Fix the sign-in lockout"?`, saying whether it can be restored (a soft delete) or is gone for good. */
+const deleteApproval = (text, described, key, current, restorable) => ({
+	title: text.deleteTitle(recordName(described, key, current)),
+	body: restorable ? text.restorable : text.permanent,
+	tone: restorable ? "warning" : "danger",
+	approveLabel: restorable ? text.delete : text.deleteForGood,
+	rejectLabel: text.reject
+});
+//#endregion
+export { createApproval, deleteApproval, describedResource, updateApproval };

package/dist/assistant/write-record-tools.js

@@ -1,5 +1,7 @@
 import { defineTool } from "./tools.js";
 import { keyOf, keyParameter, refused, resourceOf } from "./record-tool-args.js";
+import { createApproval, updateApproval } from "./write-prompts.js";
+import { approvalTexts, recordBefore } from "./record-before.js";
 import { forbiddenText, notApproved, onlyNote, outside, resourceParameterFor } from "./write-tool-limits.js";
 import { deleteRecordTool } from "./delete-record-tool.js";
 //#region src/assistant/write-record-tools.ts
@@ -32,11 +34,8 @@ const createRecordTool = (input = {}) => defineTool({
 		if (!resource || !data) return "Pass the resource and data as { \"resource\": \"<name>\", \"data\": { \"<field>\": <value> } }.";
 		const refusal = outside(input, resource);
 		if (refusal) return refusal;
-		const answer = await context.approve({
-			title: `Create a record in ${resource}?`,
-			code: JSON.stringify(data, null, 2),
-			approveLabel: "Create"
-		});
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(createApproval(text, described, data));
 		if (answer !== "approved") return notApproved(answer);
 		return context.records.create(resource, data).then((record) => JSON.stringify(record), refused);
 	}
@@ -76,14 +75,12 @@ const updateRecordTool = (input = {}) => defineTool({
 		const softDelete = await context.records.softDeleteField(resource).then((field) => ({ field }), refused);
 		if (typeof softDelete === "string") return softDelete;
 		if (softDelete.field && Object.hasOwn(data, softDelete.field)) return forbiddenText(`update_record does not set ${softDelete.field}, which deleting sets; delete with delete_record. Nothing was written.`);
-		const shownKey = Array.isArray(key) ? key.join(",") : String(key);
-		const answer = await context.approve({
-			title: `Update ${resource} ${shownKey}?`,
-			code: JSON.stringify(data, null, 2),
-			approveLabel: "Update"
-		});
-		if (answer !== "approved") return notApproved(answer);
 		const etag = typeof args.etag === "string" && args.etag ? args.etag : void 0;
+		const before = await recordBefore(context, resource, key, etag);
+		if (typeof before === "string") return before;
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(updateApproval(text, described, key, before?.record ?? {}, data));
+		if (answer !== "approved") return notApproved(answer);
 		return context.records.update(resource, key, data, { etag }).then((record) => JSON.stringify(record), refused);
 	}
 });

package/dist/create-admin.js

@@ -80,6 +80,7 @@ import { functionRoutes } from "./functions/routes.js";
 import { supabaseFunctionRoutes } from "./functions/supabase-routes.js";
 import { upgradeAuthenticator } from "./functions/upgrade-caller.js";
 import { localeSetting } from "./locale/locale-option.js";
+import { requestLocale } from "./locale/request-locale.js";
 import { mapSettings } from "./maps/map-settings.js";
 import { pluginOptions, pluginsBeforeSignIn } from "./plugins/plugin-settings.js";
 import { runtimeUrl } from "./runtime/runtime-settings.js";
@@ -329,17 +330,20 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			writes
 		});
 		const approvals = mcpApprovals();
-		const server = (session) => mcpServer({
-			info: {
-				name: appName,
-				version: "1.0.0"
-			},
-			tools: tools(session),
-			context: mcpToolContext(deps, meta, session),
-			report,
-			rolesWithoutApproval: rolesWithoutApproval(writes),
-			approvals
-		});
+		const server = (session, request) => {
+			const context = mcpToolContext(deps, meta, session, request ? requestLocale(locale, request) : locale);
+			return mcpServer({
+				info: {
+					name: appName,
+					version: "1.0.0"
+				},
+				tools: tools(session),
+				context,
+				report,
+				rolesWithoutApproval: rolesWithoutApproval(writes),
+				approvals
+			});
+		};
 		mcpRoutes(app, {
 			path: auth.mcp.path,
 			handler: mcpHandler({

package/dist/locale/messages.js

@@ -0,0 +1,8 @@
+//#region src/locale/messages.ts
+/**
+* An area's built-in texts in every language the screens come in: the lookup gives those of one locale, as the server
+* has no single active one. Dutch must translate every English text, which the types check.
+*/
+const defineMessages = (catalogue) => (locale) => catalogue[locale];
+//#endregion
+export { defineMessages };

package/dist/locale/request-locale.js

@@ -0,0 +1,14 @@
+import { pickLocale } from "@protobase/schema/internal";
+//#region src/locale/request-locale.ts
+const acceptedTags = (header) => header.split(",").map((entry) => {
+	const [tag = "", ...params] = entry.trim().split(";");
+	const weight = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+	return {
+		tag: tag.trim(),
+		q: weight ? Number(weight.slice(2)) : 1
+	};
+}).filter(({ tag, q }) => tag !== "" && tag !== "*" && q > 0).toSorted((a, b) => b.q - a.q).map(({ tag }) => tag);
+/** The language a request's user reads: the app's (`options.locale`) when it sets one, else their `Accept-Language`'s. */
+const requestLocale = (appLocale, request) => appLocale ?? pickLocale(acceptedTags(request.headers.get("accept-language") ?? ""));
+//#endregion
+export { requestLocale };

package/dist/mcp/mcp-approval.js

@@ -1,3 +1,4 @@
+import { defineMessages } from "../locale/messages.js";
 import { inputRequired, inputResponse } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-approval.ts
 /** Thrown by `approve` over MCP when the request carries no answer yet: the server then asks the client for one. */
@@ -41,20 +42,30 @@ const messageOf = (request) => [
 	request.fields?.map(({ label, value }) => `${label}: ${value}`).join("\n"),
 	request.code
 ].filter(Boolean).join("\n\n");
-const cannotAsk = {
+const text = defineMessages({
+	en: {
+		cannotAsk: "This client cannot ask you to approve a change, so nothing was written; use a client that supports MCP elicitation.",
+		approve: "Approve"
+	},
+	nl: {
+		cannotAsk: "Deze client kan je niet vragen een wijziging goed te keuren, dus er is niets opgeslagen; gebruik een client die MCP-elicitation ondersteunt.",
+		approve: "Goedkeuren"
+	}
+});
+const cannotAsk = (locale) => ({
 	content: [{
 		type: "text",
-		text: "This client cannot ask you to approve a change, so nothing was written; use a client that supports MCP elicitation."
+		text: text(locale).cannotAsk
 	}],
 	isError: true
-};
+});
 /**
 * The answer to a call whose tool asked for approval: a form asking the user to approve `request` when the client can
-* show one, filed under the nonce of the state `ask` mints for the call, else a refusal. A 2025-protocol request
-* declares no capabilities per request, so it is always refused.
+* show one, filed under the nonce of the state `ask` mints for the call, else a refusal in `locale`. A 2025-protocol
+* request declares no capabilities per request, so it is always refused.
 */
-const approvalAsked = async (request, capabilities, ask) => {
-	if (!asksForms(capabilities)) return cannotAsk;
+const approvalAsked = async (request, capabilities, ask, locale = "en") => {
+	if (!asksForms(capabilities)) return cannotAsk(locale);
 	const { state, nonce } = await ask();
 	return inputRequired({
 		inputRequests: { [approvalKey(nonce)]: inputRequired.elicit({
@@ -63,7 +74,7 @@ const approvalAsked = async (request, capabilities, ask) => {
 				type: "object",
 				properties: { approve: {
 					type: "boolean",
-					title: request.approveLabel ?? "Approve"
+					title: request.approveLabel ?? text(locale).approve
 				} },
 				required: ["approve"]
 			}

package/dist/mcp/mcp-context.d.ts

@@ -2,10 +2,12 @@ import { Session } from "../types.js";
 import { Deps } from "../deps.js";
 import { ToolContext } from "../assistant/tools.js";
 import { Meta } from "../meta.js";
+import { Locale } from "@protobase/schema/internal";
 //#region src/mcp/mcp-context.d.ts
 /**
- * What tools get over MCP for `session`: its records and the resources it may read, under its access rules. Nothing
- * shows beside a tool's result, and `mcpServer` gives each call its own `approve`.
+ * What tools get over MCP for `session`: its records and the resources it may read, under its access rules, and
+ * `locale`, the language its approvals are asked in. Nothing shows beside a tool's result, and `mcpServer` gives each
+ * call its own `approve`.
  */
-export declare const mcpToolContext: (deps: Deps, meta: Pick<Meta, "forCaller">, session: Session) => Omit<ToolContext, "approve">;
+export declare const mcpToolContext: (deps: Deps, meta: Pick<Meta, "forCaller">, session: Session, locale?: Locale) => Omit<ToolContext, "approve">;
 //#endregion

package/dist/mcp/mcp-context.js

@@ -2,11 +2,13 @@ import { assistantRecords } from "../assistant/records.js";
 import { readableResources } from "../assistant/readable-resources.js";
 //#region src/mcp/mcp-context.ts
 /**
-* What tools get over MCP for `session`: its records and the resources it may read, under its access rules. Nothing
-* shows beside a tool's result, and `mcpServer` gives each call its own `approve`.
+* What tools get over MCP for `session`: its records and the resources it may read, under its access rules, and
+* `locale`, the language its approvals are asked in. Nothing shows beside a tool's result, and `mcpServer` gives each
+* call its own `approve`.
 */
-const mcpToolContext = (deps, meta, session) => ({
+const mcpToolContext = (deps, meta, session, locale) => ({
 	session,
+	...locale && { locale },
 	records: assistantRecords(deps, session),
 	resources: () => readableResources(meta, session),
 	show: () => {}

package/dist/mcp/mcp-handler.d.ts

@@ -3,8 +3,11 @@ import { McpGateInput } from "./mcp-gate.js";
 import { McpServer } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-handler.d.ts
 export type McpHandlerInput = McpGateInput & {
-  /** Builds the server for the caller of one request, such as `mcpServer(...)` with tools of your own registered on it. */
-  server: (session: Session) => McpServer | Promise<McpServer>;
+  /**
+   * Builds the server for the caller of one request, such as `mcpServer(...)` with tools of your own registered on it;
+   * `request` is the HTTP request it serves, such as for the language its user reads.
+   */
+  server: (session: Session, request: Request | undefined) => McpServer | Promise<McpServer>;
 };
 /**
  * The MCP endpoint as a fetch handler: refuses a request addressed to another host than the resource's, then one

package/dist/mcp/mcp-handler.js

@@ -9,7 +9,7 @@ import { createMcpHandler, hostHeaderValidationResponse } from "@modelcontextpro
 const mcpHandler = ({ server, ...gate }) => {
 	const hostname = new URL(gate.resource).hostname;
 	const admit = mcpGate(gate);
-	const handler = createMcpHandler((context) => server(sessionOf(context.authInfo)), { legacy: "stateless" });
+	const handler = createMcpHandler((context) => server(sessionOf(context.authInfo), context.requestInfo), { legacy: "stateless" });
 	return async (request) => {
 		const wrongHost = hostHeaderValidationResponse(request, [hostname]);
 		if (wrongHost) return wrongHost;

package/dist/mcp/mcp-server.js

@@ -70,7 +70,7 @@ const mcpServer = ({ info, tools, context, report, rolesWithoutApproval = [], ap
 			} catch (error) {
 				if (!(error instanceof ApprovalNeeded)) throw error;
 				const { scope, call } = bound();
-				return approvalAsked(error.request, capabilitiesOf(ctx.mcpReq.envelope), () => approvals.ask(scope, call));
+				return approvalAsked(error.request, capabilitiesOf(ctx.mcpReq.envelope), () => approvals.ask(scope, call), context.locale);
 			}
 		};
 		server.registerTool(tool.name, config, async (args, ctx) => {

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.50.0";
+var version = "0.51.0";
 //#endregion
 export { version };

package/dist/realtime/channel-access.js

@@ -0,0 +1,61 @@
+import { isDatabaseError } from "../error-handler.js";
+import { writeTransaction } from "../transactions.js";
+import { callerSettings } from "../rest/caller-settings.js";
+import { sql } from "kysely";
+import { randomUUID } from "node:crypto";
+//#region src/realtime/channel-access.ts
+const insufficientPrivilege = "42501";
+/**
+* Supabase Realtime Authorization: the row security policies on `realtime.messages` decide what a caller may do on a
+* private channel's topic, as Supabase's Realtime checks them. Each check runs in a transaction of its own, under a
+* savepoint it rolls back, so nothing it inserts stays. It sets the caller's role and claims as `/api/sb/rest/v1` does,
+* and the topic, without its `realtime:` prefix, in `realtime.topic`, which `realtime.topic()` reads. A database
+* without `realtime.messages` allows nothing.
+*/
+const channelAccess = ({ db, statementTimeoutMs }) => {
+	const probe = (denied, run) => writeTransaction(db, statementTimeoutMs, async (trx) => {
+		const { rows } = await sql`select to_regclass('realtime.messages') is not null as found`.execute(trx);
+		if (!rows[0].found) return denied;
+		await sql`savepoint access_probe`.execute(trx);
+		const result = await run(trx);
+		await sql`rollback to savepoint access_probe`.execute(trx);
+		return result;
+	});
+	const actAs = (trx, caller, topic) => {
+		const settings = {
+			role: "none",
+			"request.jwt.claim.sub": "",
+			...callerSettings(caller),
+			"realtime.topic": topic
+		};
+		return sql`select ${sql.join(Object.entries(settings).map(([name, value]) => sql`set_config(${name}, ${value}, true)`))}`.execute(trx);
+	};
+	return {
+		/**
+		* Whether the caller may receive each extension's messages on the topic: as the connection's own role, which must
+		* own `realtime.messages` or bypass its policies, it inserts a message of each, then selects them as the caller.
+		*/
+		read: (caller, topic, extensions) => probe(/* @__PURE__ */ new Map(), async (trx) => {
+			const probes = extensions.map((extension) => ({
+				id: randomUUID(),
+				extension
+			}));
+			await sql`insert into realtime.messages (id, topic, extension, private)
+          select id, ${topic}, extension, true from jsonb_to_recordset(${JSON.stringify(probes)}::jsonb) as p(id uuid, extension text)`.execute(trx);
+			await actAs(trx, caller, topic);
+			const { rows } = await sql`select id::text as id from realtime.messages where id = any(${probes.map((probe) => probe.id)}::uuid[])`.execute(trx);
+			const seen = new Set(rows.map((row) => row.id));
+			return new Map(probes.map((probe) => [probe.extension, seen.has(probe.id)]));
+		}),
+		/** Whether the caller may send the extension's messages on the topic: whether it may insert one. */
+		write: (caller, topic, extension) => probe(false, async (trx) => {
+			await actAs(trx, caller, topic);
+			return sql`insert into realtime.messages (topic, extension, private) values (${topic}, ${extension}, true)`.execute(trx).then(() => true, (error) => {
+				if (isDatabaseError(error) && error.code === insufficientPrivilege) return false;
+				throw error;
+			});
+		})
+	};
+};
+//#endregion
+export { channelAccess };

package/dist/realtime/channel-gate.js

@@ -0,0 +1,46 @@
+import { isDatabaseError } from "../error-handler.js";
+//#region src/realtime/channel-gate.ts
+/** A public channel, which may do anything. */
+const publicGate = {
+	authorize: async () => void 0,
+	hears: () => true,
+	mayWrite: async () => true
+};
+/** Supabase's message for a refusal to read the topic, which it names without its `realtime:` prefix. */
+const readRefusalText = (topic, refusal) => refusal === "revoked" ? `You no longer have permission to read from this Channel topic: ${subTopic(topic)}` : `You do not have permissions to read from this Channel topic: ${subTopic(topic)}`;
+const subTopic = (topic) => topic.replace(/^realtime:/, "");
+/**
+* A private channel, as Supabase Realtime Authorization checks one: its reads of broadcasts, and of presence when it
+* listens to presence, are checked by `authorize`, and each write the first time the channel sends it after that, and
+* kept until its next token. A policy that fails, such as one calling a function that raises, allows nothing, and its
+* error goes to `report`.
+*/
+const privateGate = (access, topic, presence, report) => {
+	let reads = /* @__PURE__ */ new Map();
+	let writes = /* @__PURE__ */ new Map();
+	const denied = (nothing) => (error) => {
+		if (!isDatabaseError(error)) throw error;
+		report(error);
+		return nothing;
+	};
+	return {
+		authorize: async (caller) => {
+			const before = reads;
+			reads = await access.read(caller, subTopic(topic), presence ? ["broadcast", "presence"] : ["broadcast"]).catch(denied(/* @__PURE__ */ new Map()));
+			writes = /* @__PURE__ */ new Map();
+			if (![...reads.values()].some(Boolean)) return "denied";
+			if ([...before].some(([extension, allowed]) => allowed && !reads.get(extension))) return "revoked";
+		},
+		hears: (extension) => reads.get(extension) === true,
+		mayWrite: async (caller, extension) => {
+			const known = writes.get(extension);
+			if (known !== void 0) return known;
+			return access.write(caller, subTopic(topic), extension).then((allowed) => {
+				writes.set(extension, allowed);
+				return allowed;
+			}, denied(false));
+		}
+	};
+};
+//#endregion
+export { privateGate, publicGate, readRefusalText };

package/dist/realtime/realtime-app.js

@@ -1,10 +1,12 @@
 import { changeChecker } from "./change-checker.js";
 import { changeHub } from "./change-hub.js";
+import { channelAccess } from "./channel-access.js";
 import { realtimeRoutes } from "./realtime-routes.js";
 //#region src/realtime/realtime-app.ts
 /**
 * `/api/sb/realtime/v1`: the `postgres_changes` of the live resources, each checked under the subscriber's role, claims and
-* the tables' RLS policies before it is sent, and broadcasts and presence between the channels of the process.
+* the tables' RLS policies before it is sent, and broadcasts and presence between the channels of the process, on a
+* private channel as the policies on `realtime.messages` allow.
 */
 const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
 	const live = deps.registry.entries.filter((entry) => entry.model.live);
@@ -19,11 +21,16 @@ const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
 		entry: (resource) => live.find((entry) => entry.name === resource),
 		report
 	});
+	const access = channelAccess({
+		db: deps.db,
+		statementTimeoutMs: deps.statementTimeoutMs
+	});
 	return realtimeRoutes({
 		upgradeWebSocket,
 		caller,
 		live,
 		hub,
+		access,
 		report
 	});
 };

package/dist/realtime/realtime-routes.js

@@ -16,7 +16,7 @@ const keyRequest = (apikey, token) => new Request("http://realtime.invalid/", {
 * key is refused before the upgrade, with 401. A socket whose raw socket is not one of npm `ws`, such as Bun's own `ws`
 * shim's, is closed at once with 1011, since its unsent bytes cannot be counted (`realtimeLimits.maxUnsentBytes`).
 */
-const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, report }) => {
+const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, access, report }) => {
 	const app = new Hono();
 	const broadcasts = broadcastHub();
 	const presences = presenceHub();
@@ -45,6 +45,7 @@ const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, report }) => {
 					hub,
 					broadcasts,
 					presences,
+					access,
 					nextId,
 					report
 				});

package/dist/realtime/realtime-socket.js

@@ -4,6 +4,7 @@ import { fixedWindow, fixedWindows } from "./fixed-window.js";
 import { realtimeLimits } from "./realtime-limits.js";
 import { decodeMessage, encodeMessage, reply } from "./phoenix-message.js";
 import { decodeBroadcastPush, encodeBroadcast, fitsFrame } from "./broadcast-frame.js";
+import { privateGate, publicGate, readRefusalText } from "./channel-gate.js";
 import { randomUUID } from "node:crypto";
 import { Buffer } from "node:buffer";
 //#region src/realtime/realtime-socket.ts
@@ -26,7 +27,8 @@ const refusal = (error) => {
 * One WebSocket of `/api/sb/realtime/v1`, speaking Phoenix channels as realtime-js expects: heartbeats, channel joins with
 * `postgres_changes` bindings and an access token, token refreshes on an open channel, broadcasts with their `self`
 * and `ack` options, presence tracking, and leaves. A channel's token ends it when it expires, unless a newer one came
-* first. Messages are handled one at a time, in order. Private channels are refused for now.
+* first. Messages are handled one at a time, in order. A private channel joins, hears, broadcasts and tracks presence
+* only as the policies on `realtime.messages` allow (see `privateGate`), checked again at each new token.
 *
 * It holds a client to `realtimeLimits`: a push over a rate, a channel over the cap or a presence meta too big gets an
 * error reply where Supabase would close the channel, and is not relayed. Rates count per socket, presence per socket
@@ -35,7 +37,7 @@ const refusal = (error) => {
 * earlier messages wait. A close, the client's or the server's, leaves every channel, a join still checking its token
 * included, and drops whatever is still queued.
 */
-const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadcasts, presences, nextId, report, idleMs = 6e4, now = Date.now }) => {
+const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadcasts, presences, access, nextId, report, idleMs = 6e4, now = Date.now }) => {
 	const channels = /* @__PURE__ */ new Map();
 	let queue = Promise.resolve();
 	let queuedMessages = 0;
@@ -71,6 +73,7 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		payload
 	});
 	const hear = (topic, channel, event, payload) => {
+		if (!channel.gate.hears("broadcast")) return;
 		if (vsn === "2.0.0") return deliver(encodeBroadcast(topic, event, payload));
 		if (payload instanceof ArrayBuffer) return;
 		toChannel(topic, channel, "broadcast", {
@@ -109,12 +112,16 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		if (!channels.has(message.topic) && channels.size >= realtimeLimits.channelsPerSocket) return push(reply(message, "error", { reason: "ChannelRateLimitReached: Too many channels" }));
 		leave(message.topic);
 		const config = isRecord(message.payload.config) ? message.payload.config : {};
-		if (config.private === true) return push(reply(message, "error", { reason: "Not implemented: private channels" }));
 		const broadcast = isRecord(config.broadcast) ? config.broadcast : {};
 		const presence = isRecord(config.presence) ? config.presence : {};
+		const listens = presence.enabled === true;
+		const gate = config.private === true ? privateGate(access, message.topic, listens, report) : publicGate;
 		const caller = await resolve(tokenOf(message.payload)).catch(refusal);
 		if (!open) return;
 		if (typeof caller === "string") return push(reply(message, "error", { reason: caller }));
+		const refused = await gate.authorize(caller);
+		if (!open) return;
+		if (refused) return push(reply(message, "error", { reason: `Unauthorized: ${readRefusalText(message.topic, refused)}` }));
 		const parsed = parseBindings(config.postgres_changes, live, nextId);
 		if (typeof parsed === "string") return push(reply(message, "error", { reason: parsed }));
 		const { topic } = message;
@@ -123,10 +130,11 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 			receive: (event, payload) => hear(topic, channel, event, payload)
 		};
 		const key = typeof presence.key === "string" && presence.key !== "" ? presence.key : randomUUID();
-		const listens = presence.enabled === true;
 		const seat = presences.join(topic, {
 			key,
-			listens,
+			get listens() {
+				return listens && gate.hears("presence");
+			},
 			receive: (diff) => toChannel(topic, channel, "presence_diff", diff)
 		});
 		const offBroadcast = broadcasts.join(topic, member);
@@ -138,6 +146,7 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		const channel = {
 			joinRef: message.joinRef,
 			caller,
+			gate,
 			ack: broadcast.ack === true,
 			member,
 			presence: seat,
@@ -150,7 +159,7 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		channels.set(topic, channel);
 		expireAt(topic, channel);
 		push(reply(message, "ok", { postgres_changes: parsed.replies }));
-		if (listens) toChannel(topic, channel, "presence_state", seat.state());
+		if (listens && gate.hears("presence")) toChannel(topic, channel, "presence_state", seat.state());
 		if (parsed.bindings.length > 0) toChannel(message.topic, channel, "system", {
 			extension: "postgres_changes",
 			status: "ok",
@@ -163,25 +172,37 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		const channel = channels.get(message.topic);
 		if (!channel) return;
 		if (typeof caller === "string") return end(message.topic, caller);
+		const refused = await channel.gate.authorize(caller);
+		if (channels.get(message.topic) !== channel) return;
+		if (refused) return end(message.topic, readRefusalText(message.topic, refused));
 		channel.caller = caller;
 		expireAt(message.topic, channel);
 	};
-	const sendBroadcast = (message, channel) => {
+	const sendBroadcast = async (message, channel) => {
 		const { event, payload } = message.payload;
 		if (!events()) return push(reply(message, "error", { reason: tooFast }));
 		if (typeof event !== "string") return push(reply(message, "error", { reason: "A broadcast needs an event" }));
 		if (!fitsFrame(message.topic) || !fitsFrame(event)) return push(reply(message, "error", { reason: "A broadcast topic and event are at most 255 bytes each" }));
+		const allowed = await channel.gate.mayWrite(channel.caller, "broadcast");
+		if (channels.get(message.topic) !== channel) return;
+		if (!allowed) return push(reply(message, "error", { error: "unauthorized" }));
 		if (!broadcasts.send(message.topic, channel.member, event, payload)) return push(reply(message, "error", { reason: `${tooFast} on this topic` }));
 		if (channel.ack) push(reply(message, "ok", {}));
 	};
-	const updatePresence = (message, channel) => {
+	const updatePresence = async (message, channel) => {
 		const { event, payload } = message.payload;
 		if (!events()) return push(reply(message, "error", { reason: tooFast }));
 		if (!presenceRate(message.topic)) return push(reply(message, "error", { reason: "Client presence rate limit exceeded" }));
-		if (event === "track" && isRecord(payload) && Buffer.byteLength(JSON.stringify(payload)) > realtimeLimits.maxPresenceBytes) return push(reply(message, "error", { reason: "Track message size exceeded" }));
-		if (event === "track" && isRecord(payload)) channel.presence.track(payload);
-		else if (event === "untrack") channel.presence.untrack();
-		else return push(reply(message, "error", { reason: "A presence message tracks an object or untracks" }));
+		if (event === "untrack") {
+			channel.presence.untrack();
+			return push(reply(message, "ok", {}));
+		}
+		if (event !== "track" || !isRecord(payload)) return push(reply(message, "error", { reason: "A presence message tracks an object or untracks" }));
+		if (Buffer.byteLength(JSON.stringify(payload)) > realtimeLimits.maxPresenceBytes) return push(reply(message, "error", { reason: "Track message size exceeded" }));
+		const allowed = await channel.gate.mayWrite(channel.caller, "presence");
+		if (channels.get(message.topic) !== channel) return;
+		if (!allowed) return push(reply(message, "error", {}));
+		channel.presence.track(payload);
 		push(reply(message, "ok", {}));
 	};
 	const handle = async (message) => {

package/package.json

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