@protobase/server 0.45.16 → 0.45.18

package/dist/notifications/schema.js

@@ -1,7 +1,8 @@
 import { migrationCommand } from "../changes/capture-schema.js";
-import { notificationsNames } from "./options.js";
+import { historyNames, notificationsNames } from "./options.js";
 import { storeSchema } from "../better-auth/auth-tables.js";
 import { devicesTableSql, qualified } from "./schema-sql.js";
+import { historyTableSql } from "./history-sql.js";
 import { sql } from "kysely";
 //#region src/notifications/schema.ts
 /** Auth's users table, as the store names it: devices point at it. */
@@ -17,43 +18,65 @@ const userIdType = async (db, users) => {
 	return rows[0].type;
 };
 /**
-* The SQL that adds the devices table `notifications()` keeps devices in, under the names its options give; with
-* `auth`, its user column points at auth's users table. `undefined` when the table exists, and with a store of the
-* app's own, which needs none.
+* The SQL that adds the tables `notifications()` keeps devices and each user's history in, under the names its options
+* give; with `auth`, their user columns point at auth's users table. Each table is left out when it exists or a store
+* of the app's own replaces it; `undefined` when none is left.
 */
 const notificationsMigration = async (db, options = {}, auth) => {
-	if (options.store) return void 0;
-	const names = notificationsNames(options);
-	if (await regclass(db, qualified(names)) !== null) return void 0;
+	const devices = !options.store && notificationsNames(options);
+	const history = !options.historyStore && historyNames(options);
+	const missing = async (names) => names && await regclass(db, qualified(names)) === null;
+	const [needsDevices, needsHistory] = [await missing(devices), await missing(history)];
+	if (!needsDevices && !needsHistory) return void 0;
 	const users = auth && authUsersTable(auth);
 	const user = users ? {
 		type: await userIdType(db, users),
 		references: `${qualified(users)} (id)`
 	} : { type: "text" };
-	return `${devicesTableSql(names, user).join(";\n\n")};`;
+	const statements = [...needsDevices && devices ? devicesTableSql(devices, user) : [], ...needsHistory && history ? historyTableSql(history, user) : []];
+	return `${[...new Set(statements)].join(";\n\n")};`;
 };
 const columnsOf = async (db, oid) => (await sql`select attname as name, attnum as num from pg_attribute where attrelid = ${oid} and attnum > 0 and not attisdropped`.execute(db)).rows;
 const uniqueOn = async (db, oid, num) => (await sql`select exists (select from pg_index where indrelid = ${oid} and indisunique and indpred is null and indexprs is null and indnatts = 1 and indkey[0] = ${num}) as found`.execute(db)).rows[0].found;
 const cascadesFrom = async (db, oid, num, users) => (await sql`select exists (select from pg_constraint where conrelid = ${oid} and contype = 'f' and confdeltype = 'c'
     and conkey = array[${num}]::int2[] and confrelid = to_regclass(${qualified(users)})) as found`.execute(db)).rows[0].found;
+const missingTable = (what, table) => /* @__PURE__ */ new Error(`The ${what} table ${table} of notifications() is missing. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
 /**
 * Refuses to start while the devices table lacks what `notifications()` needs, naming it: the table, each column under
 * its configured name, a unique index on the token alone, which moving a device relies on, and with `auth` a foreign key
 * from the user column that deletes a user's devices with the user. Nothing to check with a store of the app's own.
 */
-const checkNotificationsSchema = async (db, options = {}, auth) => {
+const checkDevicesTable = async (db, options, users) => {
 	if (options.store) return;
 	const names = notificationsNames(options);
 	const devices = qualified(names);
 	const oid = await regclass(db, devices);
-	if (oid === null) throw new Error(`The devices table ${devices} of notifications() is missing. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+	if (oid === null) throw missingTable("devices", devices);
 	const found = await columnsOf(db, oid);
 	const numOf = (column) => found.find((row) => row.name === names.columns[column])?.num;
 	const missing = Object.keys(names.columns).find((column) => numOf(column) === void 0);
 	if (missing !== void 0) throw new Error(`The devices table ${devices} has no column "${names.columns[missing]}": add it, or name the table's own with notifications({ devices: { columns: { ${missing}: ... } } })`);
 	if (!await uniqueOn(db, oid, numOf("token"))) throw new Error(`The devices table ${devices} needs a unique index on its token column "${names.columns.token}" alone, which moving a device to the user who registers it relies on`);
-	const users = auth && authUsersTable(auth);
 	if (users && !await cascadesFrom(db, oid, numOf("user_id"), users)) throw new Error(`The devices table ${devices} needs a foreign key from "${names.columns.user_id}" to ${qualified(users)} with on delete cascade, so a deleted user's devices go with them`);
 };
+/** Refuses to start while the history table lacks its table, a column or, with `auth`, the cascading foreign key. */
+const checkHistoryTable = async (db, options, users) => {
+	if (options.historyStore) return;
+	const names = historyNames(options);
+	const history = qualified(names);
+	const oid = await regclass(db, history);
+	if (oid === null) throw missingTable("history", history);
+	const found = await columnsOf(db, oid);
+	const numOf = (column) => found.find((row) => row.name === names.columns[column])?.num;
+	const missing = Object.keys(names.columns).find((column) => numOf(column) === void 0);
+	if (missing !== void 0) throw new Error(`The history table ${history} has no column "${names.columns[missing]}": add it, or name the table's own with notifications({ history: { columns: { ${missing}: ... } } })`);
+	if (users && !await cascadesFrom(db, oid, numOf("user_id"), users)) throw new Error(`The history table ${history} needs a foreign key from "${names.columns.user_id}" to ${qualified(users)} with on delete cascade, so a deleted user's history goes with them`);
+};
+/** Refuses to start while the devices or the history table lacks what `notifications()` needs, naming it. */
+const checkNotificationsSchema = async (db, options = {}, auth) => {
+	const users = auth && authUsersTable(auth);
+	await checkDevicesTable(db, options, users);
+	await checkHistoryTable(db, options, users);
+};
 //#endregion
 export { authUsersTable, checkNotificationsSchema, notificationsMigration };

package/dist/notifications/sender.d.ts

@@ -0,0 +1,25 @@
+import { Device, DeviceKind } from "./device.js";
+import { PushMessage } from "./message.js";
+//#region src/notifications/sender.d.ts
+/**
+ * What a sender answers for one device: `ok` when the push service took the message, `gone` when the device no longer
+ * exists there and should be removed, `retry` when it may take the message later, after `retryAfterSeconds` when the
+ * push service says.
+ */
+export type PushAnswer = {
+  id: string;
+  result: 'ok' | 'gone' | 'retry';
+  retryAfterSeconds?: number;
+};
+/**
+ * Delivers notifications to the devices of its `kinds`, through their push service: the built-in Web Push sender, or
+ * one of the app's own passed as `notifications({ senders })`, typically from a package. `send` takes a message and a
+ * batch of devices of those kinds only, and answers each device by its id. A sender for `web` devices names the VAPID
+ * `publicKey` browsers subscribe with, which every client may read.
+ */
+export type PushSender = {
+  kinds: readonly DeviceKind[];
+  publicKey?: string;
+  send: (message: PushMessage, devices: readonly Device[]) => Promise<PushAnswer[]>;
+};
+//#endregion

package/dist/notifications/sender.js

@@ -0,0 +1,23 @@
+import { deviceKinds } from "./device.js";
+import { isPublicKey } from "./web-push/keys.js";
+//#region src/notifications/sender.ts
+const checkSender = (sender, index, claimed) => {
+	const name = `notifications({ senders }): sender ${index}`;
+	if (typeof sender !== "object" || sender === null || typeof sender.send !== "function") throw new Error(`${name} has no send method`);
+	if (!Array.isArray(sender.kinds) || sender.kinds.length === 0) throw new Error(`${name} names no kinds: ${deviceKinds.join(", ")}`);
+	for (const kind of sender.kinds) {
+		if (!deviceKinds.includes(kind)) throw new Error(`${name} names a kind that is none of ${deviceKinds.join(", ")}`);
+		if (claimed.has(kind)) throw new Error(`${name} delivers to ${kind} devices, as an earlier sender does`);
+		claimed.add(kind);
+	}
+	if (sender.publicKey !== void 0 && !isPublicKey(sender.publicKey)) throw new Error(`${name} has a publicKey that is not a P-256 public key in base64url`);
+};
+/** The senders, checked: each with a send method and kinds, no kind delivered by two, and a public key when one is named. */
+const checkSenders = (senders) => {
+	if (!Array.isArray(senders)) throw new Error("notifications({ senders }) is a list of senders");
+	const claimed = /* @__PURE__ */ new Set();
+	senders.forEach((sender, index) => checkSender(sender, index, claimed));
+	return senders;
+};
+//#endregion
+export { checkSenders };

package/dist/notifications/senders-of.d.ts

@@ -0,0 +1,10 @@
+import { PushSender } from "./sender.js";
+import { NotificationsOptions } from "./options.js";
+//#region src/notifications/senders-of.d.ts
+/**
+ * The senders `notifications()` delivers with: the app's own `senders`, which replace the built-in ones, or the
+ * built-in ones whose environment is set. Each comes guarded (see `guardedSender`): the code that sends calls them only
+ * through what this returns. A VAPID variable that is wrong stops startup.
+ */
+export declare const notificationSenders: (options: NotificationsOptions, env?: Record<string, string | undefined>) => PushSender[];
+//#endregion

package/dist/notifications/senders-of.js

@@ -0,0 +1,19 @@
+import { checkSenders } from "./sender.js";
+import { guardedSender } from "./guarded-sender.js";
+import { readVapidSettings } from "./web-push/vapid-settings.js";
+import { webPushSender } from "./web-push/web-push-sender.js";
+//#region src/notifications/senders-of.ts
+const builtInSenders = (env) => {
+	const vapid = readVapidSettings(env);
+	return vapid ? [webPushSender(vapid)] : [];
+};
+/**
+* The senders `notifications()` delivers with: the app's own `senders`, which replace the built-in ones, or the
+* built-in ones whose environment is set. Each comes guarded (see `guardedSender`): the code that sends calls them only
+* through what this returns. A VAPID variable that is wrong stops startup.
+*/
+const notificationSenders = (options, env = globalThis.process?.env ?? {}) => checkSenders(options.senders ?? builtInSenders(env)).map(guardedSender);
+/** The VAPID public key browsers subscribe with: the web sender's, when there is one. */
+const webPushKey = (senders) => senders.find((sender) => sender.kinds.includes("web"))?.publicKey;
+//#endregion
+export { notificationSenders, webPushKey };

package/dist/notifications/tap-url.js

@@ -0,0 +1,15 @@
+//#region src/notifications/tap-url.ts
+const plain = /^[^\s\u0000-\u001f\u007f-\u009f]+$/;
+/**
+* The URL a notification opens on tap, as the WHATWG parser writes it, or `undefined` when it is no absolute `http` or
+* `https` URL: a relative or scheme-relative URL, `javascript:`, `data:`, `file:`, `blob:` and every other scheme are
+* refused, since they would run or show content on tap. Any origin is allowed.
+*/
+const tapUrl = (value) => {
+	if (typeof value !== "string" || value.length > 2048 || !plain.test(value) || !URL.canParse(value)) return void 0;
+	const url = new URL(value);
+	if (url.protocol !== "https:" && url.protocol !== "http:") return void 0;
+	return url.href;
+};
+//#endregion
+export { tapUrl };

package/dist/notifications/web-push/encrypt.js

@@ -0,0 +1,45 @@
+import { createCipheriv, createECDH, hkdfSync, randomBytes } from "node:crypto";
+//#region src/notifications/web-push/encrypt.ts
+/** The record size the body is one record of. */
+const recordSize = 4096;
+/** The most plaintext one message carries: push services take a body of at most 4096 bytes, of which the 86-byte header, the 16-byte tag and the padding delimiter are not plaintext. */
+const maxPlaintextBytes = 3993;
+const derived = (ikm, salt, info, length) => Buffer.from(hkdfSync("sha256", ikm, salt, info, length));
+/**
+* `plaintext` encrypted for one subscription as Web Push's aes128gcm (RFC 8291, RFC 8188): a fresh ephemeral key and a
+* random 16-byte salt for every call, one record with its padding delimiter. `fixed` replaces both, for test vectors
+* only. Throws for a plaintext over `maxPlaintextBytes`.
+*/
+const encryptPayload = (plaintext, keys, fixed) => {
+	if (plaintext.length > 3993) throw new Error(`A Web Push payload carries at most ${maxPlaintextBytes} bytes`);
+	const salt = fixed?.salt ?? randomBytes(16);
+	const ecdh = fixed?.ecdh ?? createECDH("prime256v1");
+	const serverPublic = fixed ? ecdh.getPublicKey() : ecdh.generateKeys();
+	const secret = ecdh.computeSecret(keys.p256dh);
+	const keyInfo = Buffer.concat([
+		Buffer.from("WebPush: info\0"),
+		keys.p256dh,
+		serverPublic
+	]);
+	const ikm = derived(secret, keys.auth, keyInfo, 32);
+	const contentKey = derived(ikm, salt, Buffer.from("Content-Encoding: aes128gcm\0"), 16);
+	const nonce = derived(ikm, salt, Buffer.from("Content-Encoding: nonce\0"), 12);
+	const cipher = createCipheriv("aes-128-gcm", contentKey, nonce);
+	const ciphertext = Buffer.concat([
+		cipher.update(plaintext),
+		cipher.update(Buffer.from([2])),
+		cipher.final(),
+		cipher.getAuthTag()
+	]);
+	const size = Buffer.alloc(4);
+	size.writeUInt32BE(recordSize);
+	return Buffer.concat([
+		salt,
+		size,
+		Buffer.from([serverPublic.length]),
+		serverPublic,
+		ciphertext
+	]);
+};
+//#endregion
+export { encryptPayload, maxPlaintextBytes };

package/dist/notifications/web-push/keys.d.ts

@@ -0,0 +1,7 @@
+//#region src/notifications/web-push/keys.d.ts
+/** A fresh VAPID key pair, both in base64url, for `PROTOBASE_VAPID_PUBLIC_KEY` and `PROTOBASE_VAPID_PRIVATE_KEY`. */
+export declare const generateVapidKeys: () => {
+  publicKey: string;
+  privateKey: string;
+};
+//#endregion

package/dist/notifications/web-push/keys.js

@@ -0,0 +1,43 @@
+import { ECDH, createECDH } from "node:crypto";
+//#region src/notifications/web-push/keys.ts
+const curve = "prime256v1";
+const base64url = /^[A-Za-z0-9_-]+$/;
+/** The bytes of unpadded base64url text, or `undefined` for anything else. */
+const fromBase64url = (text) => typeof text === "string" && base64url.test(text) ? Buffer.from(text, "base64url") : void 0;
+/** Whether `bytes` is a P-256 public key, an uncompressed point on the curve, as browsers and VAPID give it. */
+const isPublicPoint = (bytes) => {
+	if (bytes?.length !== 65 || bytes[0] !== 4) return false;
+	try {
+		ECDH.convertKey(bytes, curve);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ERR_CRYPTO_OPERATION_FAILED") return false;
+		throw error;
+	}
+};
+/** Whether `text` is a P-256 public key in base64url. */
+const isPublicKey = (text) => isPublicPoint(fromBase64url(text));
+/** The public key of a P-256 private key, or `undefined` when the bytes are none. */
+const publicKeyOf = (privateKey) => {
+	if (privateKey.length !== 32) return void 0;
+	const ecdh = createECDH(curve);
+	try {
+		ecdh.setPrivateKey(privateKey);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ERR_CRYPTO_INVALID_KEYTYPE") return void 0;
+		throw error;
+	}
+	return ecdh.getPublicKey();
+};
+/** A private key as 32 bytes: the runtime gives a key with leading zero bytes shorter. */
+const padPrivateKey = (privateKey) => Buffer.concat([Buffer.alloc(32 - privateKey.length), privateKey]);
+/** A fresh VAPID key pair, both in base64url, for `PROTOBASE_VAPID_PUBLIC_KEY` and `PROTOBASE_VAPID_PRIVATE_KEY`. */
+const generateVapidKeys = () => {
+	const ecdh = createECDH(curve);
+	return {
+		publicKey: ecdh.generateKeys().toString("base64url"),
+		privateKey: padPrivateKey(ecdh.getPrivateKey()).toString("base64url")
+	};
+};
+//#endregion
+export { fromBase64url, generateVapidKeys, isPublicKey, isPublicPoint, padPrivateKey, publicKeyOf };

package/dist/notifications/web-push/payload.js

@@ -0,0 +1,48 @@
+import { isJsonObject, mergeJson } from "../json-value.js";
+import { tapUrl } from "../tap-url.js";
+import { PushMessageError } from "../message.js";
+//#region src/notifications/web-push/payload.ts
+const checkedUrl = (value, field) => {
+	const url = tapUrl(value);
+	if (url === void 0) throw new PushMessageError(field);
+	return url;
+};
+const withCheckedUrls = (payload) => {
+	const checked = { ...payload };
+	if (checked.url !== void 0) checked.url = checkedUrl(checked.url, "platform.web.payload.url");
+	if (checked.notification === void 0) return checked;
+	if (!isJsonObject(checked.notification)) throw new PushMessageError("platform.web.payload.notification");
+	const notification = { ...checked.notification };
+	if (notification.navigate !== void 0) notification.navigate = checkedUrl(notification.navigate, "platform.web.payload.notification.navigate");
+	if (notification.actions !== void 0) {
+		if (!Array.isArray(notification.actions)) throw new PushMessageError("platform.web.payload.notification.actions");
+		notification.actions = notification.actions.map((action, index) => {
+			const field = `platform.web.payload.notification.actions.${index}`;
+			if (!isJsonObject(action)) throw new PushMessageError(field);
+			return action.navigate === void 0 ? action : {
+				...action,
+				navigate: checkedUrl(action.navigate, `${field}.navigate`)
+			};
+		});
+	}
+	return {
+		...checked,
+		notification
+	};
+};
+/**
+* The JSON a browser's service worker gets, from a checked message: its title, body, url, data, badge and tag, with
+* `platform.web.payload` merged over them. Every url in it is checked again after the merge, so the payload never
+* carries one that is no absolute `http` or `https` URL.
+*/
+const webPushPayload = (message) => {
+	const common = { title: message.title };
+	if (message.body !== void 0) common.body = message.body;
+	if (message.url !== void 0) common.url = message.url;
+	if (message.data !== void 0) common.data = message.data;
+	if (message.badge !== void 0) common.badge = message.badge;
+	if (message.tag !== void 0) common.tag = message.tag;
+	return withCheckedUrls(mergeJson(common, message.platform?.web?.payload ?? {}));
+};
+//#endregion
+export { webPushPayload };

package/dist/notifications/web-push/post.d.ts

@@ -0,0 +1,6 @@
+//#region src/notifications/web-push/post.d.ts
+export type PostOptions = {
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+};
+//#endregion

package/dist/notifications/web-push/post.js

@@ -0,0 +1,47 @@
+//#region src/notifications/web-push/post.ts
+/** How long a push service has to answer before the device is answered `retry`. */
+const defaultPushTimeoutMs = 1e4;
+const retryAfter = (response) => {
+	const seconds = response.headers.get("retry-after")?.trim();
+	return seconds !== void 0 && /^\d{1,7}$/.test(seconds) ? {
+		result: "retry",
+		retryAfterSeconds: Number(seconds)
+	} : { result: "retry" };
+};
+/**
+* What a push service's status means for the device: any 2xx took it; 404 and 410 say the subscription is gone; every
+* other status, a redirect, a 429 or 5xx, and a 4xx that may be a configuration mistake (a wrong key), asks to try
+* again, so no mistake of ours removes devices.
+*/
+const pushResult = (response) => {
+	if (response.status >= 200 && response.status < 300) return { result: "ok" };
+	if (response.status === 404 || response.status === 410) return { result: "gone" };
+	return retryAfter(response);
+};
+const isTransient = (error) => error instanceof TypeError || error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError");
+/**
+* Posts one Web Push request and answers what it means for the device. Redirects are never followed, so the request
+* and its token reach only `url`, and an answer that does not come within the timeout is `retry`. Fetch's own errors
+* are never passed on, since they can name the URL: one that is not a missing answer becomes an error of its own.
+*/
+const postPush = async (url, headers, body, options = {}) => {
+	const request = new Request(url, {
+		method: "POST",
+		headers,
+		body,
+		redirect: "manual"
+	});
+	const signal = AbortSignal.timeout(options.timeoutMs ?? 1e4);
+	const send = options.fetch ?? fetch;
+	let response;
+	try {
+		response = await send(request, { signal });
+	} catch (error) {
+		if (isTransient(error)) return { result: "retry" };
+		throw new Error("A Web Push request failed unexpectedly");
+	}
+	await response.body?.cancel();
+	return pushResult(response);
+};
+//#endregion
+export { defaultPushTimeoutMs, postPush, pushResult };

package/dist/notifications/web-push/vapid-jwt.js

@@ -0,0 +1,45 @@
+import { sign } from "node:crypto";
+//#region src/notifications/web-push/vapid-jwt.ts
+/** How long a token is valid: RFC 8292 allows at most 24 hours. */
+const lifetimeSeconds = 43200;
+/** A token is signed again once less than this is left of it, so none expires on its way. */
+const refreshSeconds = 3600;
+/** The push services' origins a sender keeps a token for: a handful, as there are a handful of push services. */
+const maxAudiences = 16;
+const encoded = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+const signed = (settings, audience, exp) => {
+	const input = `${encoded({
+		typ: "JWT",
+		alg: "ES256"
+	})}.${encoded({
+		aud: audience,
+		exp,
+		sub: settings.subject
+	})}`;
+	return `${input}.${sign("sha256", Buffer.from(input), {
+		key: settings.privateKey,
+		dsaEncoding: "ieee-p1363"
+	}).toString("base64url")}`;
+};
+/**
+* The `Authorization` header of a Web Push request to a push service's origin (RFC 8292): `vapid t=<ES256 JWT>,
+* k=<public key>`. A token is reused for its origin until an hour before it expires; at most 16 origins are kept, the
+* least recently used dropped first. Each sender makes its own, so no two key pairs share a token.
+*/
+const vapidAuthorizer = (settings, now = Date.now) => {
+	const tokens = /* @__PURE__ */ new Map();
+	return (audience) => {
+		const seconds = Math.floor(now() / 1e3);
+		const kept = tokens.get(audience);
+		tokens.delete(audience);
+		const entry = kept && kept.exp - seconds > refreshSeconds ? kept : {
+			token: signed(settings, audience, seconds + lifetimeSeconds),
+			exp: seconds + lifetimeSeconds
+		};
+		tokens.set(audience, entry);
+		if (tokens.size > maxAudiences) tokens.delete(tokens.keys().next().value);
+		return `vapid t=${entry.token}, k=${settings.publicKey}`;
+	};
+};
+//#endregion
+export { vapidAuthorizer };

package/dist/notifications/web-push/vapid-settings.d.ts

@@ -0,0 +1,22 @@
+import { KeyObject } from "node:crypto";
+//#region src/notifications/web-push/vapid-settings.d.ts
+/**
+ * The VAPID key pair and contact (RFC 8292) the Web Push sender signs with. The private key is a `KeyObject`, which
+ * prints no key material when logged or serialized.
+ */
+export type VapidSettings = {
+  publicKey: string;
+  privateKey: KeyObject;
+  subject: string;
+};
+export declare const vapidPublicKeyVariable = "PROTOBASE_VAPID_PUBLIC_KEY";
+export declare const vapidPrivateKeyVariable = "PROTOBASE_VAPID_PRIVATE_KEY";
+export declare const vapidSubjectVariable = "PROTOBASE_VAPID_SUBJECT";
+/**
+ * The VAPID settings from `PROTOBASE_VAPID_PUBLIC_KEY`, `PROTOBASE_VAPID_PRIVATE_KEY` and `PROTOBASE_VAPID_SUBJECT`;
+ * `undefined` when none is set, which turns Web Push off. A blank variable counts as unset. Some set but not all, a key
+ * that is not one, a public key that is not the private key's, or a subject that is no `mailto:` or `https:` URL is a
+ * configuration error naming the variable, never its value, so the server stops at startup.
+ */
+export declare const readVapidSettings: (env: Record<string, string | undefined>) => VapidSettings | undefined;
+//#endregion

package/dist/notifications/web-push/vapid-settings.js

@@ -0,0 +1,51 @@
+import { fromBase64url, isPublicPoint, publicKeyOf } from "./keys.js";
+import { createPrivateKey } from "node:crypto";
+//#region src/notifications/web-push/vapid-settings.ts
+const vapidPublicKeyVariable = "PROTOBASE_VAPID_PUBLIC_KEY";
+const vapidPrivateKeyVariable = "PROTOBASE_VAPID_PRIVATE_KEY";
+const vapidSubjectVariable = "PROTOBASE_VAPID_SUBJECT";
+const variables = [
+	vapidPublicKeyVariable,
+	vapidPrivateKeyVariable,
+	vapidSubjectVariable
+];
+const isSubject = (subject) => {
+	if (/^mailto:[^\s@]+@[^\s@]+$/.test(subject)) return true;
+	return URL.canParse(subject) && new URL(subject).protocol === "https:" && !/\s/.test(subject);
+};
+/**
+* The VAPID settings from `PROTOBASE_VAPID_PUBLIC_KEY`, `PROTOBASE_VAPID_PRIVATE_KEY` and `PROTOBASE_VAPID_SUBJECT`;
+* `undefined` when none is set, which turns Web Push off. A blank variable counts as unset. Some set but not all, a key
+* that is not one, a public key that is not the private key's, or a subject that is no `mailto:` or `https:` URL is a
+* configuration error naming the variable, never its value, so the server stops at startup.
+*/
+const readVapidSettings = (env) => {
+	const [publicText, privateText, subject] = variables.map((name) => env[name]?.trim() || void 0);
+	if (!publicText && !privateText && !subject) return void 0;
+	const missing = variables.filter((name) => !env[name]?.trim());
+	if (missing.length > 0) throw new Error(`${missing.join(" and ")} must be set for Web Push, with ${variables.filter((name) => !missing.includes(name)).join(" and ")}; set all three, or none to turn Web Push off`);
+	const publicKey = fromBase64url(publicText);
+	if (!isPublicPoint(publicKey)) throw new Error(`${vapidPublicKeyVariable} is not a P-256 public key in base64url; generate a pair with protobase notifications vapid-keys`);
+	const privateKey = fromBase64url(privateText);
+	const derived = privateKey && publicKeyOf(privateKey);
+	if (!derived) throw new Error(`${vapidPrivateKeyVariable} is not a P-256 private key in base64url; generate a pair with protobase notifications vapid-keys`);
+	if (!derived.equals(publicKey)) throw new Error(`${vapidPublicKeyVariable} is not the public key of ${vapidPrivateKeyVariable}; set both from one pair`);
+	if (!isSubject(subject)) throw new Error(`${vapidSubjectVariable} must be a mailto: address or an https: URL, such as mailto:admin@example.com`);
+	const jwk = {
+		kty: "EC",
+		crv: "P-256",
+		d: privateKey.toString("base64url"),
+		x: publicKey.subarray(1, 33).toString("base64url"),
+		y: publicKey.subarray(33).toString("base64url")
+	};
+	return {
+		publicKey: publicKey.toString("base64url"),
+		privateKey: createPrivateKey({
+			key: jwk,
+			format: "jwk"
+		}),
+		subject
+	};
+};
+//#endregion
+export { readVapidSettings, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable };

package/dist/notifications/web-push/web-push-sender.d.ts

@@ -0,0 +1,15 @@
+import { PushSender } from "../sender.js";
+import { PostOptions } from "./post.js";
+import { VapidSettings } from "./vapid-settings.js";
+//#region src/notifications/web-push/web-push-sender.d.ts
+export type WebPushOptions = PostOptions & {
+  now?: () => number;
+};
+/**
+ * The built-in Web Push sender (RFC 8030, 8291, 8292): delivers to `web` devices, signed with the VAPID pair and
+ * encrypted for each device's keys. It checks the message as `pushMessage` does and throws before any request when it
+ * is not one. A device whose endpoint is not on a browser's push service, or whose keys are not a subscription's, is
+ * answered `gone` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
+ */
+export declare const webPushSender: (settings: VapidSettings, options?: WebPushOptions) => PushSender;
+//#endregion

package/dist/notifications/web-push/web-push-sender.js

@@ -0,0 +1,74 @@
+import { fromBase64url, isPublicPoint } from "./keys.js";
+import { isPushEndpoint } from "../push-hosts.js";
+import { PushMessageError, pushMessage } from "../message.js";
+import { encryptPayload, maxPlaintextBytes } from "./encrypt.js";
+import { webPushPayload } from "./payload.js";
+import { postPush } from "./post.js";
+import { vapidAuthorizer } from "./vapid-jwt.js";
+//#region src/notifications/web-push/web-push-sender.ts
+/** How many requests one batch has open at once. */
+const concurrency = 8;
+const endpointOf = (device) => isPushEndpoint(device.token) ? new URL(device.token) : void 0;
+const keysOf = (device) => {
+	const p256dh = fromBase64url(device.p256dh);
+	const auth = fromBase64url(device.auth);
+	return isPublicPoint(p256dh) && auth?.length === 16 ? {
+		p256dh,
+		auth
+	} : void 0;
+};
+const headersOf = (message) => {
+	const web = message.platform?.web;
+	const urgency = web?.urgency ?? message.urgency;
+	const topic = web?.topic ?? message.tag;
+	return {
+		TTL: String(web?.ttl ?? message.ttl ?? 2419200),
+		...urgency !== void 0 && { Urgency: urgency },
+		...topic !== void 0 && { Topic: topic },
+		"Content-Type": "application/octet-stream",
+		"Content-Encoding": "aes128gcm"
+	};
+};
+/**
+* The built-in Web Push sender (RFC 8030, 8291, 8292): delivers to `web` devices, signed with the VAPID pair and
+* encrypted for each device's keys. It checks the message as `pushMessage` does and throws before any request when it
+* is not one. A device whose endpoint is not on a browser's push service, or whose keys are not a subscription's, is
+* answered `gone` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
+*/
+const webPushSender = (settings, options = {}) => {
+	const authorization = vapidAuthorizer(settings, options.now);
+	const sendOne = async (device, headers, plaintext) => {
+		const url = endpointOf(device);
+		const keys = keysOf(device);
+		if (!url || !keys) return {
+			id: device.id,
+			result: "gone"
+		};
+		const body = encryptPayload(plaintext, keys);
+		const answer = await postPush(url, {
+			...headers,
+			Authorization: authorization(url.origin)
+		}, body, options);
+		return {
+			id: device.id,
+			...answer
+		};
+	};
+	const send = async (given, devices) => {
+		const message = pushMessage(given);
+		if (devices.some((device) => device.kind !== "web")) throw new Error("The Web Push sender was given a device that is not a web device");
+		const headers = headersOf(message);
+		const plaintext = Buffer.from(JSON.stringify(webPushPayload(message)));
+		if (plaintext.length > 3993) throw new PushMessageError(`message: its Web Push payload is over ${maxPlaintextBytes} bytes`);
+		const answers = [];
+		for (let start = 0; start < devices.length; start += concurrency) answers.push(...await Promise.all(devices.slice(start, start + concurrency).map((device) => sendOne(device, headers, plaintext))));
+		return answers;
+	};
+	return {
+		kinds: ["web"],
+		publicKey: settings.publicKey,
+		send
+	};
+};
+//#endregion
+export { webPushSender };

package/dist/package.js

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

package/package.json

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