@protobase/server 0.62.4 → 0.63.0

package/dist/calls/guest-routes.js

@@ -0,0 +1,97 @@
+import { HttpProblem, forbidden, notFound, unauthorized } from "../problem.js";
+import { socketAcceptor } from "../functions/accept-socket.js";
+import { allowedOrigin } from "../functions/upgrade-caller.js";
+import { guestLimits } from "./guest-limits.js";
+import { guestName } from "./guest-name.js";
+import { guestTokenPrefix, linkTokenPrefix, newToken, tokenHash } from "./guest-tokens.js";
+import { guestSocket } from "./guest-socket.js";
+import { Hono } from "hono";
+//#region src/calls/guest-routes.ts
+const noStore = { "Cache-Control": "no-store" };
+const tooMany = () => new HttpProblem(429, "too-many-requests", "Too Many Requests", "Too many tries: wait a minute", {}, { "retry-after": "60" });
+const noLobby = () => notFound("This link lets nobody into a call");
+const bearer = (c) => c.req.header("authorization")?.match(/^Bearer (.+)$/)?.[1];
+/**
+* The guests' routes, mounted at `guestCallsPath` before the API's authenticator, which takes none of their tokens,
+* as no route but these takes them:
+* - `POST /lobby` with `{ link, name }`: the guest waits in the lobby of the link's call; `201 { guest, token }`.
+* - `GET /lobby` with `Authorization: Bearer <token>`: `{ state }`, with `call` and `publish` once let in.
+* - `DELETE /lobby`: the waiting guest leaves.
+* - `GET /socket`: the guest's call socket (see `guestSocket`).
+* Each address may enter `entriesPerMinute` times a minute, and is answered 429 for the rest of the minute after
+* `refusalsPerMinute` unknown or refused tokens; each guest asks after their wait `pollsPerMinute` times at most.
+*/
+const guestRoutes = ({ calls, addressOf, origins, upgradeWebSocket, onError, report }) => {
+	const app = new Hono();
+	app.onError(onError);
+	const limits = guestLimits();
+	const address = (c) => addressOf(c.req.raw) ?? "no-trusted-address";
+	const open = (c) => {
+		const at = address(c);
+		if (limits.blocked(at)) throw tooMany();
+		return at;
+	};
+	const guestToken = (c, at) => {
+		const hash = tokenHash(guestTokenPrefix, bearer(c));
+		if (!hash) {
+			limits.refused(at);
+			throw unauthorized("Send the token the lobby gave you");
+		}
+		if (!limits.poll(hash.toString("hex"))) throw tooMany();
+		return hash;
+	};
+	app.post("/lobby", async (c) => {
+		const at = open(c);
+		const body = await c.req.json().catch(() => void 0);
+		if (!limits.enter(at)) throw tooMany();
+		const name = guestName(body?.name);
+		const link = tokenHash(linkTokenPrefix, body?.link);
+		if (!link) {
+			limits.refused(at);
+			throw noLobby();
+		}
+		const token = newToken(guestTokenPrefix);
+		const entered = await (await calls.runtime()).guests().enter({
+			link,
+			name,
+			token: tokenHash(guestTokenPrefix, token)
+		});
+		if ("refused" in entered) {
+			limits.refused(at);
+			throw noLobby();
+		}
+		return c.json({
+			guest: entered.guest,
+			token
+		}, 201, noStore);
+	});
+	app.get("/lobby", async (c) => {
+		const at = open(c);
+		const hash = guestToken(c, at);
+		const state = await (await calls.runtime()).guests().state(hash);
+		if (!state) {
+			limits.refused(at);
+			throw unauthorized("This token lets nobody into a call");
+		}
+		return c.json(state, 200, noStore);
+	});
+	app.delete("/lobby", async (c) => {
+		const at = open(c);
+		await (await calls.runtime()).guests().leave(guestToken(c, at));
+		return c.body(null, 204);
+	});
+	app.get("/socket", async (c) => {
+		const at = open(c);
+		if (!allowedOrigin(c.req.raw, origins)) throw forbidden("foreign-origin", "This page’s origin may not open a socket to this app");
+		const runtime = await calls.runtime();
+		const acceptor = socketAcceptor({
+			c,
+			upgradeWebSocket,
+			report
+		});
+		return acceptor.answer("guest call", acceptor.accept(guestSocket(runtime, () => limits.refused(at))));
+	});
+	return app;
+};
+//#endregion
+export { guestRoutes };

package/dist/calls/guest-socket.js

@@ -0,0 +1,58 @@
+import { forbidden } from "../problem.js";
+import { parseClientMessage } from "./client-message.js";
+import { guestTokenPrefix, tokenHash } from "./guest-tokens.js";
+//#region src/calls/guest-socket.ts
+/** How long a guest's socket may stay open before its first message names the guest, in milliseconds. */
+const guestFirstMessageMs = 1e4;
+const refusedCloseCode = 1008;
+const maxMessageBytes = 307200;
+/**
+* A guest's call socket: open to anyone, it lets in only a guest whose first message, their `join` or `resume`, carries
+* the token of a guest a member let in who may still be in the call. From then on it is a member's socket, as `guest:<id>` in their link's call,
+* checked every minute: removed, their link revoked or expired, guests turned off or the call ended closes it. A
+* socket that names no such guest, or none in time, closes with 1008 and `refused` (the address is counted).
+*/
+const guestSocket = (runtime, refused) => {
+	let socket;
+	let relay;
+	let guest;
+	let timer;
+	const refuse = () => {
+		refused();
+		socket.send(JSON.stringify({
+			type: "left",
+			reason: "refused"
+		}));
+		socket.close(refusedCloseCode, "Not let into this call");
+	};
+	const first = async (data) => {
+		clearTimeout(timer);
+		const message = parseClientMessage(data);
+		const hash = message && (message.type === "join" || message.type === "resume") ? tokenHash(guestTokenPrefix, message.guest) : void 0;
+		const row = hash && await runtime.guests().byToken(hash);
+		if (!row || row.admitted !== true || !await runtime.guests().stillAllowed(row.id)) return refuse();
+		guest = row.id;
+		relay = await runtime.relayGuest(row);
+		await relay.onOpen?.(socket);
+		await relay.onMessage?.(data, socket);
+	};
+	return {
+		maxMessageBytes,
+		onOpen: (opened) => {
+			socket = opened;
+			timer = setTimeout(refuse, guestFirstMessageMs);
+			timer.unref?.();
+		},
+		onMessage: (data) => relay ? relay.onMessage?.(data, socket) : first(data),
+		onClose: (code, reason) => {
+			clearTimeout(timer);
+			return relay?.onClose?.(code, reason);
+		},
+		recheck: async () => {
+			if (guest === void 0) return;
+			if (!await runtime.guests().stillAllowed(guest)) throw forbidden("guest-not-allowed", "This guest may no longer be in the call");
+		}
+	};
+};
+//#endregion
+export { guestFirstMessageMs, guestSocket };

package/dist/calls/guest-store.d.ts

@@ -0,0 +1,48 @@
+import { GuestRow } from "./guest-checks-sql.js";
+import { CreateLinkInput } from "./guest-links-sql.js";
+import { DecideInput, LobbyState } from "./guest-lobby-sql.js";
+import { CallGuestLink, CallGuestRefusal, CallLobbyGuest } from "@protobase/schema/internal";
+import { Db } from "@protobase/query";
+//#region src/calls/guest-store.d.ts
+/** Where guest links, the lobby's guests and the organizations' switch are kept: the `calls` schema. */
+export type GuestStore = {
+  createLink: (input: CreateLinkInput) => Promise<{
+    link: CallGuestLink;
+    token: string;
+  } | {
+    refused: CallGuestRefusal;
+  }>;
+  revokeLink: (input: {
+    call: string;
+    link: string;
+    member: string;
+  }) => Promise<boolean>;
+  decide: (input: DecideInput) => Promise<{
+    refused?: CallGuestRefusal;
+  }>;
+  lobbies: (calls: readonly string[]) => Promise<Map<string, {
+    guests: CallLobbyGuest[];
+    links: CallGuestLink[];
+  }>>;
+  enter: (input: {
+    link: Buffer;
+    name: string;
+    token: Buffer;
+  }) => Promise<{
+    guest: string;
+  } | {
+    refused: 'gone';
+  }>;
+  state: (token: Buffer) => Promise<LobbyState | undefined>;
+  leave: (token: Buffer) => Promise<void>;
+  byToken: (token: Buffer) => Promise<GuestRow | undefined>;
+  stillAllowed: (guest: string) => Promise<boolean>;
+  /** The calls whose guests turning guests off took out. */
+  setOrganization: (input: {
+    organization: string;
+    allowed: boolean;
+    by: string;
+  }) => Promise<string[]>;
+  organizationAllowed: (organization: string) => Promise<boolean>;
+};
+//#endregion

package/dist/calls/guest-store.js

@@ -0,0 +1,20 @@
+import { guestByToken, guestStillAllowed } from "./guest-checks-sql.js";
+import { createLink, organizationGuests, revokeLink, setOrganizationGuests } from "./guest-links-sql.js";
+import { decideGuest, enterLobby, leaveLobby, lobbies, lobbyState } from "./guest-lobby-sql.js";
+//#region src/calls/guest-store.ts
+/** The `calls` schema of the app's database; writes under the API's statement timeout. */
+const sqlGuestStore = (db, timeoutMs, organizationOf) => ({
+	createLink: (input) => createLink(db, timeoutMs, organizationOf, input),
+	revokeLink: (input) => revokeLink(db, timeoutMs, input),
+	decide: (input) => decideGuest(db, timeoutMs, input),
+	lobbies: (calls) => lobbies(db, calls),
+	enter: (input) => enterLobby(db, timeoutMs, input),
+	state: (token) => lobbyState(db, token),
+	leave: (token) => leaveLobby(db, token),
+	byToken: (token) => guestByToken(db, token),
+	stillAllowed: (guest) => guestStillAllowed(db, guest),
+	setOrganization: (input) => setOrganizationGuests(db, timeoutMs, input),
+	organizationAllowed: (organization) => organizationGuests(db, organization)
+});
+//#endregion
+export { sqlGuestStore };

package/dist/calls/guest-tokens.js

@@ -0,0 +1,17 @@
+import { createHash, randomBytes } from "node:crypto";
+//#region src/calls/guest-tokens.ts
+/** What starts a guest link's token, and a guest's: neither is ever a session token, a JWT or an API key. */
+const linkTokenPrefix = "pbgl_";
+const guestTokenPrefix = "pbg_";
+/** A new token, 32 random bytes in base64url after its prefix. */
+const newToken = (prefix) => `${prefix}${randomBytes(32).toString("base64url")}`;
+/** The SHA-256 a token is stored and looked up by; `undefined` for a value that is no token of this kind. */
+const tokenHash = (prefix, token) => {
+	if (typeof token !== "string" || !token.startsWith(prefix) || token.length !== prefix.length + 43) return;
+	return createHash("sha256").update(token).digest();
+};
+/** The member a guest is in their call: no `calls.join` takes a member of this form. */
+const guestMember = (guest) => `guest:${guest}`;
+const isGuestMember = (member) => member.startsWith("guest:");
+//#endregion
+export { guestMember, guestTokenPrefix, isGuestMember, linkTokenPrefix, newToken, tokenHash };

package/dist/calls/member-relay.js

@@ -1,9 +1,11 @@
-import { memberEnd } from "./close-codes.js";
 import { parseClientMessage } from "./client-message.js";
+import { memberEnd } from "./close-codes.js";
 //#region src/calls/member-relay.ts
 /** The close code of a socket whose caller Protobase refused: the member leaves the call too. */
 const refusedCloseCode = 1008;
 const mayPublish = (rights, tracks) => rights.publish === true || Array.isArray(rights.publish) && tracks.every((track) => rights.publish.includes(track.source));
+const guestSources = (rights, asked) => [...new Set(asked)].filter((source) => rights.publish === true || Array.isArray(rights.publish) && rights.publish.includes(source));
+const isGuestMessage = (message) => message.type.startsWith("guest-");
 const refusals = {
 	removed: "You were removed from this call",
 	full: "This call is full",
@@ -15,7 +17,7 @@ const refusals = {
 * may not make, and tells the call and the plugin how the socket ended. The plugin only ever sees well-formed messages
 * of a member Protobase let in.
 */
-const memberRelay = ({ door, backend, record, member, rights, maxMembers, maxMinutes, report, user, ring }) => {
+const memberRelay = ({ door, backend, record, member, rights, maxMembers, maxMinutes, report, user, ring, invites = false, name, guest }) => {
 	let browser;
 	let session;
 	let inCall;
@@ -49,14 +51,20 @@ const memberRelay = ({ door, backend, record, member, rights, maxMembers, maxMin
 				muted: false
 			}))
 		} : void 0;
+		const more = {
+			...user !== void 0 && { user },
+			...ring && !resume && { ring },
+			...invites && { invites },
+			...name !== void 0 && { name },
+			...guest && { guest }
+		};
 		const admitted = await door.admit({
 			record,
 			member,
 			maxMembers,
 			maxMinutes,
 			...resume && { resume },
-			...user !== void 0 && { user },
-			...ring && !resume && { ring }
+			...more
 		}, {
 			send,
 			close
@@ -80,9 +88,59 @@ const memberRelay = ({ door, backend, record, member, rights, maxMembers, maxMin
 		await session.receive(message);
 		await admitted.listen(session.roster ?? (() => {}));
 	};
+	const guests = async (message, call) => {
+		const actions = door.guests;
+		if (!invites || !actions) return send({
+			type: "guest-refused",
+			reason: "not-allowed"
+		});
+		switch (message.type) {
+			case "guest-link": {
+				const made = await actions.link({
+					call,
+					member,
+					publish: guestSources(rights, message.publish),
+					...message.expires_at && { expiresAt: new Date(message.expires_at) }
+				});
+				if ("refused" in made) return send({
+					type: "guest-refused",
+					reason: made.refused
+				});
+				return send({
+					type: "guest-link",
+					link: made.link,
+					token: made.token
+				});
+			}
+			case "guest-link-revoke": return send(await actions.revoke({
+				call,
+				link: message.link,
+				member
+			}) ? { type: "guest-done" } : {
+				type: "guest-refused",
+				reason: "gone"
+			});
+			case "guest-decide": {
+				const decided = await actions.decide({
+					call,
+					guest: message.guest,
+					member,
+					admit: message.admit
+				});
+				return send(decided.refused ? {
+					type: "guest-refused",
+					reason: decided.refused
+				} : { type: "guest-done" });
+			}
+			case "guest-remove":
+				await actions.remove(call, message.guest);
+				return send({ type: "guest-done" });
+		}
+	};
 	const relay = async (message) => {
 		if (message.type === "join" || message.type === "resume") return enter(message);
-		if (!session) return close(refusedCloseCode, "Join or resume the call first");
+		if (!session || !inCall) return close(refusedCloseCode, "Join or resume the call first");
+		if (isGuestMessage(message)) return guests(message, inCall.call);
 		if (message.type === "publish" && !mayPublish(rights, message.tracks)) return send({
 			type: "publish-refused",
 			reason: "The member may not publish these tracks"

package/dist/calls/organization-guests-route.js

@@ -0,0 +1,38 @@
+import { badRequest, forbidden } from "../problem.js";
+import { Hono } from "hono";
+//#region src/calls/organization-guests-route.ts
+const organizationOf = (session) => {
+	if (session.anonymous || session.client || session.organization === void 0) throw forbidden("organization-required", "Sign in and work in an organization first");
+	return String(session.organization.id);
+};
+/**
+* Whether the calls of the organization the user works in take guests, mounted behind the API's authenticator: `GET /`
+* `{ allowed }` for any member, `PUT /` with `{ allowed }` for its owner or an admin. Turning guests off revokes every
+* guest link of the organization's calls and takes their guests out at once.
+*/
+const organizationGuestsRoute = ({ calls, roleIn }) => {
+	const app = new Hono();
+	app.get("/", async (c) => {
+		const session = c.get("session");
+		const organization = organizationOf(session);
+		if (!await roleIn(organization, String(session.user.id))) throw forbidden("not-a-member", "You are not a member of this organization");
+		return c.json({ allowed: await (await calls.runtime()).guests().organizationAllowed(organization) }, 200, { "Cache-Control": "no-store" });
+	});
+	app.put("/", async (c) => {
+		const session = c.get("session");
+		const organization = organizationOf(session);
+		const role = await roleIn(organization, String(session.user.id));
+		if (role !== "owner" && role !== "admin") throw forbidden("organization-admin-required", "Only an owner or admin of the organization turns guest links on or off");
+		const body = await c.req.json().catch(() => void 0);
+		if (typeof body?.allowed !== "boolean") throw badRequest("allowed-required", "Send { allowed: true } or { allowed: false }");
+		await (await calls.runtime()).setOrganizationGuests({
+			organization,
+			allowed: body.allowed,
+			by: String(session.user.id)
+		});
+		return c.json({ allowed: body.allowed });
+	});
+	return app;
+};
+//#endregion
+export { organizationGuestsRoute };

package/dist/calls/record-organization.js

@@ -0,0 +1,24 @@
+import { decodeKey } from "@protobase/schema/internal";
+import { sql } from "kysely";
+//#region src/calls/record-organization.ts
+/**
+* The organization a call's record is in, read from the record's own tenant field with no access check: `null` for a
+* record of a resource without a tenant, or one that is gone, which no organization's switch covers. A key of a relation
+* to a resource with a key of several fields is read as none either, so its calls take no guests.
+*/
+const recordOrganization = (registry) => async (trx, record) => {
+	const entry = registry.find(record.resource);
+	const tenant = entry?.model.tenant;
+	if (!entry || !tenant) return null;
+	const { model } = entry;
+	const decoded = decodeKey(record.key, entry.keyTypes);
+	const values = Array.isArray(decoded) ? decoded : [decoded];
+	if (values.length !== model.primaryKey.length) return null;
+	const table = model.table.schema ? sql.id(model.table.schema, model.table.name) : sql.id(model.table.name);
+	const where = sql.join(model.primaryKey.map((name, index) => sql`${sql.id(model.fields[name].column)} = ${values[index]}`), sql` and `);
+	const { rows } = await sql`select ${sql.id(model.fields[tenant].column)} as tenant from ${table} where ${where}`.execute(trx);
+	const found = rows[0]?.tenant;
+	return found === void 0 || found === null ? null : String(found);
+};
+//#endregion
+export { recordOrganization };

package/dist/create-admin.js

@@ -61,6 +61,10 @@ import { webhookTable } from "./webhooks/table/webhook-table.js";
 import { subscriptionUrlCheck, subscriptionWriteCheck } from "./webhooks/table/validate-hook.js";
 import { callsService } from "./calls/calls-service.js";
 import { ringRoutes } from "./calls/ring-routes.js";
+import { upgradeAuthenticator } from "./functions/upgrade-caller.js";
+import { guestRoutes } from "./calls/guest-routes.js";
+import { organizationGuestsRoute } from "./calls/organization-guests-route.js";
+import { organizationRole } from "./better-auth/organizations/organization-role.js";
 import { deviceStore, removeDevicesWithUsers } from "./notifications/device-store-of.js";
 import { historyStore, removeHistoryWithUsers } from "./notifications/history-store-of.js";
 import { devicesPath, historyPath } from "./notifications/paths.js";
@@ -91,7 +95,6 @@ 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";
-import { upgradeAuthenticator } from "./functions/upgrade-caller.js";
 import { localeSetting } from "./locale/locale-option.js";
 import { requestLocale } from "./locale/request-locale.js";
 import { mapSettings } from "./maps/map-settings.js";
@@ -112,7 +115,8 @@ import { createScanGuard } from "./scan-guard.js";
 import { failedJobs, failedJobsView } from "./jobs/failed-jobs.js";
 import { Hono } from "hono";
 import { accountPage, accountPageName, checkPages, settingsResources, withSettingsFields } from "@protobase/layout";
-import { ringsPath, statusPath } from "@protobase/schema/internal";
+import { guestCallsPath, ringsPath, statusPath } from "@protobase/schema/internal";
+import { getIP } from "better-auth/api";
 //#region src/create-admin.ts
 const declaredRoles = (auth, roles) => {
 	const names = [...auth?.roles ?? [], ...Object.keys(roles?.definitions ?? {})];
@@ -270,6 +274,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			notices: changes,
 			channels: () => channels,
 			notifications: Boolean(notifications),
+			organizations: Boolean(auth?.organizations),
 			...auth?.origins[0] && { origin: auth.origins[0] },
 			...statusTables && { doNotDisturb: (ringDb, userIds) => onDoNotDisturb(ringDb, statusTables.statuses, userIds) }
 		}) }
@@ -414,6 +419,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		records: (session) => callerRecords(deps, session),
 		channels,
 		decryptField,
+		...auth && auth.personalMail.length > 0 && { personalMailer: auth.personalMailer },
 		onError,
 		wake: () => wakeDispatch(deps),
 		upgradeWebSocket,
@@ -469,6 +475,21 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	}
 	if (statusTables) app.route(statusPath(systemPath), guarded((routes) => void routes.route("/", statusRoutes(db, statusTables))));
 	if (deps.calls) app.route(ringsPath(systemPath), guarded((routes) => void routes.route("/", ringRoutes(deps.calls))));
+	if (deps.calls && auth) {
+		const addressOf = (request) => getIP(request, auth.options);
+		app.route(guestCallsPath(systemPath), guestRoutes({
+			calls: deps.calls,
+			addressOf,
+			origins: auth.origins,
+			onError,
+			...upgradeWebSocket && { upgradeWebSocket },
+			report
+		}));
+		if (auth.organizations) app.route(guestCallsPath(systemPath, "organization"), guarded((routes) => void routes.route("/", organizationGuestsRoute({
+			calls: deps.calls,
+			roleIn: organizationRole(auth)
+		}))));
+	}
 	if (forms) app.route(`${systemPath}/forms`, formRoutes(deps, forms));
 	const feed = tableFeed({
 		db,

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

@@ -1,4 +1,5 @@
 import { DecryptField } from "../encryption/decrypt-field-types.js";
+import { Mailer } from "../mail/mail-message.js";
 import { Session } from "../types.js";
 import { Caller } from "../api-keys/resolve-caller.js";
 import { SocketEvents } from "./function-socket.js";
@@ -43,6 +44,15 @@ export type FunctionContext = PublicFunctionContext & FunctionCaller & {
    * the audit does. Not on a public function's context: a public function that needs a value enqueues a job.
    */
   decryptField: DecryptField;
+  /**
+   * Mail from the caller's own mailbox, through the mail provider they linked (`auth.personalMail`), attachments and
+   * all: `personalMail.send({ to, subject, text, html, attachments })`, or an email template's `send(to, data,
+   * context.personalMail, { attachments })`. Rejects with a `PersonalMailError`, sending nothing, when they linked no
+   * mailbox (`not_linked`) or the link no longer works (`link_expired`); thrown on, it answers as a 409 problem with
+   * that `code`. Only someone signed in as themselves sends from their mailbox: staff signed in as them, or an outside
+   * app acting for them, is refused with a 403 problem. Not on a public function's context.
+   */
+  personalMail: Mailer;
 };
 /** 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 = {

package/dist/functions/own-mailbox.js

@@ -0,0 +1,9 @@
+import { ownSignInUser } from "../notifications/caller.js";
+//#region src/functions/own-mailbox.ts
+/**
+* The caller's own mailbox: mail goes out from it only for someone signed in as themselves. Staff signed in as them,
+* an outside app acting for them and a visitor are refused with a 403 problem, sending nothing.
+*/
+const ownMailbox = (session, personalMailer) => ({ send: async (message) => personalMailer(ownSignInUser(session, "send mail from their own mailbox")).send(message) });
+//#endregion
+export { ownMailbox };

package/dist/functions/routes.js

@@ -2,9 +2,10 @@ 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 { socketAcceptor } from "./accept-socket.js";
 import { runInBackground } from "../background-work.js";
 import { callsAccess } from "../calls/calls-access.js";
-import { socketAcceptor } from "./accept-socket.js";
+import { ownMailbox } from "./own-mailbox.js";
 import { functionGate, requireGate } from "./function-gate.js";
 import { sameCaller } from "./same-caller.js";
 import { Hono } from "hono";
@@ -15,6 +16,7 @@ const relativeRequest = (request, prefix) => {
 	url.pathname = url.pathname.slice(prefix.length) || "/";
 	return new Request(url, request);
 };
+const noPersonalMail = () => ({ send: () => Promise.reject(/* @__PURE__ */ new Error("Personal mail is off: name the mail providers people may link in auth.personalMail, such as [\"gmail\"]")) });
 const isUpgrade = (request) => request.headers.get("upgrade")?.toLowerCase() === "websocket";
 /**
 * Every function at `<basePath>/<name>` and below, any method. A protected function authenticates the request first, so
@@ -24,7 +26,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, channels, decryptField, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, calls, report }) => {
+const functionRoutes = ({ basePath, functions, authenticate, access, db, records, channels, decryptField, personalMailer = noPersonalMail, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, calls, report }) => {
 	const app = new Hono().basePath(basePath);
 	app.onError(onError);
 	const sessionOf = (request) => isUpgrade(request) ? upgradeAuthenticate(request) : authenticate(request);
@@ -99,6 +101,7 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 				...caller,
 				caller: async () => caller,
 				decryptField: decryptField(reader),
+				personalMail: ownMailbox(caller.session, personalMailer),
 				acceptWebSocket: acceptor.accept,
 				calls: callsAccess(calls, async () => caller)
 			};

package/dist/functions/upgrade-caller.js

@@ -22,4 +22,4 @@ const upgradeAuthenticator = ({ authenticate, origins, sessionToken }) => async
 	return authenticate(new Request(request, { headers }));
 };
 //#endregion
-export { upgradeAuthenticator };
+export { allowedOrigin, upgradeAuthenticator };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { RealtimeOptions, relayed, sqlSends } from "./realtime/relay/realtime-op
 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 { MailAttachment, MailMessage, Mailer } from "./mail/mail-message.js";
 import { JsonObject, JsonValue } from "./notifications/json-value.js";
 import { HistoryPosition, NewNotification, StoredNotification, historyIdPattern, historyLimits } from "./notifications/history.js";
 import { PushMessage, PushMessageError, Urgency, WebPushFields, maxTtlSeconds, pushMessage, urgencies } from "./notifications/message.js";
@@ -175,9 +175,11 @@ import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js
 import { FatalJobError } from "./jobs/run-job.js";
 import { ArgumentsPayload, EnqueueJob, JobDeclaration, JobName, JobPayload, JobRun, enqueueJob } from "./jobs/declared-job.js";
 import { isSchedule } from "./jobs/schedule.js";
+import { PersonalMailError, PersonalMailErrorCode } from "./personal-mail/personal-mail-error.js";
+import { PersonalMailProviderId } from "./personal-mail/personal-mail-providers.js";
 import { EmailComponent, EmailOptions, EmailTemplate, RenderedEmail, defineEmail } from "./mail/define-email.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
 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 BaseToolContext, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type CallBackend, type CallMember, type Caller, type CallerOptions, type CallsAccess, type CallsOptions, type CapturedRow, type CascadingKey, type ChannelBroadcast, type ChannelSender, 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 LiveKitBackend, 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 StatusOptions, 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, 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 { 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 BaseToolContext, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type CallBackend, type CallMember, type Caller, type CallerOptions, type CallsAccess, type CallsOptions, type CapturedRow, type CascadingKey, type ChannelBroadcast, type ChannelSender, 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 LiveKitBackend, type LocalFilesOptions, type MailAttachment, 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, PersonalMailError, type PersonalMailErrorCode, type PersonalMailProviderId, 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 StatusOptions, 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, 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 };