@protobase/server 0.35.0 → 0.37.0

package/dist/meta.d.ts

@@ -0,0 +1,76 @@
+import { Session } from "./types.js";
+import { ErrorReportingSettings } from "./error-reporting/error-reporting-settings.js";
+import { MapSettings } from "./maps/map-settings.js";
+import { PluginRef } from "./plugins/plugin-settings.js";
+import { SourceRef } from "./sources/source-settings.js";
+import { Deps } from "./deps.js";
+import { PageModel } from "@protobase/layout";
+import { Locale } from "@protobase/schema/internal";
+import { BottomBarItemModel, ResourceModel, SignInViewModel, UserMenuModel, ViewModel } from "@protobase/schema";
+//#region src/meta.d.ts
+export type ResourcePermissions = {
+  read: boolean;
+  create: boolean;
+  update: boolean;
+  delete: boolean;
+  /** Operations allowed only for some records: a row filter (`.own`) or a record-level rule decides. */
+  conditional: Array<'create' | 'update' | 'delete'>;
+};
+export type CallerMeta = {
+  /** The app's name, which ends the admin app's tab titles. */
+  appName: string;
+  /** The app's own icon, its favicon's path, when the project has one: the sidebar's logo draws it beside the name. */
+  appIcon?: string;
+  resources: ResourceModel[];
+  views: ViewModel[];
+  /** The composed pages the caller may open, without the elements that name what they cannot see or do. */
+  pages: PageModel[];
+  permissions: Record<string, ResourcePermissions>;
+  /** The user menu with the resources the caller cannot see left out. */
+  userMenu?: UserMenuModel;
+  /** For a visitor who is not signed in, the resources they cannot see whose view tells them what signing in gives. */
+  signIn?: SignInViewModel[];
+  /** The bottom bar naming the caller's active role, without the resources and pages they cannot see. */
+  bottomBar?: {
+    label: string;
+    items: BottomBarItemModel[];
+  };
+  /** The assistant backend, for a caller with the `admin` or `ai` role when there is one: an absolute URL, or the built-in one's path. */
+  assistant?: {
+    url: string;
+  };
+  /** The runtime updates endpoint, for a caller with the `admin` role when the app has one. */
+  runtime?: {
+    url: string;
+  };
+  /** Where the admin app sends its errors, when the app reports them: the DSN is public, as in any browser app. */
+  errorReporting?: ErrorReportingSettings;
+  /** The map style the admin app draws its maps with, and the layers they may switch to, when the app has one: public, as the tiles are. */
+  maps?: MapSettings;
+  /** The language the admin app's screens are in, when the app sets one for everyone. */
+  locale?: Locale;
+  /** The hosts besides the app's own whose images the admin app draws with the page's referrer, when there are any. */
+  files?: {
+    trustedHosts: string[];
+  };
+  /** The plugins the admin app loads for the caller: those for everyone, and those for one of their roles. */
+  plugins?: PluginRef[];
+  /** The other APIs whose resources the admin app draws for the caller: those for everyone, and those for one of their roles. */
+  sources?: SourceRef[];
+};
+/**
+ * `/meta` as one caller sees it: the resources they can do anything with, each as the restricted model (hidden fields
+ * absent, `readOnly` unless writable), the view for their roles with hidden fields pruned, what they may do, and the
+ * user menu and their bottom bar without the resources they cannot see. A visitor also gets the prompts of the resources
+ * they could use once signed in, which keep their place in the bottom bar and the user menu.
+ * The ETag hashes all of it, so it differs per user and per roles.
+ */
+export declare const createMeta: (deps: Deps, appName: string, appIcon?: string) => {
+  forCaller: (session: Session) => Promise<{
+    body: CallerMeta;
+    etag: string;
+  }>;
+  version: (roles: readonly string[]) => Promise<string>;
+};
+export type Meta = ReturnType<typeof createMeta>;
+//#endregion

package/dist/records.js

@@ -1,6 +1,6 @@
-import { storedValue } from "./encryption/stored-value.js";
 import { columnId, filterCondition, keyConditions, returningList, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { etagOf } from "./etag.js";
+import { storedValue } from "./encryption/stored-value.js";
 import { exposeRow, pickFields } from "./rows.js";
 import { sql } from "kysely";
 //#region src/records.ts

package/dist/registry.d.ts

@@ -1,2 +1,22 @@
-import "./resource-source.js";
-import { KeyType, ResourceModel } from "@protobase/schema";
+import { ResourceSource } from "./resource-source.js";
+import { FieldModel, KeyType, ResourceModel } from "@protobase/schema";
+//#region src/registry.d.ts
+export type EtagSource = {
+  field: FieldModel;
+  kind: 'version' | 'timestamp';
+};
+export type Entry = {
+  name: string;
+  source: ResourceSource;
+  model: ResourceModel;
+  keyTypes: KeyType[];
+  /** The type of the user ids its `.owner()` field holds: the field's own, or the key type of the record it points at. */
+  ownerType?: KeyType;
+  /** A database-managed `version` or `updated_at` column, when the table has one; otherwise ETags hash the row. */
+  etag?: EtagSource;
+};
+export type Registry = {
+  entries: Entry[];
+  find: (name: string) => Entry | undefined;
+};
+//#endregion

package/dist/request-access.d.ts

@@ -1,5 +1,5 @@
 import "./types.js";
 import "./registry.js";
 import "./deps.js";
-import { ResourceModel } from "@protobase/schema";
-import "@protobase/query";
+import { FieldModel, ResourceModel } from "@protobase/schema";
+import { Scope } from "@protobase/query";

package/dist/routes/collection.js

@@ -1,5 +1,5 @@
-import { runWrite } from "../write-pipeline.js";
 import { listRecords } from "../list-service.js";
+import { runWrite } from "../write-pipeline.js";
 import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
 import { aggregate } from "../aggregate-groups.js";
 import { mapRecords } from "../map-service.js";

package/dist/routes/record.js

@@ -1,10 +1,10 @@
 import { notFound } from "../problem.js";
 import { keyFromPath } from "../key.js";
+import { deletedRows, selectedFields } from "../params.js";
 import { pickFields } from "../rows.js";
 import { readRecord } from "../read-service.js";
 import { runWrite } from "../write-pipeline.js";
 import { auditOrigin } from "../audit/origin.js";
-import { deletedRows, selectedFields } from "../params.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget } from "./target.js";
 import { revealField } from "../reveal-service.js";

package/dist/row-permissions.js

@@ -3,8 +3,8 @@ import { recordDecision } from "./request-access.js";
 import { aliasedColumn, columnId, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { fetchRecord } from "./records.js";
 import { parentGuard } from "./parent-access.js";
-import { sql } from "kysely";
 import { compileFilter } from "@protobase/query";
+import { sql } from "kysely";
 //#region src/row-permissions.ts
 const keyOf = (access, row) => JSON.stringify(access.full.primaryKey.map((name) => String(row[name])));
 const matching = async (trx, access, rows, filter) => {

package/dist/scan-guard.d.ts

@@ -1,4 +1,22 @@
-import "./types.js";
-import "./registry.js";
+import { ScanGuardMode } from "./types.js";
+import { Entry } from "./registry.js";
 import { ResourceModel } from "@protobase/schema";
-import { Db } from "@protobase/query";
+import { CoverageQuery, Db, Scope, TableIndexes } from "@protobase/query";
+//#region src/scan-guard.d.ts
+/** The model the query runs against (as the caller sees it) and its scope (tenant, row filter, full model). */
+export type GuardContext = {
+  model: ResourceModel;
+  scope: Scope;
+};
+/**
+ * Checks that an index serves every column a read filters, sorts or groups by, from the table's indexes in the catalog
+ * (read once per table and kept for the process lifetime), so a read is never refused or allowed by how many rows match.
+ */
+export declare const createScanGuard: (db: Db, options?: {
+  mode?: ScanGuardMode;
+}) => ((entry: Entry, query: CoverageQuery, context: GuardContext) => Promise<string | undefined>) & {
+  mode: ScanGuardMode;
+  indexesOf: (entry: Entry) => Promise<TableIndexes>;
+};
+export type ScanGuard = ReturnType<typeof createScanGuard>;
+//#endregion

package/dist/sql-parts.js

@@ -1,5 +1,5 @@
-import { sql } from "kysely";
 import { compileFilter } from "@protobase/query";
+import { sql } from "kysely";
 //#region src/sql-parts.ts
 const etagAlias = "__pb_etag";
 const tableId = (model) => {

package/dist/webhooks/subscriber-view.js

@@ -40,20 +40,30 @@ const subscriptionEvent = (change, event, { fields, thin = false } = {}) => ({
 		transaction: change.transaction
 	}
 });
-const withUnknownEncrypted = (model, record) => {
-	const fields = Object.values(model.fields).filter((field) => field.encrypted);
-	if (fields.length === 0) return record;
+const withUnknownFields = (model, record) => {
+	const fields = Object.values(model.fields).filter((field) => field.sensitive || !Object.hasOwn(record, field.name));
 	const unknown = { ...record };
+	const read = [];
+	const error = (name) => {
+		const field = model.fields[name];
+		return /* @__PURE__ */ new Error(`a subscription's access check cannot tell whether the ${field.sensitive ? "sensitive field" : "field"} "${name}" is set${field.sensitive ? "" : ", which the captured change does not hold"}`);
+	};
 	for (const field of fields) Object.defineProperty(unknown, field.name, {
 		enumerable: true,
 		get: () => {
-			throw new Error(`a subscription's access check cannot tell whether the encrypted field "${field.name}" is set`);
+			read.push(field.name);
+			throw error(field.name);
 		}
 	});
-	return unknown;
+	const check = () => {
+		if (read.length > 0) throw error(read[0]);
+	};
+	return {
+		record: unknown,
+		check
+	};
 };
-const mayRead = async (access, captured) => {
-	const record = withUnknownEncrypted(access.full, captured);
+const decide = async (access, record) => {
 	const { resolved, session, entry } = access;
 	if (!resolved.operations.read) return false;
 	if (resolved.rowFilter.read && evaluateFilter(resolved.rowFilter.read, record) !== true) return false;
@@ -64,6 +74,12 @@ const mayRead = async (access, captured) => {
 	};
 	return checkRecord(entry.source, context, "read", record, void 0, access.deps.accessOptions);
 };
+const mayRead = async (access, captured) => {
+	const { record, check } = withUnknownFields(access.full, captured);
+	const allowed = await decide(access, record);
+	check();
+	return allowed;
+};
 /**
 * Builds each subscriber's event, under the access rules of the session it delivers as, resolved once per subscription
 * and resource: `undefined` when it may not read the record, after the change or before a delete.

package/dist/webhooks/webhooks.js

@@ -47,7 +47,9 @@ const deliveryGroup = ({ subscription, change }) => `${subscription.name}:${chan
 *   before that commits leaves the rows, and the job's retry delivers them again, under the same `webhook-id`.
 * - `webhooks.dispatch-change`, one change whose app code threw in dispatch: an event's `match` or filter, a
 *   subscription's `when`, or an access rule of its roles. Kept as failed, so dispatch moves on to later changes; a
-*   retry after the fix queues the change's deliveries. Any other error fails the whole dispatch, which is retried.
+*   retry after the fix queues the change's deliveries. An access rule's failure keeps the change for that subscription
+*   only: the others still receive it, and the retry delivers to that subscription alone. Any other error fails the
+*   whole dispatch, which is retried.
 * - `webhooks.deliver`, one try of an unordered delivery; a failure queues the next try on the Standard Webhooks
 *   schedule, or Retry-After, and the last one is kept as failed.
 * - `webhooks.deliver-ordered`, the ordered deliveries of one dispatch for one subscription and record, retried with
@@ -148,17 +150,32 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 	const changeDeliveries = async (db) => {
 		const route = subscriptionRouter(await current(db), models);
 		const eventOf = subscriberEvents(deps);
-		return async (change) => {
+		return async (change, only) => {
+			const routes = route(change, matchers.get(change.resource)(change)).filter(({ subscription }) => only === void 0 || subscription.name === only);
 			const deliveries = [];
-			for (const { subscription, event } of route(change, matchers.get(change.resource)(change))) {
-				const shaped = await eventOf(subscription, change, event);
+			const failures = [];
+			const failed = /* @__PURE__ */ new Set();
+			for (const { subscription, event } of routes) {
+				if (failed.has(subscription.name)) continue;
+				const shaped = await eventOf(subscription, change, event).catch((error) => {
+					if (!(error instanceof EventCodeError)) throw error;
+					failed.add(subscription.name);
+					failures.push({
+						change,
+						subscription: subscription.name,
+						error
+					});
+				});
 				if (shaped) deliveries.push({
 					subscription,
 					event: shaped,
 					change
 				});
 			}
-			return deliveries;
+			return {
+				deliveries: deliveries.filter(({ subscription }) => !failed.has(subscription.name)),
+				failures
+			};
 		};
 	};
 	const queueOrdered = async (db, deliveries) => {
@@ -178,8 +195,9 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 		name: "webhooks.dispatch-change",
 		maxAttempts: 1,
 		timeout: "5 minutes",
-		run: async ({ change }, { db }) => {
-			const deliveries = await (await changeDeliveries(db))(change);
+		run: async ({ change, subscription: only }, { db }) => {
+			const { deliveries, failures } = await (await changeDeliveries(db))(change, only);
+			if (only !== void 0 && failures.length > 0) throw failures[0].error;
 			await db.transaction().execute(async (trx) => {
 				for (const { subscription, event } of deliveries.filter(({ subscription }) => !subscription.options.ordered)) {
 					const payload = {
@@ -190,6 +208,10 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 					await deliver.enqueue(trx, payload, { key: deliveryKey(payload) });
 				}
 				await queueOrdered(trx, deliveries);
+				for (const { subscription } of failures) await dispatchChange.enqueue(trx, {
+					change,
+					subscription
+				});
 			});
 		}
 	});
@@ -204,7 +226,9 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 		const deliveries = [];
 		const failures = [];
 		for (const change of changes) try {
-			deliveries.push(...await deliveriesOf(change));
+			const routed = await deliveriesOf(change);
+			deliveries.push(...routed.deliveries);
+			failures.push(...routed.failures);
 		} catch (error) {
 			if (!(error instanceof EventCodeError)) throw error;
 			failures.push({
@@ -232,7 +256,10 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 				});
 			}
 			await queueOrdered(trx, deliveries);
-			for (const { change } of failures) await dispatchChange.enqueue(trx, { change });
+			for (const { change, subscription } of failures) await dispatchChange.enqueue(trx, {
+				change,
+				...subscription !== void 0 && { subscription }
+			});
 			await writeHistory(trx, schema, changes.filter((change) => deps.registry.find(change.resource)?.model.history));
 			await writeNotices(trx, schema, changes.filter((change) => deps.registry.find(change.resource)?.model.live));
 			await deleteOutbox(trx, schema, rows.map((row) => row.id));

package/dist/write-shared.js

@@ -2,8 +2,8 @@ import { maskEncrypted } from "./encryption/mask-stored.js";
 import { forbidden, notFound, preconditionFailed, preconditionRequired } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { andFilters, recordDecision } from "./request-access.js";
-import { presentFiles } from "./files/present.js";
 import { ifMatchSatisfied } from "./etag.js";
+import { presentFiles } from "./files/present.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
 import { parentGuard } from "./parent-access.js";

package/package.json

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