@protobase/server 0.33.3 → 0.34.0

package/dist/records.js

@@ -1,3 +1,4 @@
+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 { exposeRow, pickFields } from "./rows.js";
@@ -24,10 +25,9 @@ const fetchRecord = async (db, entry, key, tenant, options = {}) => {
 	const query = sql`select ${returningList(entry, shape.fields)} from ${tableId(entry.model)} as t${whereClause(conditions)} limit 1${lockClause(lock)}`;
 	return stored(entry, (await rowsOf(db, query))[0], shape);
 };
-const writeValue = (field, value) => field.type === "json" && value !== null ? JSON.stringify(value) : value;
 const insertRecord = async (db, entry, values, shape = {}) => {
 	const fields = Object.keys(values).map((name) => entry.model.fields[name]);
-	const body = fields.length === 0 ? sql`default values` : sql`(${sql.join(fields.map(columnId))}) values (${sql.join(fields.map((field) => writeValue(field, values[field.name])))})`;
+	const body = fields.length === 0 ? sql`default values` : sql`(${sql.join(fields.map(columnId))}) values (${sql.join(fields.map((field) => storedValue(field, values[field.name])))})`;
 	const query = sql`insert into ${tableId(entry.model)} ${body} returning ${returningList(entry, shape.fields)}`;
 	return await stored(entry, (await rowsOf(db, query))[0], shape);
 };
@@ -39,7 +39,7 @@ const etagBump = (entry) => {
 const updateRecord = async (db, entry, key, tenant, values, shape = {}) => {
 	const assignments = [...Object.entries(values).map(([name, value]) => {
 		const field = entry.model.fields[name];
-		return sql`${columnId(field)} = ${writeValue(field, value)}`;
+		return sql`${columnId(field)} = ${storedValue(field, value)}`;
 	}), ...etagBump(entry)];
 	const conditions = [...scopeConditions(entry.model, tenant), ...keyConditions(entry.model, key)];
 	const query = sql`update ${tableId(entry.model)} as t set ${sql.join(assignments)}${whereClause(conditions)} returning ${returningList(entry, shape.fields)}`;

package/dist/request-access.js

@@ -1,3 +1,4 @@
+import { maskEncrypted } from "./encryption/mask-stored.js";
 import { forbidden, notFound, unauthorized } from "./problem.js";
 import { checkedFilter } from "./filter-input.js";
 import { checkOwnerId } from "./owner-id.js";
@@ -98,7 +99,7 @@ const trusted = (model) => ({
 	...model,
 	fields: Object.fromEntries(Object.entries(model.fields).map(([name, field]) => [name, {
 		...field,
-		filterable: true
+		filterable: !field.encrypted
 	}]))
 });
 const asFilter = (access, expr, operation) => {
@@ -109,13 +110,16 @@ const asFilter = (access, expr, operation) => {
 };
 /**
 * The record-level rule of an operation, run with the stored record (and the input of a write). Returns a verdict, or a
-* filter that the caller checks in the database, so its semantics match reads exactly.
+* filter that the caller checks in the database, so its semantics match reads exactly. The rule gets a set encrypted
+* field of the stored record as `encrypted`, never its ciphertext; the input it gets as written.
 */
 const recordDecision = async (access, operation, record, input) => {
 	const { entry, deps, full, session } = access;
 	const explicit = entry.source.accessRules[operation] ?? (operation === "list" ? entry.source.accessRules.read : void 0);
 	const fallback = deps.accessOptions.defaultAccess ? () => deps.accessOptions.defaultAccess === "allow" : deps.accessOptions.roles ? deps.accessOptions.roles.can(`${entry.name}.${operation === "list" ? "read" : operation}`) : () => true;
-	const result = await (explicit ?? fallback)({
+	const rule = explicit ?? fallback;
+	const stored = record && maskEncrypted(full, record);
+	const result = await rule({
 		user: {
 			id: session.user.id,
 			roles: session.user.roles
@@ -123,8 +127,8 @@ const recordDecision = async (access, operation, record, input) => {
 		...organizationOf(session),
 		model: full,
 		operation,
-		record
-	}, record, input);
+		record: stored
+	}, stored, input);
 	if (typeof result === "boolean") return result;
 	return asFilter(access, result, operation);
 };

package/dist/rest/encrypted-columns.js

@@ -0,0 +1,37 @@
+import { restError } from "./rest-error.js";
+import { sameTable } from "../encryption/shared-columns.js";
+//#region src/rest/encrypted-columns.ts
+const guardedTable = (served, models) => ({
+	name: served.table.name,
+	models: models.filter((model) => sameTable(model, served))
+});
+const encryptedColumns = (table) => new Set(table.models.flatMap((model) => Object.values(model.fields).filter((field) => field.encrypted).map((field) => field.column)));
+const bindingColumns = (table) => table.models.filter((model) => Object.values(model.fields).some((field) => field.encrypted)).flatMap((model) => [...model.primaryKey, ...model.tenant ? [model.tenant] : []].map((name) => model.fields[name].column));
+const refusal = (table, column, what) => restError(400, "encrypted-column", `Column '${column}' of '${table.name}' is encrypted: it cannot be ${what} here`, null, "Write and reveal encrypted fields through /api/v1");
+const filterColumns = (filter) => filter.kind === "condition" ? [filter.field.column] : filter.args.flatMap(filterColumns);
+/** Refuses filters, a sort or a join on an encrypted column, whose ciphertext no comparison matches. */
+const refuseEncryptedReads = (table, filters, order, joined = []) => {
+	const encrypted = encryptedColumns(table);
+	const read = [
+		...filters.flatMap(filterColumns),
+		...order.map((term) => term.field.column),
+		...joined
+	].find((column) => encrypted.has(column));
+	if (read !== void 0) throw refusal(table, read, "filtered, sorted or joined on");
+};
+/** Refuses a write of an encrypted column, or matching an upsert's rows on one. */
+const refuseEncryptedWrite = (table, columns) => {
+	const encrypted = encryptedColumns(table);
+	const written = columns.find((column) => encrypted.has(column));
+	if (written !== void 0) throw refusal(table, written, "written or matched on");
+};
+/**
+* On a table with encrypted fields, refuses a write that changes the key or tenant of a row, which its encrypted values
+* are bound to: an update's `columns`, or an upsert's beyond the `kept` ones it matches rows on and so writes unchanged.
+*/
+const refuseRebinding = (table, columns, kept = []) => {
+	const rebound = bindingColumns(table).find((column) => columns.includes(column) && !kept.includes(column));
+	if (rebound !== void 0) throw restError(400, "encrypted-column", `Column '${rebound}' of '${table.name}' cannot change here: its encrypted fields are bound to it`, null, "Change it through /api/v1");
+};
+//#endregion
+export { guardedTable, refuseEncryptedReads, refuseEncryptedWrite, refuseRebinding };

package/dist/rest/table-routes.js

@@ -7,6 +7,7 @@ import { parseQuery } from "./parse-query.js";
 import { embedsOf, resolveShape } from "./embed-shape.js";
 import { readRows } from "./read-rows.js";
 import { asCaller, queryParams, readBody } from "./rest-context.js";
+import { guardedTable, refuseEncryptedReads, refuseEncryptedWrite, refuseRebinding } from "./encrypted-columns.js";
 import { scanRefusal, uncoveredReads } from "./rest-scan.js";
 import { deleteRows, insertRows, updateRows } from "./write-rows.js";
 import { Hono } from "hono";
@@ -35,27 +36,32 @@ const shapeOf = async (deps, foreignKeys, entry, query) => {
 		embedded: query.embedded
 	}, entry.model.table.name, query.select);
 };
+const guarded = (deps, entry) => guardedTable(entry.model, deps.registry.entries.map((one) => one.model));
 const targetOf = (entry) => ({
 	table: tableId(entry.model),
 	alias: entry.model.table.name
 });
+/** What a request reads of the table and of every embedded one: its filters, its sort and the columns it joins on. */
+const readsOf = (deps, entry, filters, order, shape) => [{
+	entry,
+	filters,
+	order,
+	joined: []
+}, ...embedsOf(shape).map((embed) => ({
+	entry: tableEntry(deps, embed.table),
+	filters: embed.params.filters,
+	order: embed.params.order,
+	joined: embed.relationship.join.map((pair) => pair.target)
+}))];
 /**
-* Refuses filters and a sort no index serves, as the scan guard does on `/api/v1`, on the table and on every embedded
-* one, whose join columns need an index too; in `warn` mode, a warning header instead.
+* Refuses filters, a sort or a join on an encrypted column; then filters and a sort no index serves, as the scan guard
+* does on `/api/v1`, on the table and on every embedded one, whose join columns need an index too; in `warn` mode, a
+* warning header instead.
 */
 const scanCheck = async (deps, entry, filters, order, shape = []) => {
+	const reads = readsOf(deps, entry, filters, order, shape);
+	for (const read of reads) refuseEncryptedReads(guarded(deps, read.entry), read.filters, read.order, read.joined);
 	if (deps.guard.mode === "off") return {};
-	const reads = [{
-		entry,
-		filters,
-		order,
-		joined: []
-	}, ...embedsOf(shape).map((embed) => ({
-		entry: tableEntry(deps, embed.table),
-		filters: embed.params.filters,
-		order: embed.params.order,
-		joined: embed.relationship.join.map((pair) => pair.target)
-	}))];
 	for (const read of reads) {
 		const [first] = uncoveredReads(await deps.guard.indexesOf(read.entry), read.filters, read.order, read.joined);
 		if (!first) continue;
@@ -130,6 +136,9 @@ const insert = async (deps, foreignKeys, c) => {
 	if (columns.length === 0 && rows.length > 1) throw restError(400, "PGRST102", "Several rows without any column cannot be inserted at once");
 	if (rows.length === 0 && object) checkSingle(0);
 	const conflict = query.onConflict ?? entry.model.primaryKey.map((name) => entry.model.fields[name].column);
+	const table = guarded(deps, entry);
+	refuseEncryptedWrite(table, prefer.resolution ? [...columns, ...conflict] : columns);
+	if (prefer.resolution === "merge-duplicates") refuseRebinding(table, columns, conflict);
 	const written = rows.length === 0 ? {
 		total: 0,
 		...prefer.return === "representation" && { body: "[]" }
@@ -154,6 +163,9 @@ const update = async (deps, foreignKeys, c) => {
 	const object = wantsObject(c.req.raw);
 	const body = await readBody(c);
 	if (!isRecord(body)) throw restError(400, "PGRST102", "Empty or invalid json");
+	const table = guarded(deps, entry);
+	refuseEncryptedWrite(table, Object.keys(body));
+	refuseRebinding(table, Object.keys(body));
 	const shape = await shapeOf(deps, foreignKeys, entry, query);
 	const warning = await scanCheck(deps, entry, query.filters, [], shape);
 	const written = Object.keys(body).length === 0 ? {

package/dist/reveal-service.js

@@ -1,10 +1,21 @@
 import { badRequest, notFound } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation } from "./request-access.js";
+import { bindingOf } from "./encryption/binding.js";
 import { fetchReadable } from "./fetch-readable.js";
 import { readTransaction } from "./transactions.js";
+import { openText } from "./encryption/envelope-open.js";
 import { encodeKey } from "@protobase/schema/internal";
 //#region src/reveal-service.ts
+const revealedValue = (deps, model, field, record) => {
+	const stored = record[field.name] ?? null;
+	if (!field.encrypted || stored === null) return stored;
+	if (!deps.encryption) throw new Error(`"${model.name}" has encrypted fields but no encryption runtime`);
+	return openText(deps.encryption.keyring, bindingOf(model, field, record), String(stored), {
+		resource: model.name,
+		field: field.name
+	});
+};
 /**
 * The value of one sensitive field of one record, for a caller who may read the record and the field: the same tenant,
 * row filter and record-level rule as a get. The reveal is published to the audit queue before the value is returned;
@@ -17,9 +28,12 @@ const revealField = async (deps, entry, session, request) => {
 	const field = Object.hasOwn(access.readable.fields, name) ? access.readable.fields[name] : void 0;
 	if (!field) throw badRequest("invalid-parameter", `Unknown field "${name}"`);
 	if (!field.sensitive) throw badRequest("invalid-parameter", `"${name}" is not sensitive; it comes with the record`);
-	const keyFields = access.full.primaryKey.map((part) => access.full.fields[part]);
-	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchReadable(trx, access, request.key, "hide", { fields: [...keyFields, access.full.fields[name]] }));
+	const { full } = access;
+	const tenantField = full.fields[name].encrypted && full.tenant && !full.primaryKey.includes(full.tenant) ? [full.tenant] : [];
+	const keyFields = [...full.primaryKey, ...tenantField].map((part) => full.fields[part]);
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchReadable(trx, access, request.key, "hide", { fields: [...keyFields, full.fields[name]] }));
 	if (!found) throw notFound(`No ${entry.name} with this key`);
+	const value = revealedValue(deps, access.full, full.fields[name], found.record);
 	const tenant = tenantScope(entry, session)?.tenantValue;
 	await deps.audit.publish({
 		type: "field.revealed",
@@ -36,7 +50,7 @@ const revealField = async (deps, entry, session, request) => {
 	});
 	return {
 		field: name,
-		value: found.record[name] ?? null
+		value
 	};
 };
 //#endregion

package/dist/types.d.ts

@@ -19,6 +19,11 @@ export type Session = {
   tenant?: TenantValue;
   organization?: SessionOrganization;
   anonymous?: true;
+  /** The outside app acting as the user, such as an MCP client: its OAuth client id and the scopes its token carries. */
+  client?: {
+    id: string;
+    scopes: string[];
+  };
 };
 /**
  * Resolves the caller of a request, or throws a 401 problem (see `unauthorized`). `userIdType` declares the type of

package/dist/validate-body.js

@@ -1,3 +1,4 @@
+import { maskEncrypted } from "./encryption/mask-stored.js";
 import { badRequest } from "./problem.js";
 import { writableFields } from "./request-access.js";
 //#region src/validate-body.ts
@@ -31,7 +32,8 @@ const requiredOnCreate = (field, schema) => !(field.default && "db" in field.def
 * for a text field that may not be null counts as not given: a create fills in its default or reports it required,
 * an update reports it required. Only the values written are checked, so a stored '' still reads.
 * Returns only the values to write: on create the defaults are filled in, on update only the provided fields.
-* `current` is the stored record an update merges into for `.validate()` rules.
+* `current` is the stored record an update merges into for `.validate()` rules, which get a set encrypted field of it as
+* `encrypted`: they see an encrypted value as text only when this write gives it.
 */
 const validateBody = (access, mode, body, current = {}) => {
 	if (!isObject(body)) throw badRequest("invalid-record", "The request body must be a JSON object");
@@ -85,7 +87,7 @@ const validateBody = (access, mode, body, current = {}) => {
 	}
 	if (errors.length > 0) throw fail(errors);
 	const merged = {
-		...current,
+		...maskEncrypted(full, current),
 		...values
 	};
 	const issues = entry.source.validators.flatMap((validate) => validate(merged) ?? []);

package/dist/webhooks/attempt.js

@@ -47,10 +47,14 @@ const callFunction = async (name, subscription, event, options, context, signal)
 		session,
 		records: context.records(session)
 	};
+	const acceptWebSocket = () => {
+		throw new Error(`The function "${name}" accepted a WebSocket, but a webhook delivery is no upgrade`);
+	};
 	const functionContext = {
 		name,
 		db: context.db,
-		caller: async () => caller
+		caller: async () => caller,
+		acceptWebSocket
 	};
 	return invokeFunction(name, fn, await request("http://protobase.internal/", event, options, signal), fn.options.public ? functionContext : {
 		...functionContext,

package/dist/webhooks/subscriber-view.js

@@ -40,7 +40,20 @@ const subscriptionEvent = (change, event, { fields, thin = false } = {}) => ({
 		transaction: change.transaction
 	}
 });
-const mayRead = async (access, record) => {
+const withUnknownEncrypted = (model, record) => {
+	const fields = Object.values(model.fields).filter((field) => field.encrypted);
+	if (fields.length === 0) return record;
+	const unknown = { ...record };
+	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`);
+		}
+	});
+	return unknown;
+};
+const mayRead = async (access, captured) => {
+	const record = withUnknownEncrypted(access.full, captured);
 	const { resolved, session, entry } = access;
 	if (!resolved.operations.read) return false;
 	if (resolved.rowFilter.read && evaluateFilter(resolved.rowFilter.read, record) !== true) return false;

package/dist/write-pipeline.js

@@ -1,11 +1,13 @@
 import { HttpProblem, badRequest } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
-import { deleteRecord, fetchRecord, insertRecord, restoreRecord } from "./records.js";
+import { bindingOf, pendingBinding } from "./encryption/binding.js";
+import { deleteRecord, fetchRecord, insertRecord, restoreRecord, updateRecord } from "./records.js";
 import { writeTransaction } from "./transactions.js";
 import { blockedDelete } from "./blocked-delete.js";
 import { isDatabaseError } from "./error-handler.js";
 import { attachFiles } from "./files/attach.js";
+import { encryptedValuesOf, hasEncryptedValues, sealValues } from "./encryption/seal-values.js";
 import { actorSettings, wakeDispatch } from "./changes/actor.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkParents, checkPrecondition, decide, denied, firstKeyField, keyOf, missing, notifier, shown } from "./write-shared.js";
@@ -21,6 +23,14 @@ const withOwner = (access, values) => {
 		[owner]: caller
 	};
 };
+const bindEncrypted = async (trx, deps, access, row, inserted, shape) => {
+	const { entry, full } = access;
+	if (!hasEncryptedValues(full, row)) return inserted;
+	const values = sealValues(deps.encryption, full, encryptedValuesOf(full, row), (field) => bindingOf(full, field, inserted.record));
+	const bound = await updateRecord(trx, entry, keyOf(access, inserted.record), tenantScope(entry, access.session)?.tenantValue, values, shape);
+	if (!bound) throw new Error(`A ${entry.name} record was created whose key the API cannot address, so its encrypted fields cannot be bound to it`);
+	return bound;
+};
 const create = async (trx, deps, access, body) => {
 	const { entry, full } = access;
 	const scope = tenantScope(entry, access.session);
@@ -33,7 +43,9 @@ const create = async (trx, deps, access, body) => {
 	const filter = await decide(access, "create", void 0, row);
 	const parents = checkParents(trx, access, "create");
 	await parents(row);
-	const created = await insertRecord(trx, entry, row, { etagFields: Object.keys(access.model.fields) });
+	const shape = { etagFields: Object.keys(access.model.fields) };
+	const inserted = await insertRecord(trx, entry, sealValues(deps.encryption, full, row, (field) => pendingBinding(full, field)), shape);
+	const created = await bindEncrypted(trx, deps, access, row, inserted, shape);
 	await assertWritten(trx, access, created, "create", access.resolved.rowFilter.create, filter);
 	await parents(created.record);
 	if (full.position) await checkRankAfter(trx, deps, access, full.position.field, [{

package/dist/write-shared.js

@@ -1,3 +1,4 @@
+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";
@@ -44,7 +45,10 @@ const assertWritten = async (trx, access, written, operation, ...filters) => {
 		fields: [firstKeyField(access)]
 	})) throw denied(access.entry, `leave in that state (${operation})`);
 };
-/** The caller sees the readable fields only, files as objects with their URL; hooks get the whole record. */
+/**
+* The caller sees the readable fields only, files as objects with their URL; hooks get the whole record, a set encrypted
+* field as `encrypted`.
+*/
 const shown = async (access, written) => ({
 	record: (await presentFiles(access, [pickFields(written.record, Object.keys(access.model.fields))]))[0],
 	etag: written.etag
@@ -58,8 +62,8 @@ const notifier = (deps, access) => async (trx, kind, before, after) => {
 		user: session.user,
 		...session.tenant !== void 0 && { tenant: session.tenant },
 		...session.anonymous && { anonymous: true },
-		...before && { before },
-		...after && { after }
+		...before && { before: maskEncrypted(access.full, before) },
+		...after && { after: maskEncrypted(access.full, after) }
 	};
 	for (const hook of deps.hooks) await hook(event, trx);
 	await scheduleRemovedFiles(access, kind, before, after);

package/dist/write-update.js

@@ -1,7 +1,10 @@
+import { badRequest } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { targetFilter } from "./request-access.js";
+import { bindingOf } from "./encryption/binding.js";
 import { fetchRecord, updateRecord } from "./records.js";
 import { attachFiles } from "./files/attach.js";
+import { sealValues } from "./encryption/seal-values.js";
 import { validateBody } from "./validate-body.js";
 import { assertWritten, checkParents, checkPrecondition, decide, denied, firstKeyField, missing, notifier } from "./write-shared.js";
 //#region src/write-update.ts
@@ -40,11 +43,18 @@ const planUpdate = async (trx, access, key, body, ifMatch, required = true) => {
 		parents
 	};
 };
+const refuseKeyChange = (access, plan) => {
+	const { full, entry } = access;
+	if (!Object.values(full.fields).some((field) => field.encrypted)) return;
+	if (full.primaryKey.some((name) => Object.hasOwn(plan.values, name) && String(plan.values[name]) !== String(plan.current.record[name]))) throw badRequest("key-change-unsupported", `The key of a ${entry.name} record cannot change: its encrypted fields are bound to it`);
+};
 /** Writes a planned update, checks the row as written against the filters, and runs the hooks. */
 const applyUpdate = async (trx, deps, access, key, plan) => {
-	const { entry } = access;
+	const { entry, full } = access;
+	refuseKeyChange(access, plan);
 	const tenant = tenantScope(entry, access.session)?.tenantValue;
-	const updated = await updateRecord(trx, entry, key, tenant, plan.values, { etagFields: Object.keys(access.model.fields) });
+	const values = sealValues(deps.encryption, full, plan.values, (field) => bindingOf(full, field, plan.current.record));
+	const updated = await updateRecord(trx, entry, key, tenant, values, { etagFields: Object.keys(access.model.fields) });
 	await assertWritten(trx, access, updated, "update", access.resolved.rowFilter.update, plan.filter);
 	await plan.parents(updated.record);
 	await notifier(deps, access)(trx, "update", plan.current.record, updated.record);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.33.3",
+  "version": "0.34.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,18 +30,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@better-auth/passkey": "^1.7.7",
-    "@better-auth/sso": "^1.7.7",
-    "@protobase/layout": "0.33.3",
-    "@protobase/query": "0.33.3",
-    "@protobase/schema": "0.33.3",
+    "@better-auth/cimd": "^1.7.12",
+    "@better-auth/mcp": "^1.7.12",
+    "@better-auth/oauth-provider": "^1.7.12",
+    "@better-auth/passkey": "^1.7.12",
+    "@better-auth/sso": "^1.7.12",
+    "@protobase/layout": "0.34.0",
+    "@protobase/query": "0.34.0",
+    "@protobase/schema": "0.34.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
     "@simplewebauthn/server": "^13.3.1",
     "altcha-lib": "^2.6.0",
     "bcryptjs": "^3.0.3",
-    "better-auth": "^1.7.7",
+    "better-auth": "^1.7.12",
+    "better-call": "1.4.4",
     "cron-parser": "^5.10.1",
     "file-type": "^22.1.1",
     "hono": "^4.13.13",