@protobase/server 0.62.4 → 0.63.0

package/dist/index.js

@@ -33,6 +33,7 @@ import { supabasePath } from "./supabase-paths.js";
 import { goTruePath } from "./gotrue/keys.js";
 import { defaultSignInPolicy, signInPolicyMethods } from "./better-auth/sign-in-policy.js";
 import { parseRoles } from "./better-auth/parse-roles.js";
+import { PersonalMailError } from "./personal-mail/personal-mail-error.js";
 import { passwordLength } from "./better-auth/new-account-password.js";
 import { readOperatorSettings } from "./better-auth/operator-provider.js";
 import { readPlatformSignIn } from "./better-auth/platform-sign-in.js";
@@ -67,6 +68,7 @@ import { historyIdPattern, historyLimits } from "./notifications/history.js";
 import { PushMessageError, maxTtlSeconds, pushMessage, urgencies } from "./notifications/message.js";
 import { NotificationSendError, maxMessageBytes, maxRecipients } from "./notifications/send-input.js";
 import { sendNotification } from "./notifications/send-notification.js";
+import { capSocketMessages, honorSocketMessageCaps, socketMessageCapOf } from "./functions/socket-message-cap.js";
 import { maxHistoryPage, maxUnreadCount } from "./notifications/history-store.js";
 import { generateVapidKeys } from "./notifications/web-push/keys.js";
 import { DeviceStoreError, postgresDeviceStore } from "./notifications/postgres-store.js";
@@ -88,7 +90,6 @@ import { localFileStore } from "./files/local-files.js";
 import { s3FileStore } from "./files/s3-files.js";
 import { storageProvider } from "./files/storage-provider.js";
 import { isBackgroundWork, runInBackground, wantsLongQueries } from "./background-work.js";
-import { capSocketMessages, honorSocketMessageCaps, socketMessageCapOf } from "./functions/socket-message-cap.js";
 import { mapSettings, mapStyleUrl, mapStyleVariable } from "./maps/map-settings.js";
 import { beforeSignInPluginsVariable, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
@@ -132,4 +133,4 @@ import { enqueueJob } from "./jobs/declared-job.js";
 import { defineEmail } from "./mail/define-email.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { ConnectionsBusy, DeviceStoreError, FatalJobError, HistoryStoreError, HttpProblem, MissingCredentials, ModelError, NotificationSendError, PushMessageError, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, callsMigration, capSocketMessages, changesMigration, channelSendsMigration, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkStatusSchema, 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, onDoNotDisturb, 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, refusalOf, refused, 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, sqlSends, startErrorReporting, startJobs, statusMigration, statusNames, 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 { ConnectionsBusy, DeviceStoreError, FatalJobError, HistoryStoreError, HttpProblem, MissingCredentials, ModelError, NotificationSendError, PersonalMailError, PushMessageError, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, callsMigration, capSocketMessages, changesMigration, channelSendsMigration, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkStatusSchema, 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, onDoNotDisturb, 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, refusalOf, refused, 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, sqlSends, startErrorReporting, startJobs, statusMigration, statusNames, 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,6 +1,6 @@
 import { DecryptField } from "../encryption/decrypt-field-types.js";
 import { StandardSchema } from "../functions/read-json.js";
-import { Mailer } from "../mail/smtp-mailer.js";
+import { Mailer } from "../mail/mail-message.js";
 import { SendNotification } from "../notifications/send-input.js";
 import { Db } from "@protobase/query";
 //#region src/jobs/job-types.d.ts

package/dist/jobs/runtime.d.ts

@@ -1,5 +1,5 @@
 import { FieldDecrypter } from "../encryption/decrypt-field-types.js";
-import { Mailer } from "../mail/smtp-mailer.js";
+import { Mailer } from "../mail/mail-message.js";
 import { JobDefinition } from "./job-types.js";
 import { JobsEnqueuer } from "./current.js";
 import { Db } from "@protobase/query";

package/dist/mail/composer-message.js

@@ -0,0 +1,27 @@
+//#region src/mail/composer-message.ts
+/**
+* `message` as Nodemailer composes it: its header fields checked, and its attachments as their bytes alone, with
+* Nodemailer's reads of a file path or URL turned off, so no attachment can name a file on the server or a URL to fetch.
+*/
+const composerMessage = ({ attachments, ...message }) => {
+	checkHeaders(message.headers);
+	if (!attachments?.length) return message;
+	return {
+		...message,
+		attachments: attachments.map(({ filename, content, contentType }) => ({
+			filename,
+			content: Buffer.from(content),
+			...contentType && { contentType }
+		})),
+		disableFileAccess: true,
+		disableUrlAccess: true
+	};
+};
+const checkHeaders = (headers = {}) => {
+	for (const [name, value] of Object.entries(headers)) {
+		if (!/^[!-9;-~]+$/.test(name)) throw new Error(`Mail header name "${name}" is not a valid header field name`);
+		if (/[\r\n]/.test(value)) throw new Error(`Mail header ${name} has a line break; a header value is one line`);
+	}
+};
+//#endregion
+export { composerMessage };

package/dist/mail/define-email.d.ts

@@ -1,4 +1,4 @@
-import { Mailer } from "./smtp-mailer.js";
+import { MailAttachment, Mailer } from "./mail-message.js";
 //#region src/mail/define-email.d.ts
 export type EmailOptions<Data extends object> = {
   /** Names the email in errors, such as `welcome` or `listing-alert`. */
@@ -32,10 +32,13 @@ export type EmailTemplate<Data extends object> = {
   render(data: Data): Promise<RenderedEmail>;
   /**
    * Renders the email for `data` and sends it to `to`: through `mailer` when given, such as a job's `context.mail`,
-   * otherwise through the app's SMTP server (`PROTOBASE_SMTP_URL`, `PROTOBASE_MAIL_FROM`). Rejects when mail is off
-   * or the server refuses the message.
+   * or a function's `context.personalMail`, the caller's own mailbox, otherwise through the app's SMTP server
+   * (`PROTOBASE_SMTP_URL`, `PROTOBASE_MAIL_FROM`), with the `attachments` given. Rejects when mail is off or the server
+   * refuses the message.
    */
-  send(to: string, data: Data, mailer?: Mailer): Promise<void>;
+  send(to: string, data: Data, mailer?: Mailer, extra?: {
+    attachments?: MailAttachment[];
+  }): Promise<void>;
 };
 /**
  * An email the app sends, with typed data: its subject and a React component for its body. Protobase renders it to

package/dist/mail/define-email.js

@@ -27,11 +27,12 @@ const defineEmail = (options) => {
 			...headers && { headers }
 		};
 	};
-	const send = async (to, data, mailer = platformMailer()) => {
+	const send = async (to, data, mailer = platformMailer(), { attachments } = {}) => {
 		if (!mailer) throw new Error(`Email "${options.name}" cannot be sent: mail is off; set ${smtpUrlVariable} and ${mailFromVariable}`);
 		await mailer.send({
 			to,
-			...await render(data)
+			...await render(data),
+			...attachments && attachments.length > 0 && { attachments }
 		});
 	};
 	return {

package/dist/mail/{smtp-mailer.d.ts → mail-message.d.ts}

@@ -1,4 +1,4 @@
-//#region src/mail/smtp-mailer.d.ts
+//#region src/mail/mail-message.d.ts
 export type MailMessage = {
   to: string;
   subject: string;
@@ -11,6 +11,14 @@ export type MailMessage = {
    * of bulk mail. A value is one line.
    */
   headers?: Record<string, string>;
+  /** Files sent with the message, such as an invoice's PDF. */
+  attachments?: MailAttachment[];
+};
+/** A file sent with a message: its name as the recipient sees it, its bytes, and its media type, else one its name implies. */
+export type MailAttachment = {
+  filename: string;
+  content: Uint8Array;
+  contentType?: string;
 };
 /** Sends one message; rejects when the server refuses it. */
 export type Mailer = {

package/dist/mail/smtp-mailer.js

@@ -1,3 +1,4 @@
+import { composerMessage } from "./composer-message.js";
 //#region src/mail/smtp-mailer.ts
 /**
 * Mail over SMTP with Nodemailer: the most used Node SMTP client, maintained, with no dependencies of its
@@ -10,14 +11,13 @@
 const smtpMailer = (settings) => {
 	let transport;
 	return { send: async (message) => {
-		checkHeaders(message.headers);
 		transport ??= import("nodemailer").then(({ createTransport }) => createTransport({
 			url: settings.smtpUrl,
 			name: senderDomain(settings.from)
 		}));
 		await (await transport).sendMail({
 			from: sender(settings),
-			...message
+			...composerMessage(message)
 		});
 	} };
 };
@@ -27,11 +27,5 @@ const sender = ({ from, name }) => name ? {
 } : from;
 /** The domain of a sender address `readMailSettings` accepted, so always a dotted hostname. */
 const senderDomain = (from) => from.slice(from.lastIndexOf("@") + 1);
-const checkHeaders = (headers = {}) => {
-	for (const [name, value] of Object.entries(headers)) {
-		if (!/^[!-9;-~]+$/.test(name)) throw new Error(`Mail header name "${name}" is not a valid header field name`);
-		if (/[\r\n]/.test(value)) throw new Error(`Mail header ${name} has a line break; a header value is one line`);
-	}
-};
 //#endregion
 export { smtpMailer };

package/dist/package.js

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

package/dist/personal-mail/gmail.js

@@ -0,0 +1,43 @@
+import { PersonalMailError } from "./personal-mail-error.js";
+import { rfc822Message } from "./rfc822-message.js";
+//#region src/personal-mail/gmail.ts
+/** The Gmail API's scope that sends mail and nothing else: no reading of the mailbox. */
+const gmailSendScope = "https://www.googleapis.com/auth/gmail.send";
+/** Its upload endpoint takes the message as it is, up to 35 MB, where the JSON one takes it base64-encoded. */
+const gmailSendUrl = "https://gmail.googleapis.com/upload/gmail/v1/users/me/messages/send?uploadType=media";
+/**
+* Gmail, linked through Google sign-in: offline access, so Google gives a refresh token, asked with `prompt=consent`
+* so it gives one again on a second link. Gmail sets the From header to the linked address.
+*/
+const gmail = (fetcher = (...args) => fetch(...args)) => ({
+	id: "gmail",
+	name: "Gmail",
+	signInProvider: "google",
+	scopes: [gmailSendScope],
+	linkParams: {
+		access_type: "offline",
+		prompt: "consent"
+	},
+	send: async (message, accessToken) => {
+		const body = await rfc822Message(message);
+		const response = await fetcher(gmailSendUrl, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${accessToken}`,
+				"content-type": "message/rfc822"
+			},
+			body: new Uint8Array(body)
+		});
+		if (response.ok) return;
+		if (response.status === 401 || response.status === 403 && await gmailReason(response) === "insufficientPermissions") throw new PersonalMailError("link_expired", "gmail");
+		throw new Error(`Gmail refused the message: ${response.status} ${response.statusText}`);
+	}
+});
+const gmailReason = async (response) => {
+	if (!response.headers.get("content-type")?.includes("json")) return;
+	const body = await response.json();
+	const reasons = [...body.error?.errors ?? [], ...body.error?.details ?? []].map((entry) => entry.reason);
+	return reasons.includes("insufficientPermissions") || reasons.includes("ACCESS_TOKEN_SCOPE_INSUFFICIENT") ? "insufficientPermissions" : reasons[0];
+};
+//#endregion
+export { gmail, gmailSendScope, gmailSendUrl };

package/dist/personal-mail/linked-accounts.js

@@ -0,0 +1,36 @@
+import { PersonalMailError } from "./personal-mail-error.js";
+import { APIError } from "better-auth/api";
+//#region src/personal-mail/linked-accounts.ts
+const storedScopes = (scope) => (scope ?? "").split(/[\s,]+/).filter(Boolean);
+/**
+* The accounts Better Auth keeps, with the tokens it stores, decrypted when `encryptOAuthTokens` is on. Its
+* `getAccessToken` refreshes a token within five seconds of expiry with the provider's refresh token and stores the new
+* one; when the provider refuses the refresh, as for a revoked grant, that is `link_expired`.
+*/
+const betterAuthLinkedAccounts = (auth) => ({
+	accounts: async (userId) => {
+		return (await (await auth.$context).internalAdapter.findAccounts(userId)).map((account) => ({
+			id: account.id,
+			providerId: account.providerId,
+			scopes: storedScopes(account.scope)
+		}));
+	},
+	accessToken: async (userId, account, provider) => {
+		const accessToken = await validAccessToken(auth, userId, account.id, provider);
+		if (!accessToken) throw new PersonalMailError("link_expired", provider);
+		return accessToken;
+	}
+});
+const validAccessToken = async (auth, userId, accountId, provider) => {
+	try {
+		return (await auth.api.getAccessToken({ body: {
+			accountId,
+			userId
+		} })).accessToken;
+	} catch (error) {
+		if (error instanceof APIError && error.body?.code === "FAILED_TO_GET_ACCESS_TOKEN") throw new PersonalMailError("link_expired", provider);
+		throw error;
+	}
+};
+//#endregion
+export { betterAuthLinkedAccounts };

package/dist/personal-mail/personal-mail-error.d.ts

@@ -0,0 +1,22 @@
+import { HttpProblem } from "../problem.js";
+//#region src/personal-mail/personal-mail-error.d.ts
+/**
+ * Why a message cannot go out from someone's own mailbox: `not_linked`, they linked no mail provider of the app's, or
+ * linked the sign-in account without allowing it to send mail; `link_expired`, the provider no longer honours the
+ * link, as when they revoked it or its refresh token expired, so they link it again.
+ */
+export type PersonalMailErrorCode = 'not_linked' | 'link_expired';
+/**
+ * Thrown when a message cannot go out from someone's own mailbox, and nothing was sent. Out of a function it answers as
+ * a 409 problem whose `code` and `provider` say which, so the app can offer to link the mailbox; in code,
+ * `error instanceof PersonalMailError` and its `code` tell.
+ */
+export declare class PersonalMailError extends HttpProblem {
+  readonly code: PersonalMailErrorCode;
+  /** The mail provider at fault, such as `gmail`; none when nothing is linked. */
+  readonly provider?: string | undefined;
+  constructor(code: PersonalMailErrorCode,
+  /** The mail provider at fault, such as `gmail`; none when nothing is linked. */
+  provider?: string | undefined);
+}
+//#endregion

package/dist/personal-mail/personal-mail-error.js

@@ -0,0 +1,25 @@
+import { HttpProblem } from "../problem.js";
+//#region src/personal-mail/personal-mail-error.ts
+const details = {
+	not_linked: "Link a mailbox to send mail from it",
+	link_expired: "The link to your mailbox has expired: link it again to send mail from it"
+};
+/**
+* Thrown when a message cannot go out from someone's own mailbox, and nothing was sent. Out of a function it answers as
+* a 409 problem whose `code` and `provider` say which, so the app can offer to link the mailbox; in code,
+* `error instanceof PersonalMailError` and its `code` tell.
+*/
+var PersonalMailError = class extends HttpProblem {
+	code;
+	provider;
+	constructor(code, provider) {
+		super(409, `personal-mail-${code.replace("_", "-")}`, "Conflict", details[code], {
+			code,
+			...provider && { provider }
+		});
+		this.code = code;
+		this.provider = provider;
+	}
+};
+//#endregion
+export { PersonalMailError };

package/dist/personal-mail/personal-mail-provider.d.ts

@@ -0,0 +1,25 @@
+import { MailMessage } from "../mail/mail-message.js";
+//#region src/personal-mail/personal-mail-provider.d.ts
+/**
+ * A mail provider people link their own mailbox with, through the app's sign-in provider of the same company: linking
+ * asks the sign-in provider for `scopes` with `linkParams`, the sign-in account Better Auth keeps holds the tokens, and
+ * `send` sends a message with its access token.
+ */
+export type PersonalMailProvider = {
+  /** Its id, such as `gmail`, as `auth.personalMail` names it. */
+  id: string;
+  /** The name the account page shows, such as `Gmail`. */
+  name: string;
+  /** The sign-in provider whose account holds the tokens, such as `google`: one of the app's `socialProviders`. */
+  signInProvider: string;
+  /** The scopes linking asks for, which the account must hold to send. */
+  scopes: string[];
+  /** More authorization parameters of the link, such as those that ask for a refresh token. */
+  linkParams: Record<string, string>;
+  /**
+   * Sends `message` from the mailbox. Rejects with a `PersonalMailError` of `link_expired` when the provider refuses the
+   * token, and with an error naming the status for anything else it refuses.
+   */
+  send: (message: MailMessage, accessToken: string) => Promise<void>;
+};
+//#endregion

package/dist/personal-mail/personal-mail-providers.d.ts

@@ -0,0 +1,8 @@
+import { PersonalMailProvider } from "./personal-mail-provider.js";
+//#region src/personal-mail/personal-mail-providers.d.ts
+/** The mail providers Protobase links mailboxes with, by the id `auth.personalMail` names them with. */
+export declare const personalMailProviders: {
+  gmail: (fetcher?: typeof fetch) => PersonalMailProvider;
+};
+export type PersonalMailProviderId = keyof typeof personalMailProviders;
+//#endregion

package/dist/personal-mail/personal-mail-providers.js

@@ -0,0 +1,16 @@
+import { gmail } from "./gmail.js";
+//#region src/personal-mail/personal-mail-providers.ts
+/** The mail providers Protobase links mailboxes with, by the id `auth.personalMail` names them with. */
+const personalMailProviders = { gmail };
+/**
+* The providers of `ids`, each checked against the app's sign-in providers: linking one goes through its sign-in
+* provider, so an app without it is a configuration error at startup.
+*/
+const resolvePersonalMail = (ids, signInProviders) => ids.map((id) => {
+	if (!Object.hasOwn(personalMailProviders, id)) throw new Error(`auth.personalMail: "${id}" is not a mail provider; use one of ${Object.keys(personalMailProviders).join(", ")}`);
+	const provider = personalMailProviders[id]();
+	if (!signInProviders.includes(provider.signInProvider)) throw new Error(`auth.personalMail: ${provider.name} links through the sign-in provider "${provider.signInProvider}"; add it to auth.socialProviders`);
+	return provider;
+});
+//#endregion
+export { personalMailProviders, resolvePersonalMail };

package/dist/personal-mail/personal-mailer.js

@@ -0,0 +1,26 @@
+import { PersonalMailError } from "./personal-mail-error.js";
+//#region src/personal-mail/personal-mailer.ts
+/** The mail provider `userId` linked, of the app's `providers` in their order, with the account that holds its tokens. */
+const linkedProvider = async (accounts, providers, userId) => {
+	const linked = await accounts.accounts(userId);
+	for (const provider of providers) {
+		const account = linked.find((candidate) => candidate.providerId === provider.signInProvider && provider.scopes.every((scope) => candidate.scopes.includes(scope)));
+		if (account) return {
+			provider,
+			account
+		};
+	}
+};
+/**
+* Mail from `userId`'s own mailbox: each message goes out through the mail provider they linked, with an access token
+* refreshed when it expired. Rejects with a `PersonalMailError` and sends nothing when they linked none (`not_linked`)
+* or the provider no longer honours the link (`link_expired`).
+*/
+const personalMailer = (accounts, providers, userId) => ({ send: async (message) => {
+	const linked = await linkedProvider(accounts, providers, userId);
+	if (!linked) throw new PersonalMailError("not_linked");
+	const accessToken = await accounts.accessToken(userId, linked.account, linked.provider.id);
+	await linked.provider.send(message, accessToken);
+} });
+//#endregion
+export { linkedProvider, personalMailer };

package/dist/personal-mail/rfc822-message.js

@@ -0,0 +1,15 @@
+import { composerMessage } from "../mail/composer-message.js";
+//#region src/personal-mail/rfc822-message.ts
+/**
+* `message` as an RFC 5322 message, attachments and all, the way the SMTP mailer composes it, with Nodemailer's
+* composer. Without `from`, the provider fills in the From header with the mailbox it sends from.
+*/
+const rfc822Message = async (message, from) => {
+	const { default: MailComposer } = await import("nodemailer/lib/mail-composer");
+	return new MailComposer({
+		...from && { from },
+		...composerMessage(message)
+	}).compile().build();
+};
+//#endregion
+export { rfc822Message };

package/package.json

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