@protobase/server 0.57.6 → 0.58.0

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";
@@ -373,6 +374,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 +382,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 +472,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/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.57.6";
+var version = "0.58.0";
 //#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.0",
   "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.0",
+    "@protobase/query": "0.58.0",
+    "@protobase/schema": "0.58.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",