@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/src/network/playwright/GuardedBrowserProxy.ts

@@ -0,0 +1,172 @@
+import { randomBytes } from 'node:crypto';
+import { createServer, request as httpRequest, type IncomingMessage, type ServerResponse, type OutgoingHttpHeaders } from 'node:http';
+import { connect, type Socket } from 'node:net';
+import type { Duplex } from 'node:stream';
+import { assertPublicUrl } from '../assertPublicUrl';
+import { BlockedUrlError } from '../BlockedUrlError';
+import { normalizedUrlHostname } from '../privateNetworkAddresses';
+import { publicAddressLookup } from '../publicAddressLookup';
+
+/** Internal connection policy; the browser adapter owns request attribution. */
+interface ProxyOptions {
+	allowPrivate?: boolean;
+	requestTimeoutMs?: number;
+	onBlocked: (url: string, error: BlockedUrlError) => void;
+}
+
+/**
+ * Context-owned loopback proxy enforcing the destination of every browser socket.
+ *
+ * HTTP bodies stream without buffering. HTTPS remains end-to-end TLS through a
+ * validated CONNECT tunnel, preserving browser certificates, cookies and origins.
+ * Redirects create normal browser requests and cannot escape the proxy's policy.
+ */
+export class GuardedBrowserProxy {
+	readonly #options: ProxyOptions;
+	readonly #sockets = new Set<Duplex>();
+	readonly #server = createServer();
+	readonly #username = 'db3-browser';
+	readonly #password = randomBytes(32).toString('hex');
+	#closed = false;
+
+	/** Creates an unstarted, isolated browser proxy. */
+	constructor(options: ProxyOptions) {
+		this.#options = options;
+		this.#server.on('connection', socket => this.#track(socket));
+		this.#server.on('request', (request, response) => { void this.#forward(request, response); });
+		this.#server.on('connect', (request, socket, head) => { void this.#tunnel(request, socket, head); });
+		this.#server.on('clientError', (_error, socket) => socket.destroy());
+	}
+
+	/**
+	 * Starts the proxy on an ephemeral loopback port.
+	 * @returns Chromium proxy options; the bypass rule includes loopback traffic.
+	 */
+	async start(): Promise<{ server: string; bypass: string; username: string; password: string }> {
+		await new Promise<void>((resolve, reject) => {
+			this.#server.once('error', reject);
+			this.#server.listen(0, '127.0.0.1', () => {
+				this.#server.off('error', reject);
+				resolve();
+			});
+		});
+		const address = this.#server.address();
+		if (!address || typeof address === 'string') throw new Error('Browser proxy did not open a TCP port.');
+		return { server: `http://127.0.0.1:${address.port}`, bypass: '<-loopback>', username: this.#username, password: this.#password };
+	}
+
+	/** Stops accepting requests and synchronously tears down every owned socket. */
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		for (const socket of this.#sockets) socket.destroy();
+		this.#server.close();
+	}
+
+	/**
+	 * Registers socket cleanup and an inactivity timeout without buffering data.
+	 * @param socket - Accepted browser socket or outgoing destination connection.
+	 */
+	#track(socket: Duplex): void {
+		if (this.#closed) { socket.destroy(); return; }
+		this.#sockets.add(socket);
+		socket.once('close', () => this.#sockets.delete(socket));
+		socket.on('error', () => socket.destroy());
+		if ('setTimeout' in socket) (socket as Socket).setTimeout(this.#options.requestTimeoutMs ?? 30_000, () => socket.destroy());
+	}
+
+	/** Checks the per-context proxy credential supplied by Chromium. */
+	#authorized(request: IncomingMessage): boolean {
+		return request.headers['proxy-authorization'] === `Basic ${Buffer.from(`${this.#username}:${this.#password}`).toString('base64')}`;
+	}
+
+	/**
+	 * Streams a normal HTTP proxy request through a validated connection.
+	 * @param request - Browser's absolute-form request.
+	 * @param response - Response streamed back to the browser.
+	 */
+	async #forward(request: IncomingMessage, response: ServerResponse): Promise<void> {
+		if (!this.#authorized(request)) {
+			response.writeHead(407, { 'proxy-authenticate': 'Basic realm="db3-browser"' }).end();
+			return;
+		}
+		const url = request.url ?? '';
+		try {
+			await assertPublicUrl(url, this.#options);
+			const destination = new URL(url);
+			if (destination.protocol !== 'http:') throw new BlockedUrlError('HTTPS browser requests must use a CONNECT tunnel.');
+			if (this.#closed || response.destroyed) return;
+			const headers: OutgoingHttpHeaders = { ...request.headers, host: destination.host };
+			delete headers['proxy-authorization'];
+			delete headers['proxy-connection'];
+			const outgoing = httpRequest(destination, {
+				method: request.method,
+				headers,
+				agent: false,
+				lookup: this.#options.allowPrivate ? undefined : publicAddressLookup,
+			}, upstream => {
+				response.writeHead(upstream.statusCode ?? 502, upstream.headers);
+				upstream.on('error', () => response.destroy());
+				upstream.pipe(response);
+			});
+			outgoing.on('socket', socket => this.#track(socket));
+			outgoing.on('error', error => {
+				this.#reportBlocked(url, error);
+				response.destroy();
+			});
+			request.on('aborted', () => outgoing.destroy());
+			request.on('error', () => outgoing.destroy());
+			response.on('close', () => outgoing.destroy());
+			request.pipe(outgoing);
+		} catch (error) {
+			this.#reportBlocked(url, error);
+			response.destroy();
+		}
+	}
+
+	/**
+	 * Opens a TLS tunnel only after validating its actual destination connection.
+	 * @param request - Chromium CONNECT authority.
+	 * @param browser - Browser side of the opaque tunnel.
+	 * @param head - Bytes received with the CONNECT request.
+	 */
+	async #tunnel(request: IncomingMessage, browser: Duplex, head: Buffer): Promise<void> {
+		if (!this.#authorized(request)) {
+			browser.end('HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm="db3-browser"\r\nContent-Length: 0\r\n\r\n');
+			return;
+		}
+		const url = `https://${request.url ?? ''}/`;
+		try {
+			await assertPublicUrl(url, this.#options);
+			if (this.#closed || browser.destroyed) return;
+			const destination = new URL(url);
+			const upstream = connect({
+				host: normalizedUrlHostname(destination.hostname),
+				port: Number(destination.port || 443),
+				lookup: this.#options.allowPrivate ? undefined : publicAddressLookup,
+			});
+			this.#track(upstream);
+			browser.once('close', () => upstream.destroy());
+			upstream.once('close', () => browser.destroy());
+			upstream.on('error', error => {
+				this.#reportBlocked(url, error);
+				browser.destroy();
+			});
+			upstream.once('connect', () => {
+				browser.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+				if (head.length) upstream.write(head);
+				upstream.pipe(browser);
+				browser.pipe(upstream);
+			});
+		} catch (error) {
+			this.#reportBlocked(url, error);
+			browser.destroy();
+		}
+	}
+
+	/** Records policy refusals without allowing observer failures to escape I/O. */
+	#reportBlocked(url: string, error: unknown): void {
+		if (!(error instanceof BlockedUrlError)) return;
+		try { this.#options.onBlocked(url, error); } catch { /* Observers cannot change network enforcement. */ }
+	}
+}

package/src/network/playwright/contracts/GuardedBrowserContextOptions.ts

@@ -0,0 +1,43 @@
+import type { Request } from 'playwright';
+import type { BlockedUrlError } from '../../BlockedUrlError';
+import type { PublicUrlOptions } from '../../contracts';
+
+/**
+ * Details passed to the observer when the guard refuses a browser request.
+ */
+export interface BlockedBrowserRequest {
+	/** URL the page tried to load. */
+	url: string;
+
+	/** Guard rejection with a caller-safe message. */
+	error: BlockedUrlError;
+
+	/**
+	 * Playwright request that was aborted.
+	 *
+	 * Use `request.isNavigationRequest()` and `request.frame()` to tell whether
+	 * the page's own navigation was refused rather than an embedded resource.
+	 */
+	request: Request;
+}
+
+/**
+ * Network policy for a browser context whose traffic is routed through the guard.
+ */
+export interface GuardedBrowserContextOptions extends PublicUrlOptions {
+	/**
+	 * Playwright resource types aborted without a network request, for example
+	 * `['image', 'font', 'media']` when only the rendered DOM is needed.
+	 */
+	blockedResourceTypes?: readonly string[];
+
+	/** Socket inactivity timeout in milliseconds. Defaults to 30 seconds. */
+	requestTimeoutMs?: number;
+
+	/**
+	 * Observer called for each request refused by the destination policy.
+	 *
+	 * The request is aborted whether or not an observer is supplied.
+	 */
+	onBlocked?: (blocked: BlockedBrowserRequest) => void;
+}

package/src/network/playwright/contracts/index.ts

@@ -0,0 +1 @@
+export * from './GuardedBrowserContextOptions';

package/src/network/playwright/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './newGuardedBrowserContext';

package/src/network/playwright/newGuardedBrowserContext.ts

@@ -0,0 +1,74 @@
+import type { Browser, BrowserContext, BrowserContextOptions, Request } from 'playwright';
+import { BlockedUrlError } from '../BlockedUrlError';
+import { assertPublicUrl } from '../assertPublicUrl';
+import { GuardedBrowserProxy } from './GuardedBrowserProxy';
+import type * as playwrightNetwork from './contracts';
+
+/**
+ * Creates a Chromium context with connection-level private-network protection.
+ *
+ * All HTTP requests and HTTPS tunnels use a context-owned authenticated proxy.
+ * Its socket lookup validates DNS at connect time, including redirect hops that
+ * Playwright does not route again. Chromium retains native redirects, cookies,
+ * response streaming and TLS verification. Closing the context closes its proxy.
+ * Service workers and WebSockets are disabled; callers must also disable WebRTC
+ * non-proxied UDP when launching Chromium for untrusted pages.
+ *
+ * @param browser - Launched Chromium browser.
+ * @param contextOptions - Browser settings; upstream proxy overrides are refused.
+ * @param options - Destination policy, resource filters and refusal observer.
+ * @returns Isolated browser context, owned and closed by the caller.
+ * @example
+ * const context = await newGuardedBrowserContext(browser);
+ * try { await (await context.newPage()).goto(url); } finally { await context.close(); }
+ */
+export async function newGuardedBrowserContext(browser: Browser, contextOptions: BrowserContextOptions = {}, options: playwrightNetwork.GuardedBrowserContextOptions = {}): Promise<BrowserContext> {
+	if (browser.browserType().name() !== 'chromium') throw new Error('Guarded browser contexts require Chromium.');
+	if (contextOptions.proxy) throw new Error('Guarded browser contexts own their proxy configuration.');
+	const requests = new Set<Request>();
+	const reported = new WeakSet<Request>();
+	const blockedOrigins = new Map<string, BlockedUrlError>();
+	const blockedTypes = new Set(options.blockedResourceTypes ?? []);
+	/** Attributes a connection rejection without exposing observer errors to I/O. */
+	function report(request: Request, error: BlockedUrlError): void {
+		if (reported.has(request)) return;
+		reported.add(request);
+		try { options.onBlocked?.({ url: request.url(), request, error }); } catch { /* Observers cannot change network enforcement. */ }
+	}
+	const proxy = new GuardedBrowserProxy({
+		...options,
+		onBlocked: (url, error) => {
+			const origin = new URL(url).origin;
+			blockedOrigins.set(origin, error);
+			for (const request of requests) if (new URL(request.url()).origin === origin) report(request, error);
+		},
+	});
+	let context: BrowserContext | undefined;
+	try {
+		context = await browser.newContext({ ...contextOptions, proxy: await proxy.start(), serviceWorkers: 'block' });
+		context.once('close', () => { proxy.close(); requests.clear(); blockedOrigins.clear(); });
+		context.on('request', request => {
+			requests.add(request);
+			const error = blockedOrigins.get(new URL(request.url()).origin);
+			if (error) report(request, error);
+		});
+		context.on('requestfinished', request => requests.delete(request));
+		context.on('requestfailed', request => requests.delete(request));
+		await context.route('**/*', async route => {
+			try {
+				if (blockedTypes.has(route.request().resourceType())) { await route.abort('blockedbyclient'); return; }
+				await assertPublicUrl(route.request().url(), options);
+				await route.continue();
+			} catch (error) {
+				if (error instanceof BlockedUrlError) report(route.request(), error);
+				await route.abort(error instanceof BlockedUrlError ? 'blockedbyclient' : 'failed').catch(() => undefined);
+			}
+		});
+		await context.routeWebSocket('**/*', socket => socket.close());
+		return context;
+	} catch (error) {
+		proxy.close();
+		await context?.close();
+		throw error;
+	}
+}

package/src/network/privateNetworkAddresses.ts

@@ -0,0 +1,166 @@
+import { isIP } from 'node:net';
+
+/**
+ * Normalizes a URL hostname for address classification.
+ *
+ * WHATWG URL parsing already canonicalizes numeric IPv4 forms such as
+ * `2130706433` and `0x7f.1`. This helper additionally lowercases the value,
+ * removes IPv6 brackets and drops one trailing root-label dot so `localhost.`
+ * and `localhost` are treated the same.
+ *
+ * @param hostname - `URL.hostname` value to normalize.
+ * @returns Lowercase hostname or IP literal without brackets or a trailing dot.
+ *
+ * @example
+ * normalizedUrlHostname(new URL('http://[::1]/').hostname); // '::1'
+ */
+export function normalizedUrlHostname(hostname: string): string {
+	return hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+}
+
+/**
+ * Checks whether a hostname is reserved for the local machine.
+ *
+ * DNS names are otherwise judged by the addresses they resolve to, so this
+ * only covers names that never need a DNS query to reach loopback.
+ *
+ * @param hostname - Hostname normalized with {@link normalizedUrlHostname}.
+ * @returns True for `localhost` and any `*.localhost` name.
+ */
+export function isPrivateHostname(hostname: string): boolean {
+	return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+
+/**
+ * Checks whether an IP address must not be reached by server-side requests.
+ *
+ * The policy blocks loopback, private, link-local (including cloud metadata),
+ * carrier-grade NAT, benchmarking, documentation, multicast and reserved
+ * ranges. IPv6 forms that embed an IPv4 address (mapped, NAT64 and 6to4) are
+ * judged by the embedded address, and tunnelling or deprecated forms that can
+ * reach IPv4 hosts indirectly are blocked outright. Values that are not valid
+ * IP literals return false so callers can resolve them as hostnames instead.
+ *
+ * @param address - IPv4 or IPv6 literal, with or without IPv6 brackets.
+ * @returns True when the address is private, local or reserved.
+ *
+ * @example
+ * isPrivateIpAddress('169.254.169.254'); // true
+ * isPrivateIpAddress('::ffff:7f00:1'); // true (IPv4-mapped 127.0.0.1)
+ * isPrivateIpAddress('93.184.216.34'); // false
+ */
+export function isPrivateIpAddress(address: string): boolean {
+	const normalized = normalizedUrlHostname(address).replace(/%.*$/, '');
+	const version = isIP(normalized);
+
+	if (version === 4) return isPrivateIpv4Octets(normalized.split('.').map(Number));
+	if (version === 6) return isPrivateIpv6Hextets(expandIpv6(normalized));
+
+	return false;
+}
+
+/**
+ * Applies the IPv4 reserved-range policy to four parsed octets.
+ *
+ * @param octets - Parsed IPv4 octets.
+ * @returns True when the address belongs to a blocked range.
+ */
+function isPrivateIpv4Octets(octets: number[]): boolean {
+	if (octets.length !== 4 || octets.some(octet => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+		return true;
+	}
+
+	const [first, second, third] = octets as [number, number, number, number];
+
+	return first === 0
+		|| first === 10
+		|| first === 127
+		|| (first === 100 && second >= 64 && second <= 127)
+		|| (first === 169 && second === 254)
+		|| (first === 172 && second >= 16 && second <= 31)
+		|| (first === 192 && second === 0 && (third === 0 || third === 2))
+		|| (first === 192 && second === 88 && third === 99)
+		|| (first === 192 && second === 168)
+		|| (first === 198 && (second === 18 || second === 19))
+		|| (first === 198 && second === 51 && third === 100)
+		|| (first === 203 && second === 0 && third === 113)
+		|| first >= 224;
+}
+
+/**
+ * Applies the IPv6 reserved-range policy to eight expanded hextets.
+ *
+ * @param hextets - Expanded IPv6 address, or null when it could not be parsed.
+ * @returns True when the address belongs to a blocked range.
+ */
+function isPrivateIpv6Hextets(hextets: number[] | null): boolean {
+	if (!hextets) return true;
+
+	const [h0, h1, h2, h3, h4, h5, h6, h7] = hextets as [number, number, number, number, number, number, number, number];
+	const leadingZeros = h0 === 0 && h1 === 0 && h2 === 0 && h3 === 0 && h4 === 0;
+
+	// ::ffff:a.b.c.d IPv4-mapped addresses reach the embedded IPv4 host.
+	if (leadingZeros && h5 === 0xffff) return isPrivateIpv4Octets(ipv4FromHextets(h6, h7));
+	// ::, ::1 and deprecated ::a.b.c.d IPv4-compatible addresses.
+	if (leadingZeros && h5 === 0) return true;
+	// 64:ff9b::/96 well-known NAT64 prefix translates to the embedded IPv4 host.
+	if (h0 === 0x64 && h1 === 0xff9b && h2 === 0 && h3 === 0 && h4 === 0 && h5 === 0) {
+		return isPrivateIpv4Octets(ipv4FromHextets(h6, h7));
+	}
+	// 64:ff9b:1::/48 local-use NAT64.
+	if (h0 === 0x64 && h1 === 0xff9b && h2 === 1) return true;
+	// 2002::/16 6to4 embeds the relay's IPv4 address in the next 32 bits.
+	if (h0 === 0x2002) return isPrivateIpv4Octets(ipv4FromHextets(h1, h2));
+	// 2001::/32 Teredo tunnelling and 2001:db8::/32 documentation.
+	if (h0 === 0x2001 && (h1 === 0 || h1 === 0xdb8)) return true;
+	// 100::/64 discard-only.
+	if (h0 === 0x100 && h1 === 0 && h2 === 0 && h3 === 0) return true;
+
+	return (h0 & 0xfe00) === 0xfc00 // fc00::/7 unique local
+		|| (h0 & 0xffc0) === 0xfe80 // fe80::/10 link-local
+		|| (h0 & 0xffc0) === 0xfec0 // fec0::/10 deprecated site-local
+		|| (h0 & 0xff00) === 0xff00; // ff00::/8 multicast
+}
+
+/**
+ * Converts two hextets holding an embedded IPv4 address into octets.
+ *
+ * @param high - Hextet containing the first two octets.
+ * @param low - Hextet containing the last two octets.
+ * @returns Four IPv4 octets.
+ */
+function ipv4FromHextets(high: number, low: number): number[] {
+	return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+
+/**
+ * Expands a valid IPv6 literal into eight numeric hextets.
+ *
+ * Supports `::` compression and a trailing dotted IPv4 suffix.
+ *
+ * @param address - IPv6 literal already validated by `net.isIP`.
+ * @returns Eight hextets, or null when the literal cannot be expanded.
+ */
+function expandIpv6(address: string): number[] | null {
+	let value = address;
+	const dotted = value.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+
+	if (dotted) {
+		const octets = dotted[2]!.split('.').map(Number);
+		value = `${dotted[1]}${((octets[0]! << 8) | octets[1]!).toString(16)}:${((octets[2]! << 8) | octets[3]!).toString(16)}`;
+	}
+
+	const [head, tail] = value.split('::') as [string, string | undefined];
+	const headParts = head ? head.split(':') : [];
+	const tailParts = tail === undefined ? [] : tail ? tail.split(':') : [];
+	const missing = 8 - headParts.length - tailParts.length;
+
+	if (tail === undefined ? missing !== 0 : missing < 0) return null;
+
+	const hextets = [...headParts, ...Array<string>(tail === undefined ? 0 : missing).fill('0'), ...tailParts]
+		.map(part => Number.parseInt(part, 16));
+
+	return hextets.length === 8 && hextets.every(part => Number.isInteger(part) && part >= 0 && part <= 0xffff)
+		? hextets
+		: null;
+}

package/src/network/publicAddressLookup.ts

@@ -0,0 +1,49 @@
+import { lookup, type LookupAddress, type LookupOptions } from 'node:dns';
+import { BlockedUrlError } from './BlockedUrlError';
+import { PRIVATE_DESTINATION_MESSAGE } from './assertPublicUrl';
+import { isPrivateIpAddress } from './privateNetworkAddresses';
+
+/** Callback shape used by `dns.lookup` for both single and `all` results. */
+type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void;
+
+/**
+ * DNS lookup that refuses to connect to private, local or reserved addresses.
+ *
+ * It has the same signature as `dns.lookup`, so it can be passed as the
+ * `lookup` socket option of Node's `http`, `https`, `net` and `tls` modules and
+ * to clients built on them (for example undici's `connect.lookup` or got's
+ * `dnsLookup`). Because the check runs when the socket connects, the address
+ * that is validated is the address that is used, which closes the DNS
+ * rebinding gap left by checking a hostname before a separate request.
+ *
+ * Node does not call `lookup` for IP-literal hosts, so literals (including
+ * redirect targets) must still be checked with {@link assertPublicUrl}.
+ *
+ * @param hostname - Hostname being connected to.
+ * @param options - Lookup options supplied by the socket layer.
+ * @param callback - Receives the validated address(es) or a `BlockedUrlError`.
+ *
+ * @example
+ * import { Agent } from 'undici';
+ * const dispatcher = new Agent({ connect: { lookup: publicAddressLookup } });
+ */
+export function publicAddressLookup(hostname: string, options: LookupOptions, callback: LookupCallback): void {
+	lookup(hostname, { ...options, all: true }, (error, addresses) => {
+		if (error) {
+			callback(error, []);
+			return;
+		}
+
+		if (addresses.length === 0 || addresses.some(entry => isPrivateIpAddress(entry.address))) {
+			callback(Object.assign(new BlockedUrlError(PRIVATE_DESTINATION_MESSAGE), { code: 'ERR_BLOCKED_ADDRESS' }), []);
+			return;
+		}
+
+		if (options.all) {
+			callback(null, addresses);
+			return;
+		}
+
+		callback(null, addresses[0]!.address, addresses[0]!.family);
+	});
+}

package/src/notifications/Notifications.ts

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import type { UserIdentity, UserIdentityModel } from '../auth';
+import type { InApp } from '../in-app';
+import type { Mail, MailMessage } from '../mail';
+import type * as notifications from './contracts';
+
+/** Coordinates application-owned notification classes with framework channels. */
+export class Notifications<TUser extends UserIdentity = UserIdentity> {
+	/**
+	 * Creates the notification coordinator used by app().notifications.
+	 *
+	 * @param inApp - Durable framework inbox service.
+	 * @param mail - Provider-neutral framework mail service.
+	 * @param identityModel - Application identity model used to resolve ID recipients.
+	 */
+	constructor(
+		private readonly inApp: InApp,
+		private readonly mail: Mail,
+		private readonly identityModel: UserIdentityModel<TUser>,
+	) {}
+
+	/**
+	 * Delivers one notification to one or more users through its `via()` channels.
+	 *
+	 * @param recipients - User model, ID, or an array mixing both forms.
+	 * @param notification - Application-owned routing and channel renderers.
+	 * @returns One delivery result per distinct resolved user.
+	 */
+	async send(
+		recipients: notifications.NotificationRecipient<TUser> | readonly notifications.NotificationRecipient<TUser>[],
+		notification: notifications.Notification<TUser>,
+	): Promise<notifications.NotificationDelivery[]> {
+		if (!notification.type?.trim()) throw new Error('Notification type is required.');
+		const users = await this.#resolveUsers(recipients);
+		const deliveries: notifications.NotificationDelivery[] = [];
+
+		for (const user of users) deliveries.push(await this.#deliver(user, notification));
+
+		return deliveries;
+	}
+
+	/**
+	 * Delivers selected channels for one canonical user.
+	 *
+	 * @param user - Resolved application identity.
+	 * @param notification - Application-owned routing and content definition.
+	 * @returns Accepted in-app and mail outcomes for the recipient.
+	 */
+	async #deliver(user: TUser, notification: notifications.Notification<TUser>): Promise<notifications.NotificationDelivery> {
+		const userId = String(user.id);
+		const channels = [...new Set(notification.via(user))];
+		if (!channels.length) return { userId, inApp: null, mail: null };
+		if (channels.some(channel => !['inApp', 'mail'].includes(channel))) throw new Error(`Notification "${notification.type}" selected an unsupported channel.`);
+		const scope = notification.scope?.(user) ?? { type: 'account' as const };
+		const key = notification.key?.(user);
+		let inApp = null;
+		let mail = null;
+
+		if (channels.includes('inApp')) {
+			if (!notification.toInApp) throw new Error(`Notification "${notification.type}" selected inApp without a toInApp() renderer.`);
+			[inApp] = await this.inApp.send(userId, notification.toInApp(user), { scope, type: notification.type, key });
+		}
+		if (channels.includes('mail')) {
+			if (!notification.toMail) throw new Error(`Notification "${notification.type}" selected mail without a toMail() renderer.`);
+			mail = await this.mail.send(withDeliveryKey(notification.toMail(user), notification.type, key, userId));
+		}
+
+		return { userId, inApp, mail };
+	}
+
+	/**
+	 * Resolves model and ID inputs, rejecting missing identities before delivery.
+	 *
+	 * @param recipients - User model, ID, or bounded array of either form.
+	 * @returns Distinct canonical users in first-seen order.
+	 */
+	async #resolveUsers(recipients: notifications.NotificationRecipient<TUser> | readonly notifications.NotificationRecipient<TUser>[]): Promise<TUser[]> {
+		const input = Array.isArray(recipients) ? recipients : [recipients];
+		if (input.length > 100) throw new Error('Notifications accepts at most 100 recipients per send.');
+		const users = new Map<string, TUser>();
+
+		for (const recipient of input) {
+			const user = typeof recipient === 'string' ? await this.identityModel.find(recipient) : recipient;
+			if (!user?.id) throw new Error('Notification recipient is unavailable.');
+			users.set(String(user.id), user);
+		}
+
+		return [...users.values()];
+	}
+}
+
+/**
+ * Adds a stable provider retry identity when the renderer did not provide one.
+ *
+ * @param message - Provider-neutral mail content rendered by the notification.
+ * @param type - Stable notification type.
+ * @param key - Optional application-owned occurrence key.
+ * @param userId - Canonical recipient identity.
+ * @returns Original or copied message with an idempotency key when possible.
+ */
+function withDeliveryKey(message: MailMessage, type: string, key: string | undefined, userId: string): MailMessage {
+	if (message.idempotencyKey || !key) return message;
+	const hash = createHash('sha256').update(JSON.stringify([type, key, userId])).digest('hex');
+	return { ...message, idempotencyKey: `notification/${hash}` };
+}

package/src/notifications/README.md

@@ -0,0 +1,59 @@
+# Notifications
+
+`@db3.ai/app/notifications` coordinates application-owned notification classes
+with the framework's durable in-app and mail services. A notification owns its
+channel policy and renderers; it returns content and never performs delivery.
+
+```ts
+import type { Notification } from '@db3.ai/app/notifications';
+import type { User } from '../models/User.js';
+
+class ReportReadyNotification implements Notification<User> {
+	readonly type = 'report.ready';
+
+	constructor(private readonly reportId: string) {}
+
+	via(user: User) {
+		return user.email ? ['inApp', 'mail'] as const : ['inApp'] as const;
+	}
+
+	key(_user: User) {
+		return this.reportId;
+	}
+
+	toInApp(_user: User) {
+		return { title: 'Your report is ready', body: 'Open the report to review it.' };
+	}
+
+	toMail(user: User) {
+		return { to: user.email!, subject: 'Your report is ready', text: 'Open the app to review it.' };
+	}
+}
+
+await app().notifications.send(user, new ReportReadyNotification(reportId));
+await app().notifications.send(users, new ReportReadyNotification(reportId));
+```
+
+An app may add a small convenience method to its user model:
+
+```ts
+public async notify(notification: Notification<this>) {
+	return app().notifications.send(this, notification);
+}
+
+await user.notify(new ReportReadyNotification(reportId));
+```
+
+The service resolves IDs through the configured auth identity model, removes
+duplicate recipients, then stores in-app content before submitting email for
+each user. A stable notification `key()` deduplicates inbox retries and supplies
+a stable mail-provider idempotency key.
+
+The coordinator does not yet persist a generic per-channel delivery log, resolve
+notification preferences, or discover notification classes automatically.
+
+## Error reporting
+
+Use `app().log.error({ err: error }, 'Operation failed')` for operational errors.
+Logging owns configurable email and other transports; application notifications
+remain recipient-facing messages. See [logging](../logging/README.md).