@protobase/server 0.57.6 → 0.58.1

package/dist/admin-options.d.ts

@@ -5,6 +5,7 @@ import { MapOptions } from "./maps/map-settings.js";
 import { PluginOption } from "./plugins/plugin-settings.js";
 import { SourceOption } from "./sources/source-settings.js";
 import { CorsOrigins } from "./api-cors.js";
+import { AssistantTool } from "./assistant/tools.js";
 import { AssistantOptions } from "./assistant/assistant-settings.js";
 import { LocaleOption } from "./locale/locale-option.js";
 import { McpWrites } from "./mcp/mcp-writes.js";
@@ -75,12 +76,16 @@ export type AdminOptions = {
    * `writes: { rolesWithoutApproval: ['service'] }` lets a user holding one of those roles, such as a service account
    * with no person present, write without the approval; any other user is still asked. Each must be a role the app's
    * users can hold.
+   * `tools`: the app's own tools, offered after the built-in ones whatever `writes` says, each run as the caller under
+   * their access rules. One that changes data asks through `approve`, which `rolesWithoutApproval` skips too; one that
+   * never calls it writes unasked. A name taken twice, or by a built-in tool, stops startup.
    * `false`: the host serves its own MCP endpoint at `auth.mcp.path`, in front of this app. This app then answers 404
    * there and needs no `forAudience`, while the OAuth provider's discovery stays.
    */
   mcp?: {
     sql?: boolean;
     writes?: McpWrites;
+    tools?: AssistantTool[];
   } | false;
   /**
    * The websites whose browser code may call the API (`/api/*` but `/api/auth/*`) besides the app's own origins (see

package/dist/assistant/tools.d.ts

@@ -21,7 +21,7 @@ export type ToolContext = {
   show: (part: AssistantPart) => void;
   /** Asks the user to approve with a card in that message (see `requestApproval`). */
   approve: (request: ApprovalRequest) => Promise<ApprovalAnswer>;
-  /** The app's resources as the session's user, through their access rules and write hooks (built-in assistant only). */
+  /** The app's resources as the session's user, through their access rules and write hooks. */
   records: ToolRecords;
   /** The resources the caller may read, each restricted to their fields, with their views. */
   resources: () => Promise<ReadableResources>;
@@ -38,7 +38,7 @@ export type ToolAnnotations = {
 };
 /**
  * A function the model may call during a turn. `parameters` is the JSON Schema of its arguments; `run` gets them
- * parsed, but not checked against the schema, and returns what the model reads as the result.
+ * parsed, checked against the schema over MCP but not in the dock, and returns what the model reads as the result.
  */
 export type AssistantTool = {
   name: string;

package/dist/create-admin.js

@@ -77,6 +77,7 @@ import { createFilesRuntime } from "./files/runtime.js";
 import { fileRoutes } from "./files/routes.js";
 import { formRoutes } from "./forms/routes.js";
 import { createFormsRuntime } from "./forms/runtime.js";
+import { fieldDecrypter } from "./encryption/decrypt-field.js";
 import { createEncryptionRuntime } from "./encryption/runtime.js";
 import { functionRoutes } from "./functions/routes.js";
 import { supabaseFunctionRoutes } from "./functions/supabase-routes.js";
@@ -333,7 +334,8 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			db,
 			sql: options.mcp !== false && options.mcp?.sql === true,
 			writes,
-			commented
+			commented,
+			own: options.mcp !== false && options.mcp?.tools || []
 		});
 		const approvals = mcpApprovals();
 		const { resource } = auth.mcp;
@@ -373,6 +375,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			sessionToken: betterAuthSessionToken(auth)
 		}
 	});
+	const decryptField = fieldDecrypter(deps);
 	app.route("/", functionRoutes({
 		basePath: `${systemPath}/functions`,
 		functions: apiFunctions,
@@ -380,6 +383,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		access: deps.accessOptions,
 		db,
 		records: (session) => callerRecords(deps, session),
+		decryptField,
 		onError,
 		wake: () => wakeDispatch(deps),
 		upgradeWebSocket,
@@ -469,6 +473,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	});
 	return Object.assign(app, {
 		startRealtimePrune: prune,
+		decryptField,
 		jobs: [
 			...webhooks.jobs,
 			...withHistory && days !== void 0 ? [pruneHistoryJob(changes, days)] : [],

package/dist/encryption/decrypt-field-types.d.ts

@@ -0,0 +1,25 @@
+//#region src/encryption/decrypt-field-types.d.ts
+/** One record's key: its value, or its parts in the order of the resource's primary key. */
+export type RecordKey = string | number | readonly (string | number)[];
+/** Reads one encrypted field of one record as its cleartext, or `null` when it is empty. */
+export type DecryptField = (resource: string, key: RecordKey, field: string) => Promise<string | null>;
+/**
+ * Who reads, as the audit names them: a job, or a function with its caller and the request's origin (`AuditOrigin`).
+ * Filled in by the runtime, never by app code.
+ */
+export type FieldReader = {
+  job: string;
+} | {
+  function: string;
+  actor: {
+    id: string | number;
+    roles: string[];
+  };
+  origin: {
+    userAgent?: string;
+    forwardedFor?: string;
+  };
+};
+/** The app's server-side read of encrypted fields, for the reader the runtime names. */
+export type FieldDecrypter = (reader: FieldReader) => DecryptField;
+//#endregion

package/dist/encryption/decrypt-field.js

@@ -0,0 +1,63 @@
+import { readTransaction } from "../transactions.js";
+import { bindingOf } from "./binding.js";
+import { fetchRecord } from "../records.js";
+import { openText } from "./envelope-open.js";
+import { encodeKey } from "@protobase/schema/internal";
+//#region src/encryption/decrypt-field.ts
+const eventOf = (reader, base) => {
+	if ("job" in reader) return {
+		...base,
+		reader: { job: reader.job },
+		origin: {}
+	};
+	return {
+		...base,
+		actor: reader.actor,
+		reader: { function: reader.function },
+		origin: reader.origin
+	};
+};
+/**
+* The read `decryptField` of a job's and a protected function's context: privileged like their `db`, so no access rules
+* or tenant scope, of a live (not soft-deleted) record. It opens the value as the reveal does, then publishes a
+* `field.revealed` event naming the reader, and only returns the value once that is accepted: when publishing fails,
+* so does the read.
+*/
+const fieldDecrypter = (deps) => (reader) => async (resource, key, field) => {
+	const entry = deps.registry.find(resource);
+	if (!entry) throw new Error(`Unknown resource "${resource}"`);
+	const { model } = entry;
+	const target = Object.hasOwn(model.fields, field) ? model.fields[field] : void 0;
+	if (!target?.encrypted) throw new Error(`"${resource}.${field}" is not an encrypted field`);
+	if (!deps.encryption) throw new Error(`"${resource}" has encrypted fields but no encryption runtime`);
+	const parts = Array.isArray(key) ? key : [key];
+	if (parts.length !== model.primaryKey.length) throw new Error(`A ${resource} key has ${model.primaryKey.length} parts, not ${parts.length}`);
+	const tenantField = model.tenant && !model.primaryKey.includes(model.tenant) ? [model.tenant] : [];
+	const fields = [
+		...model.primaryKey,
+		...tenantField,
+		field
+	].map((name) => model.fields[name]);
+	const found = await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchRecord(trx, entry, parts, void 0, {
+		deleted: "hide",
+		fields
+	}));
+	if (!found) throw new Error(`No ${resource} with key "${encodeKey(parts)}"`);
+	const stored = found.record[field] ?? null;
+	const value = stored === null ? null : openText(deps.encryption.keyring, bindingOf(model, target, found.record), String(stored), {
+		resource,
+		field
+	});
+	const tenant = model.tenant ? found.record[model.tenant] : void 0;
+	await deps.audit.publish(eventOf(reader, {
+		type: "field.revealed",
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		...tenant !== void 0 && tenant !== null && { tenant },
+		resource,
+		recordKey: encodeKey(parts),
+		field
+	}));
+	return value;
+};
+//#endregion
+export { fieldDecrypter };

package/dist/encryption/envelope-open.js

@@ -42,7 +42,7 @@ const decrypt = (aes, aad, bytes) => {
 };
 /**
 * The plaintext of `stored`, sealed under `binding` with a key of `keyring`, or an `UnreadableValue` thrown with why it
-* does not open. The only place, with the CLI's status and apply, that decrypts.
+* does not open. The only place, with the CLI's status and apply and the audited `decryptField`, that decrypts.
 */
 const openText = (keyring, binding, stored, subject) => {
 	const parsed = parse(stored);

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

@@ -1,3 +1,4 @@
+import { DecryptField } from "../encryption/decrypt-field-types.js";
 import { Session } from "../types.js";
 import { Caller } from "../api-keys/resolve-caller.js";
 import { SocketEvents } from "./function-socket.js";
@@ -29,7 +30,14 @@ export type FunctionCaller = {
   records: FunctionRecords;
 };
 /** What a function that needs a signed-in caller gets: the caller resolved before it runs. */
-export type FunctionContext = PublicFunctionContext & FunctionCaller;
+export type FunctionContext = PublicFunctionContext & FunctionCaller & {
+  /**
+   * The cleartext of an `.encrypted()` field of one record, or `null` when it is empty: privileged like `db`, with no
+   * access rules or tenant scope. Each read is audited as a reveal, naming this function and its caller, and fails when
+   * the audit does. Not on a public function's context: a public function that needs a value enqueues a job.
+   */
+  decryptField: DecryptField;
+};
 /** What a function gets at `/api/sb/functions/v1/<name>`, where supabase-js calls it: the caller its keys and token make. */
 export type KeyFunctionContext = {
   name: string;

package/dist/functions/routes.js

@@ -1,5 +1,6 @@
 import { forbidden, notFound } from "../problem.js";
 import { namingTimeouts } from "../statement-timeout.js";
+import { auditOrigin } from "../audit/origin.js";
 import { invokeFunction } from "./define-function.js";
 import { runInBackground } from "../background-work.js";
 import { socketAcceptor } from "./accept-socket.js";
@@ -22,7 +23,7 @@ const isUpgrade = (request) => request.headers.get("upgrade")?.toLowerCase() ===
 * A function may answer an upgrade with a socket, only once it returned. While it is open, its caller is checked again
 * every minute: a protected function's always, a public one's once `caller()` resolved.
 */
-const functionRoutes = ({ basePath, functions, authenticate, access, db, records, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, report }) => {
+const functionRoutes = ({ basePath, functions, authenticate, access, db, records, decryptField, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, report }) => {
 	const app = new Hono().basePath(basePath);
 	app.onError(onError);
 	const sessionOf = (request) => isUpgrade(request) ? upgradeAuthenticate(request) : authenticate(request);
@@ -79,11 +80,21 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 				report,
 				recheck
 			});
+			const { user } = caller.session;
+			const reader = {
+				function: name,
+				actor: {
+					id: user.id,
+					roles: [...user.roles]
+				},
+				origin: auditOrigin(c.req.raw.headers)
+			};
 			const context = {
 				name,
 				db,
 				...caller,
 				caller: async () => caller,
+				decryptField: decryptField(reader),
 				acceptWebSocket: acceptor.accept
 			};
 			return acceptor.answer(name, await invokeFunction(name, fn, request, context));

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { AppIdentity } from "./app-identity.js";
 import { AppIcons, PngIcon, pngIcons } from "./web-app/app-icons.js";
 import { RealtimeOptions, relayed } from "./realtime/relay/realtime-options.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { DecryptField, FieldDecrypter, FieldReader, RecordKey } from "./encryption/decrypt-field-types.js";
 import { StandardSchema, readJson } from "./functions/read-json.js";
 import { MailMessage, Mailer } from "./mail/smtp-mailer.js";
 import { JsonObject, JsonValue } from "./notifications/json-value.js";
@@ -169,4 +170,4 @@ import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/ru
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, normalizeRoles } from "./better-auth/create-auth.js";
-export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DecryptField, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldDecrypter, type FieldReader, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKey, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/jobs/job-types.d.ts

@@ -1,3 +1,4 @@
+import { DecryptField } from "../encryption/decrypt-field-types.js";
 import { StandardSchema } from "../functions/read-json.js";
 import { Mailer } from "../mail/smtp-mailer.js";
 import { SendNotification } from "../notifications/send-input.js";
@@ -17,6 +18,11 @@ export type JobContext = {
   };
   /** Aborted when the job's timeout passes, or when the worker shuts down and its grace period ends. */
   signal: AbortSignal;
+  /**
+   * The cleartext of an `.encrypted()` field of one record, or `null` when it is empty: privileged like `db`, with no
+   * access rules or tenant scope. Each read is audited as a reveal, naming this job, and fails when the audit does.
+   */
+  decryptField: DecryptField;
   /** Sends mail with the app's mailer: its auth/mailer.ts, else the SMTP server of `PROTOBASE_SMTP_URL` and `PROTOBASE_MAIL_FROM`; `undefined` when the app has no mail. */
   mail?: Mailer;
   /** Sends a notification as `sendNotification` does; `undefined` when the app has no `notifications`. */

package/dist/jobs/run-job.js

@@ -49,11 +49,14 @@ const namedTimeout = (definition, error) => {
 	if (!isStatementTimeout(error)) return error;
 	return new Error(statementTimeoutDetail(`Job "${definition.name}"`, { kind: definition.options.longQueries ? "long" : "database" }), { cause: error });
 };
+const noDecrypter = (name) => async () => {
+	throw new Error(`Job "${name}" cannot decrypt fields: startJobs was not given the app's decryptField`);
+};
 /**
 * One try of one job: completed when `run` returns, failed (to be retried while attempts are left) when it throws, and
 * failed for good on a `FatalJobError` or an invalid payload.
 */
-const runJob = async (definition, job, db, { mail, sendNotification } = {}) => {
+const runJob = async (definition, job, db, { mail, sendNotification, decryptField } = {}) => {
 	try {
 		const payload = await checkPayload(definition, job.data ?? void 0);
 		const context = {
@@ -66,6 +69,7 @@ const runJob = async (definition, job, db, { mail, sendNotification } = {}) => {
 				startedOn: job.startedOn
 			},
 			signal: job.signal,
+			decryptField: decryptField ? decryptField({ job: definition.name }) : noDecrypter(definition.name),
 			...mail && { mail },
 			...sendNotification && { sendNotification }
 		};

package/dist/jobs/runtime.d.ts

@@ -1,3 +1,4 @@
+import { FieldDecrypter } from "../encryption/decrypt-field-types.js";
 import { Mailer } from "../mail/smtp-mailer.js";
 import { JobDefinition } from "./job-types.js";
 import { JobsEnqueuer } from "./current.js";
@@ -21,6 +22,8 @@ export type StartJobsOptions = {
    * `PROTOBASE_MAIL_FROM`, when set; `false` turns mail off whatever the environment says.
    */
   mailer?: Mailer | false;
+  /** The app's read of encrypted fields (`createAdmin(...).decryptField`), which each job's context binds to the job. */
+  decryptField?: FieldDecrypter;
 };
 /** What a drain left: whether no job is due or running any more, how many are, and when the next one is due. */
 export type DrainResult = {
@@ -31,8 +34,8 @@ export type DrainResult = {
 export type JobsRuntime = JobsEnqueuer & {
   /** Whether this process runs the jobs, or only enqueues them. */
   readonly works: boolean;
-  /** Takes the project's jobs again, as `protobase dev` does when their files change. */
-  update(jobs: JobDefinition[]): Promise<void>;
+  /** Takes the project's jobs again, as `protobase dev` does when their files change, with the rebuilt app's `decryptField`. */
+  update(jobs: JobDefinition[], decryptField?: FieldDecrypter): Promise<void>;
   /**
    * Runs the jobs that are due until none is due or running, or `seconds` have passed: for a host that wakes a sleeping
    * app to run its jobs. Needs this process to run jobs.
@@ -48,5 +51,5 @@ export type JobsRuntime = JobsEnqueuer & {
  * that retries jobs whose worker died. It reads the jobs schema, never changes it: check it first with
  * `checkJobsSchema`. Enqueueing through `defineJob(...).enqueue` reaches the runtime started here.
  */
-export declare const startJobs: ({ db, jobs, work, pollSeconds, shutdownSeconds, onError, now, mailer }: StartJobsOptions) => Promise<JobsRuntime>;
+export declare const startJobs: ({ db, jobs, work, pollSeconds, shutdownSeconds, onError, now, mailer, decryptField }: StartJobsOptions) => Promise<JobsRuntime>;
 //#endregion

package/dist/jobs/runtime.js

@@ -30,8 +30,9 @@ const createBoss = (db, work) => new PgBoss({
 * that retries jobs whose worker died. It reads the jobs schema, never changes it: check it first with
 * `checkJobsSchema`. Enqueueing through `defineJob(...).enqueue` reaches the runtime started here.
 */
-const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSeconds = 30, onError, now = () => /* @__PURE__ */ new Date(), mailer }) => {
+const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSeconds = 30, onError, now = () => /* @__PURE__ */ new Date(), mailer, decryptField }) => {
 	const mail = mailer === void 0 ? platformMailer() : mailer || void 0;
+	let decrypter = decryptField;
 	const database = busyDatabase(jobsDatabase(db));
 	const boss = createBoss(database.db, work);
 	boss.on("error", onError);
@@ -60,6 +61,7 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 				if (current.options.schedule !== void 0 && job.singletonKey === "protobase.schedule") await schedules.following(current, job.startAfter);
 				return [await runJob(current, job, db, {
 					mail,
+					...decrypter && { decryptField: decrypter },
 					...definitions.has("notifications.send") && { sendNotification }
 				})];
 			}, { longQueries: current.options.longQueries });
@@ -69,7 +71,8 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 			concurrency
 		});
 	};
-	const update = async (next) => {
+	const update = async (next, nextDecrypter) => {
+		if (nextDecrypter) decrypter = nextDecrypter;
 		for (const definition of next) await ensureQueue(definition);
 		for (const name of definitions.keys()) {
 			if (next.some((definition) => definition.name === name)) continue;

package/dist/mcp/mcp-authenticator.js

@@ -1,15 +1,15 @@
 import { isMcpWrites } from "./mcp-writes.js";
 //#region src/mcp/mcp-authenticator.ts
 const hasAudiences = (authenticate) => typeof authenticate.forAudience === "function";
-const isMcpOptions = (options) => options === void 0 || options === false || typeof options === "object" && options !== null && !Array.isArray(options) && Object.entries(options).every(([name, value]) => value === void 0 || name === "sql" && typeof value === "boolean" || name === "writes" && isMcpWrites(value));
+const isMcpOptions = (options) => options === void 0 || options === false || typeof options === "object" && options !== null && !Array.isArray(options) && Object.entries(options).every(([name, value]) => value === void 0 || name === "sql" && typeof value === "boolean" || name === "writes" && isMcpWrites(value) || name === "tools" && Array.isArray(value));
 /**
 * The authenticator of the MCP endpoint's tokens, when MCP is on (`auth.mcp`); none when the host serves its
 * own (`options.mcp: false`). Stops the server at startup when `options.mcp` is neither `false` nor
-* `{ sql?: boolean; writes?: boolean | { resources?: string[]; rolesWithoutApproval?: string[] } }`, when it is set without MCP, or when `authenticate` cannot verify tokens for
+* `{ sql?: boolean; writes?: boolean | { resources?: string[]; rolesWithoutApproval?: string[] }; tools?: AssistantTool[] }`, when it is set without MCP, or when `authenticate` cannot verify tokens for
 * another audience.
 */
 const mcpAuthenticator = (authenticate, mcp, options) => {
-	if (!isMcpOptions(options)) throw new Error("options.mcp takes false or { sql?: boolean, writes?: boolean | { resources?: [<resource>, ...], rolesWithoutApproval?: [<role>, ...] } }");
+	if (!isMcpOptions(options)) throw new Error("options.mcp takes false or { sql?: boolean, writes?: boolean | { resources?: [<resource>, ...], rolesWithoutApproval?: [<role>, ...] }, tools?: [<tool>, ...] }");
 	if (options === false) return void 0;
 	if (options && !mcp) throw new Error("mcpEndpoint needs auth.mcp in protobase.config.ts");
 	if (!mcp) return void 0;

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

@@ -18,6 +18,14 @@ export type McpToolsInput = {
    * those of them that `writes` lists when it lists some. None by default.
    */
   commented?: string[];
+  /** The app's own tools, offered to every caller after the built-in ones. */
+  own?: AssistantTool[];
 };
-export declare const mcpTools: ({ db, sql, writes, commented }: McpToolsInput) => (session: Session) => AssistantTool[];
+/**
+ * The MCP tools for a caller: the record tools, the write tools when `writes` is on, the comment tools when a resource
+ * takes comments, read-only SQL when `sql` is on and the caller sees the assistant, then the app's own tools. The
+ * tools are built once and only chosen per session: the MCP server compiles each tool's schema, and a schema object made
+ * per request would be compiled again.
+ */
+export declare const mcpTools: ({ db, sql, writes, commented, own }: McpToolsInput) => (session: Session) => AssistantTool[];
 //#endregion

package/dist/mcp/mcp-tools.js

@@ -1,16 +1,33 @@
 import { seesAssistant } from "../assistant/assistant-settings.js";
+import { checkedTools } from "../assistant/checked-tools.js";
 import { readOnlyQueryTool } from "../assistant/query-tools.js";
 import { readRecordTools } from "../assistant/record-tools.js";
 import { writeRecordTools } from "../assistant/write-record-tools.js";
 import { batchWriteTool } from "../assistant/batch-write-tool.js";
 import { commentTools } from "../assistant/comment-tools.js";
 //#region src/mcp/mcp-tools.ts
+const writeTools = (input) => [...writeRecordTools(input), batchWriteTool(input)];
+const builtInNames = (db) => new Set([
+	...readRecordTools(),
+	...writeTools({}),
+	...commentTools({ commented: ["comments"] }, {}),
+	readOnlyQueryTool(db)
+].map((tool) => tool.name));
+/** The app's own tools; one whose name is taken twice, or by a built-in tool, stops the server at startup. */
+const checkedOwnTools = (db, own) => {
+	const builtIn = builtInNames(db);
+	const taken = own.find((tool) => builtIn.has(tool.name));
+	if (taken) throw new Error(`The MCP tool "${taken.name}" has the name of a built-in MCP tool; give it another name`);
+	return checkedTools(own);
+};
 /**
-* The default MCP tools for a caller: the record tools, the write tools when `writes` is on, the comment tools when a
-* resource takes comments, and read-only SQL when `sql` is on and the caller sees the assistant.
+* The MCP tools for a caller: the record tools, the write tools when `writes` is on, the comment tools when a resource
+* takes comments, read-only SQL when `sql` is on and the caller sees the assistant, then the app's own tools. The
+* tools are built once and only chosen per session: the MCP server compiles each tool's schema, and a schema object made
+* per request would be compiled again.
 */
-const writeTools = (input) => [...writeRecordTools(input), batchWriteTool(input)];
-const mcpTools = ({ db, sql, writes, commented = [] }) => {
+const mcpTools = ({ db, sql, writes, commented = [], own = [] }) => {
+	const ownTools = checkedOwnTools(db, own);
 	const read = readRecordTools();
 	const limits = writes === false ? false : writes === true || !writes.resources ? {} : { resources: writes.resources };
 	const write = limits === false ? [] : writeTools(limits);
@@ -20,7 +37,8 @@ const mcpTools = ({ db, sql, writes, commented = [] }) => {
 		...read,
 		...write,
 		...comments,
-		...seesAssistant(session.user.roles) ? query : []
+		...seesAssistant(session.user.roles) ? query : [],
+		...ownTools
 	];
 };
 //#endregion

package/dist/package.js

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

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { FieldDecrypter } from "./encryption/decrypt-field-types.js";
 import { JobDefinition } from "./jobs/job-types.js";
 import { RealtimePrune } from "./realtime/realtime-prune.js";
 import { Hono } from "hono";
@@ -95,11 +96,18 @@ export type FieldRevealedEvent = {
   type: 'field.revealed';
   /** ISO 8601, when the server answered. */
   at: string;
-  actor: {
+  /** The caller; absent when a job read the value (`reader.job`). */
+  actor?: {
     id: string | number;
     roles: string[];
   };
-  /** The caller's tenant (organization), when the resource has one. */
+  /** The job or API function that read the value with `decryptField`; absent for a reveal. */
+  reader?: {
+    job: string;
+  } | {
+    function: string;
+  };
+  /** The caller's tenant (organization), or the record's for `decryptField`, when the resource has one. */
   tenant?: TenantValue;
   resource: string;
   /** The record's key as its URL has it (composite keys joined with a comma). */
@@ -137,11 +145,13 @@ export type PageSource = {
   toModel(): PageModel;
 };
 /**
- * The admin API, the jobs it needs a worker to run (the delivery of resource events), and the pruning of the realtime
- * tables a serving process starts once it listens and stops as it closes.
+ * The admin API, the jobs it needs a worker to run (the delivery of resource events), the pruning of the realtime
+ * tables a serving process starts once it listens and stops as it closes, and the read of encrypted fields that
+ * `startJobs` gives the jobs' context.
  */
 export type Admin = Hono<AdminEnv> & {
   jobs: JobDefinition[];
   startRealtimePrune: () => RealtimePrune;
+  decryptField: FieldDecrypter;
 };
 //#endregion

package/package.json

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