@flowdular/sdk 0.2.3 → 0.3.0

package/modules/notifications/src/services/repository.ts

@@ -0,0 +1,342 @@
+import type {
+	DeliveryAttempt,
+	DeliveryRouting,
+	DeliveryStatus,
+	MemberNotificationSettings,
+	NotificationKind,
+	NotificationPreference,
+	NotificationsInbox,
+	NotificationsInboxStatus,
+	WebhookSubscription,
+	WebhookSubscriptionStatus,
+} from '../domain/types.ts';
+import type { EncryptedSecret } from './secret-vault.ts';
+
+/** A subscription with its sealed secret. Never leaves the service layer. */
+export interface StoredWebhookSubscription extends WebhookSubscription {
+	readonly secret: EncryptedSecret;
+}
+
+export interface InboxFilters {
+	/** Absent means the open inbox: every item the member has not archived. */
+	readonly status?: NotificationsInboxStatus | undefined;
+	readonly kind?: NotificationKind | undefined;
+}
+
+export interface SubscriptionFilters {
+	readonly status?: WebhookSubscriptionStatus | undefined;
+	/** A substring of the name or the URL. */
+	readonly search?: string | undefined;
+}
+
+export interface DeliveryFilters {
+	readonly status?: DeliveryStatus | undefined;
+	readonly subscriptionId?: string | undefined;
+	/** A substring of the source reference or the source module. */
+	readonly search?: string | undefined;
+}
+
+export type PageDirection = 'asc' | 'desc';
+
+/** The sort value and the id of the row a page ends on. */
+export interface PageKey<Key extends string | number> {
+	readonly key: Key;
+	readonly id: string;
+}
+
+/**
+ * One keyset page of a list. Every list sorts on one column and the id, both
+ * in `direction`; `after` is the last row of the previous page, so the read is
+ * a range on the list's page index rather than an offset into it.
+ */
+export interface ListPage<Key extends string | number> {
+	readonly limit: number;
+	readonly direction: PageDirection;
+	readonly after: PageKey<Key> | null;
+}
+
+export interface PagedRows<Row, Key extends string | number> {
+	readonly rows: readonly Row[];
+	/** The key of the last row when the page is full, so a caller can go on; null on a short page. */
+	readonly next: PageKey<Key> | null;
+}
+
+export interface CompleteDeliveryInput {
+	readonly tenantId: string;
+	readonly id: string;
+	readonly status: Exclude<DeliveryStatus, 'pending'>;
+	readonly completedAt: number;
+	readonly responseStatus: number | null;
+	readonly errorClass: string | null;
+}
+
+export interface ClaimDeliveryInput {
+	readonly tenantId: string;
+	readonly id: string;
+	/** Claim stamp, and the due bound: an attempt scheduled later is not taken. */
+	readonly now: number;
+	/** A claim stamped at or before this was abandoned and may be taken over. */
+	readonly strandedBefore: number;
+}
+
+/**
+ * One published event, written in a single tenant-scoped write transaction.
+ * The two builders are pure: the service decides what a row looks like, the
+ * adapter decides when it is written and under which transaction.
+ */
+export interface PublishEventInput {
+	readonly tenantId: string;
+	readonly kind: NotificationKind;
+	readonly sourceRef: string;
+	readonly recipients: readonly string[];
+	readonly inboxItem: (recipientAccountId: string) => NotificationsInbox;
+	readonly delivery: (subscription: WebhookSubscription) => DeliveryAttempt;
+	/** Queued for every addressed member who turned e-mail delivery on. */
+	readonly emailDelivery: (item: NotificationsInbox) => DeliveryAttempt;
+}
+
+export interface PublishEventResult {
+	readonly inboxItemIds: readonly string[];
+	readonly deliveryIds: readonly string[];
+}
+
+/**
+ * Where a keyset page ended. Both columns are written once and never updated,
+ * so a walk resumed from one cannot revisit or skip a row while the table is
+ * still being written to.
+ */
+export interface ExportCursor {
+	readonly createdAt: number;
+	readonly id: string;
+}
+
+/**
+ * The persistence port. Async and database agnostic: the PostgreSQL statements,
+ * the tenant transactions and the background lease live in the adapter.
+ */
+export interface NotificationsRepository {
+	/**
+	 * Idempotent on (tenantId, kind, sourceRef). A repeat writes nothing and
+	 * answers with the identifiers the first publication created.
+	 */
+	publish(input: PublishEventInput): Promise<PublishEventResult>;
+
+	/** One page of the member's own inbox, by creation time and id. */
+	listInbox(
+		tenantId: string,
+		recipientAccountId: string,
+		filters: InboxFilters,
+		page: ListPage<number>,
+	): Promise<PagedRows<NotificationsInbox, number>>;
+	countUnreadInbox(
+		tenantId: string,
+		recipientAccountId: string,
+	): Promise<number>;
+	getInboxItem(
+		tenantId: string,
+		recipientAccountId: string,
+		id: string,
+	): Promise<NotificationsInbox | null>;
+	/**
+	 * The item one published event wrote for one member, by the natural key the
+	 * publication is idempotent on. The e-mail channel reads the body from it at
+	 * send time instead of copying it onto the attempt row.
+	 */
+	findInboxItem(
+		tenantId: string,
+		recipientAccountId: string,
+		kind: NotificationKind,
+		sourceRef: string,
+	): Promise<NotificationsInbox | null>;
+	setInboxStatus(
+		tenantId: string,
+		recipientAccountId: string,
+		id: string,
+		status: NotificationsInboxStatus,
+		readAt: string | null,
+	): Promise<NotificationsInbox | null>;
+	/**
+	 * Writes the items an event produced outside a publication, skipping repeats
+	 * and, exactly like `publish`, every recipient who disabled that kind.
+	 */
+	appendInboxItems(
+		tenantId: string,
+		records: readonly NotificationsInbox[],
+		emailDelivery: (item: NotificationsInbox) => DeliveryAttempt,
+	): Promise<readonly string[]>;
+	/**
+	 * Every inbox item of one workspace, oldest first, one keyset page at a
+	 * time. This is the workspace export of `notifications.core.inbox`, so it
+	 * crosses recipients; the member-facing reads never do.
+	 */
+	exportInboxPage(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly NotificationsInbox[]>;
+	/**
+	 * Removes at most `limit` inbox items created strictly before `before`.
+	 * Nothing else deletes an item by age, so this is the whole retention path
+	 * of the class.
+	 */
+	deleteInboxItemsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+
+	listPreferences(
+		tenantId: string,
+		recipientAccountId: string,
+	): Promise<readonly NotificationPreference[]>;
+	savePreference(
+		record: NotificationPreference,
+	): Promise<NotificationPreference>;
+	/** Null when the member never saved one; the caller applies the defaults. */
+	getMemberSettings(
+		tenantId: string,
+		recipientAccountId: string,
+	): Promise<MemberNotificationSettings | null>;
+	saveMemberSettings(
+		record: MemberNotificationSettings,
+	): Promise<MemberNotificationSettings>;
+
+	/**
+	 * One page of the workspace's subscriptions by normalized name and id. The
+	 * key of a row is `lower(name)` as the database computes it, so a cursor
+	 * compares exactly the way the page index orders.
+	 */
+	listSubscriptions(
+		tenantId: string,
+		filters: SubscriptionFilters,
+		page: ListPage<string>,
+	): Promise<PagedRows<StoredWebhookSubscription, string>>;
+	getSubscription(
+		tenantId: string,
+		id: string,
+	): Promise<StoredWebhookSubscription | null>;
+	/** Null when the normalized name is already taken in the tenant. */
+	createSubscription(
+		record: StoredWebhookSubscription,
+	): Promise<StoredWebhookSubscription | null>;
+	/** Null when the row is gone, `'conflict'` when the new name is taken. */
+	updateSubscription(
+		record: Pick<
+			WebhookSubscription,
+			| 'tenantId'
+			| 'id'
+			| 'name'
+			| 'url'
+			| 'events'
+			| 'description'
+			| 'updatedAt'
+		>,
+	): Promise<StoredWebhookSubscription | null | 'conflict'>;
+	setSubscriptionStatus(
+		tenantId: string,
+		id: string,
+		status: WebhookSubscriptionStatus,
+		updatedAt: number,
+	): Promise<StoredWebhookSubscription | null>;
+	/**
+	 * Moves the subscription to disabled and drops its pending attempts in the
+	 * same write, so no queued delivery can leave after the subscription stopped
+	 * accepting events. The ledger of completed attempts is untouched.
+	 */
+	disableSubscription(
+		tenantId: string,
+		id: string,
+		updatedAt: number,
+	): Promise<StoredWebhookSubscription | null>;
+	rotateSubscriptionSecret(
+		tenantId: string,
+		id: string,
+		secret: EncryptedSecret,
+		fingerprint: string,
+		updatedAt: number,
+	): Promise<StoredWebhookSubscription | null>;
+	/** Deletes the subscription and its pending attempts; the ledger stays. */
+	deleteSubscription(tenantId: string, id: string): Promise<boolean>;
+	stampSubscriptionDelivery(
+		tenantId: string,
+		id: string,
+		at: number,
+	): Promise<void>;
+
+	/** One page of the ledger by schedule time and id. */
+	listDeliveries(
+		tenantId: string,
+		filters: DeliveryFilters,
+		page: ListPage<number>,
+	): Promise<PagedRows<DeliveryAttempt, number>>;
+	getDelivery(tenantId: string, id: string): Promise<DeliveryAttempt | null>;
+	/** Null when an attempt with the same sequence and number already exists. */
+	appendDelivery(record: DeliveryAttempt): Promise<DeliveryAttempt | null>;
+	/**
+	 * Takes one due attempt for this process, under the tenant the routing row
+	 * named, and returns the row it claimed. Null when the attempt moved on, is
+	 * not due yet, or is held by a claim that has not gone stale: that is what
+	 * keeps a second process draining the same queue from repeating the request.
+	 */
+	claimDelivery(input: ClaimDeliveryInput): Promise<DeliveryAttempt | null>;
+	/**
+	 * Returns a claimed attempt to the queue at `scheduledFor`. The attempt
+	 * number, the outcome and every other ledger field stay untouched, so a
+	 * subscription that is holding its queue still counts no attempt.
+	 */
+	releaseDelivery(
+		tenantId: string,
+		id: string,
+		scheduledFor: number,
+	): Promise<boolean>;
+	/** Moves one open attempt, pending or claimed, to a terminal state. */
+	completeDelivery(input: CompleteDeliveryInput): Promise<boolean>;
+	/** Highest attempt run recorded for one event on one delivery target. */
+	latestDeliverySequence(
+		attempt: Pick<
+			DeliveryAttempt,
+			| 'tenantId'
+			| 'channel'
+			| 'subscriptionId'
+			| 'recipientAccountId'
+			| 'kind'
+			| 'sourceRef'
+		>,
+	): Promise<number>;
+
+	/** Cross-tenant, routing columns only, on the read-only background lease. */
+	listDueDeliveries(
+		now: number,
+		limit: number,
+	): Promise<readonly DeliveryRouting[]>;
+	/**
+	 * Cross-tenant claims stamped at or before `before`, whose claimant never
+	 * came back. A claim is invisible to the due query, so a process that died
+	 * mid-send would strand its rows without this second, equally bounded read.
+	 */
+	listStrandedDeliveries(
+		before: number,
+		limit: number,
+	): Promise<readonly DeliveryRouting[]>;
+	/**
+	 * Cross-tenant tenant list for retention, routing columns only. `after` is
+	 * the last tenant id the previous page ended on, so a deployment with more
+	 * tenants than one page still gets every one of them swept in turn.
+	 */
+	listDeliveryTenants(limit: number, after: string): Promise<readonly string[]>;
+	deleteCompletedDeliveriesBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	/**
+	 * Every delivery attempt of one workspace, oldest first, one keyset page at
+	 * a time. The key is the row's own creation, not the mutable schedule or
+	 * completion the queue works from.
+	 */
+	exportDeliveriesPage(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly DeliveryAttempt[]>;
+}

package/modules/notifications/src/services/secret-rotation.ts

@@ -0,0 +1,177 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { secretContext, type SecretVault } from './secret-vault.ts';
+
+/** Rows re-sealed inside one tenant-scoped transaction. */
+export const SECRET_ROTATION_BATCH = 200;
+
+export const SECRET_ROTATION_TABLE = 'notifications_webhook_subscriptions';
+
+export interface SecretKeyCount {
+	readonly keyId: string;
+	readonly rows: number;
+}
+
+export interface SecretRotationReport {
+	readonly table: string;
+	/** Key id every row should end on: the current key of the vault. */
+	readonly currentKeyId: string;
+	readonly counts: readonly SecretKeyCount[];
+	/** Rows on a retired key when the run started. */
+	readonly stale: number;
+	readonly tenants: number;
+	readonly rotated: number;
+	/** Rows a concurrent write changed between the read and the update. */
+	readonly skipped: number;
+}
+
+export interface SecretRotationOptions {
+	/** Tenant-scoped handle. Every read and write of a row runs on it. */
+	readonly runtime: DatabaseHandle;
+	/** Cross-tenant handle. It is granted the key ids and nothing else. */
+	readonly background: DatabaseHandle;
+	readonly vault: SecretVault;
+	readonly apply?: boolean;
+	readonly batchSize?: number;
+}
+
+interface StaleRow {
+	id: string;
+	secret_key_id: string;
+	secret_iv: string;
+	secret_tag: string;
+	secret_ciphertext: string;
+}
+
+const SQL = {
+	counts: `SELECT secret_key_id AS key_id, count(*) AS row_count
+	         FROM notifications_webhook_subscriptions
+	         GROUP BY secret_key_id
+	         ORDER BY secret_key_id`,
+	staleTenants: `SELECT tenant_id, count(*) AS row_count
+	               FROM notifications_webhook_subscriptions
+	               WHERE secret_key_id <> $1
+	               GROUP BY tenant_id
+	               ORDER BY tenant_id`,
+	/* Paged by primary key: a row the optimistic update skipped stays stale, so
+	   a query that only asked for stale rows would return it forever. */
+	staleBatch: `SELECT id, secret_key_id, secret_iv, secret_tag, secret_ciphertext
+	             FROM notifications_webhook_subscriptions
+	             WHERE tenant_id = $1 AND secret_key_id <> $2 AND id > $3
+	             ORDER BY id
+	             LIMIT $4`,
+	/* The envelope the row still holds is the optimistic check: a secret rotated
+	   by the application in between keeps its own value. secret_revision counts
+	   secret changes a caller can see, and a re-seal is not one, so neither it
+	   nor the fingerprint moves here. */
+	reseal: `UPDATE notifications_webhook_subscriptions
+	         SET secret_key_id = $1, secret_iv = $2, secret_tag = $3,
+	             secret_ciphertext = $4
+	         WHERE tenant_id = $5 AND id = $6 AND secret_ciphertext = $7`,
+};
+
+function count(value: number | bigint | string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized)) {
+		throw new Error('The notifications database returned an invalid count.');
+	}
+	return normalized;
+}
+
+/**
+ * Re-seals every stored webhook signing secret that is not on the current key.
+ * The inventory is read once across tenants, and each batch of rows is read,
+ * decrypted, re-sealed and written inside one transaction scoped to the tenant
+ * that owns them. It is idempotent: a second run finds nothing to do.
+ */
+export async function rotateWebhookSecrets(
+	options: SecretRotationOptions,
+): Promise<SecretRotationReport> {
+	const currentKeyId = options.vault.keyId;
+	const batchSize = options.batchSize ?? SECRET_ROTATION_BATCH;
+	const inventory = await options.background.transaction(
+		async (transaction) => ({
+			counts: (
+				await transaction.query<{
+					key_id: string;
+					row_count: number | bigint | string;
+				}>({ text: SQL.counts })
+			).rows,
+			stale: (
+				await transaction.query<{
+					tenant_id: string;
+					row_count: number | bigint | string;
+				}>({ text: SQL.staleTenants, parameters: [currentKeyId] })
+			).rows,
+		}),
+		{ access: 'read' },
+	);
+	const report = {
+		table: SECRET_ROTATION_TABLE,
+		currentKeyId,
+		counts: inventory.counts.map((row) => ({
+			keyId: row.key_id,
+			rows: count(row.row_count),
+		})),
+		stale: inventory.stale.reduce(
+			(total, row) => total + count(row.row_count),
+			0,
+		),
+		tenants: inventory.stale.length,
+	};
+	if (options.apply !== true) {
+		return { ...report, rotated: 0, skipped: 0 };
+	}
+	let rotated = 0;
+	let skipped = 0;
+	for (const { tenant_id: tenantId } of inventory.stale) {
+		let cursor = '';
+		for (;;) {
+			const batch = await options.runtime.transaction(
+				async (transaction) => {
+					const rows = (
+						await transaction.query<StaleRow>({
+							text: SQL.staleBatch,
+							parameters: [tenantId, currentKeyId, cursor, batchSize],
+						})
+					).rows;
+					let written = 0;
+					for (const row of rows) {
+						const context = secretContext(tenantId, row.id);
+						const sealed = options.vault.encrypt(
+							options.vault.decrypt(
+								{
+									keyId: row.secret_key_id,
+									iv: row.secret_iv,
+									tag: row.secret_tag,
+									ciphertext: row.secret_ciphertext,
+								},
+								context,
+							),
+							context,
+						);
+						const result = await transaction.execute({
+							text: SQL.reseal,
+							parameters: [
+								sealed.keyId,
+								sealed.iv,
+								sealed.tag,
+								sealed.ciphertext,
+								tenantId,
+								row.id,
+								row.secret_ciphertext,
+							],
+						});
+						written += result.affectedRows;
+					}
+					return { read: rows.length, written, last: rows.at(-1)?.id };
+				},
+				{ access: 'write', tenantId },
+			);
+			rotated += batch.written;
+			skipped += batch.read - batch.written;
+			if (batch.read < batchSize || batch.last === undefined) break;
+			cursor = batch.last;
+		}
+	}
+	return { ...report, rotated, skipped };
+}

package/modules/notifications/src/services/secret-vault.ts

@@ -0,0 +1,168 @@
+import { createHash, randomBytes } from 'node:crypto';
+import {
+	closeSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import {
+	createKeyring,
+	KeyringError,
+	parsePreviousKeys,
+	type Keyring,
+} from '@flowdular/sdk/kernel';
+import { flowdularLocalDataPath } from '@flowdular/sdk/kernel/legacy-local-state';
+
+export interface EncryptedSecret {
+	readonly keyId: string;
+	readonly iv: string;
+	readonly tag: string;
+	readonly ciphertext: string;
+}
+
+/** Bytes of a generated signing secret before base64url encoding. */
+export const WEBHOOK_SECRET_BYTES = 32;
+/** Characters of the SHA-256 an administrator compares after a rotation. */
+export const SECRET_FINGERPRINT_LENGTH = 32;
+
+/**
+ * The additional data every webhook secret envelope is bound to. It is part of
+ * the stored envelope: a rotation engine re-sealing a row under a new key must
+ * rebuild exactly this string, so it lives with the envelope format.
+ */
+export function secretContext(
+	tenantId: string,
+	subscriptionId: string,
+): string {
+	return `${tenantId}:${subscriptionId}:notifications-webhook`;
+}
+
+export function generateWebhookSecret(): string {
+	return randomBytes(WEBHOOK_SECRET_BYTES).toString('base64url');
+}
+
+/** Shown to administrators so a rotation is verifiable without the secret. */
+export function secretFingerprint(secret: string): string {
+	return createHash('sha256')
+		.update(secret, 'utf8')
+		.digest('hex')
+		.slice(0, SECRET_FINGERPRINT_LENGTH);
+}
+
+export interface SecretVault {
+	/** Key id every new envelope is written with; stored rows may carry older ones. */
+	readonly keyId: string;
+	encrypt(secret: string, context: string): EncryptedSecret;
+	decrypt(envelope: EncryptedSecret, context: string): string;
+}
+
+function encryptionKey(
+	value: string,
+	variable = 'FD_NOTIFICATIONS_SECRET_KEY',
+): Buffer {
+	const key = Buffer.from(value.trim(), 'base64');
+	if (key.byteLength !== 32) {
+		key.fill(0);
+		throw new Error(`${variable} must be a base64-encoded 32-byte key.`);
+	}
+	return key;
+}
+
+export class AesGcmSecretVault implements SecretVault {
+	readonly #keyring: Keyring;
+
+	/* `previous` holds the keys a rotation has not finished retiring: they open
+	   stored rows, and nothing is ever written with them. */
+	constructor(key: Buffer, previous: readonly Buffer[] = []) {
+		if (key.byteLength !== 32) {
+			throw new Error('Webhook secret encryption requires a 32-byte key.');
+		}
+		this.#keyring = createKeyring({ current: key, previous });
+	}
+
+	get keyId(): string {
+		return this.#keyring.keyId;
+	}
+
+	encrypt(secret: string, context: string): EncryptedSecret {
+		const normalized = secret.trim();
+		if (normalized.length < 8 || normalized.length > 16_384) {
+			throw new Error('Webhook secrets must contain 8 to 16384 characters.');
+		}
+		const sealed = this.#keyring.seal(normalized, context);
+		return {
+			keyId: sealed.keyId,
+			iv: sealed.iv.toString('base64'),
+			tag: sealed.tag.toString('base64'),
+			ciphertext: sealed.ciphertext.toString('base64'),
+		};
+	}
+
+	decrypt(envelope: EncryptedSecret, context: string): string {
+		try {
+			return this.#keyring
+				.open(
+					{
+						keyId: envelope.keyId,
+						iv: Buffer.from(envelope.iv, 'base64'),
+						tag: Buffer.from(envelope.tag, 'base64'),
+						ciphertext: Buffer.from(envelope.ciphertext, 'base64'),
+					},
+					context,
+				)
+				.toString('utf8');
+		} catch (error) {
+			if (error instanceof KeyringError && error.code === 'KEY_UNKNOWN') {
+				throw new Error('The webhook secret encryption key is unavailable.', {
+					cause: error,
+				});
+			}
+			throw error;
+		}
+	}
+}
+
+function developmentKey(path: string): Buffer {
+	try {
+		return encryptionKey(readFileSync(path, 'utf8'));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+	}
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const descriptor = openSync(path, 'wx', 0o600);
+	try {
+		const encoded = randomBytes(32).toString('base64');
+		writeFileSync(descriptor, encoded, { encoding: 'utf8' });
+		return encryptionKey(encoded);
+	} finally {
+		closeSync(descriptor);
+	}
+}
+
+export function secretVaultFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+	workspaceRoot = process.cwd(),
+): SecretVault {
+	const previous = parsePreviousKeys(
+		environment.FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS,
+		(entry) => encryptionKey(entry, 'FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS'),
+	);
+	const configured = environment.FD_NOTIFICATIONS_SECRET_KEY;
+	if (configured) {
+		return new AesGcmSecretVault(encryptionKey(configured), previous);
+	}
+	if (environment.NODE_ENV === 'production') {
+		throw new Error('FD_NOTIFICATIONS_SECRET_KEY is required in production.');
+	}
+	if (environment.NODE_ENV === 'test') {
+		return new AesGcmSecretVault(Buffer.alloc(32, 0x4e), previous);
+	}
+	return new AesGcmSecretVault(
+		developmentKey(
+			flowdularLocalDataPath(workspaceRoot, 'notifications-secret.key'),
+		),
+		previous,
+	);
+}