@flowdular/sdk 0.2.4 → 0.3.1

package/modules/auth/src/services/password.ts

@@ -16,6 +16,20 @@ export const DEFAULT_PASSWORD_HASH_OPTIONS: PasswordHashOptions = {
 	maxMemory: 192 * 1024 * 1024,
 };
 
+/**
+ * Stored where an account holds no password at all. `hashPassword` only ever
+ * produces a `scrypt$...` encoding, so no password can hash to this, and
+ * `verifyPassword` refuses it before deriving anything. The account is reached
+ * through the reset flow, an administrative temporary password, or an external
+ * identity; nothing about it is guessable, because there is nothing to guess.
+ */
+export const UNUSABLE_PASSWORD_HASH = 'none$unusable';
+
+/** False only for an account created without a password and never given one. */
+export function passwordIsSet(encoded: string): boolean {
+	return encoded !== UNUSABLE_PASSWORD_HASH;
+}
+
 function derive(
 	password: string,
 	salt: Buffer,

package/modules/auth/src/services/provider-secret-rotation.ts

@@ -0,0 +1,169 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import type { ProviderSecretVault } from './provider-secrets.ts';
+
+/** Rows re-sealed inside one transaction, per workspace. */
+export const PROVIDER_ROTATION_BATCH = 200;
+
+export const PROVIDER_ROTATION_TABLE = 'auth_identity_providers';
+
+export interface ProviderKeyCount {
+	readonly keyId: string;
+	readonly rows: number;
+}
+
+export interface ProviderRotationReport {
+	readonly table: string;
+	/** Key id every row should end on: the current key of the vault. */
+	readonly currentKeyId: string;
+	readonly counts: readonly ProviderKeyCount[];
+	/** Rows on a retired key when the run started. */
+	readonly stale: number;
+	readonly rotated: number;
+	/** Rows an administrator rewrote between the read and the update. */
+	readonly skipped: number;
+}
+
+export interface ProviderRotationOptions {
+	/**
+	 * The tenant-scoped runtime handle. A provider row is workspace data under a
+	 * forced policy, so every statement runs under the workspace that owns it and
+	 * the run walks the workspaces one at a time.
+	 */
+	readonly database: DatabaseHandle;
+	/** The workspaces to walk; the caller reads them on the routing handle. */
+	readonly tenants: () => Promise<readonly string[]>;
+	readonly vault: ProviderSecretVault;
+	readonly apply?: boolean;
+	readonly batchSize?: number;
+}
+
+interface StaleRow {
+	id: string;
+	client_secret_ciphertext: string;
+	client_secret_key_id: string;
+}
+
+const SQL = {
+	counts: `SELECT client_secret_key_id, count(*) AS row_count
+	         FROM auth_identity_providers
+	         WHERE tenant_id = $1
+	         GROUP BY client_secret_key_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, client_secret_ciphertext, client_secret_key_id
+	             FROM auth_identity_providers
+	             WHERE tenant_id = $1 AND client_secret_key_id IS DISTINCT FROM $2
+	               AND id > $3
+	             ORDER BY id
+	             LIMIT $4`,
+	/* The envelope the row still holds is the optimistic check: a secret an
+	   administrator rotated in between keeps its own envelope, and the
+	   fingerprint is left alone because the secret behind it did not change. */
+	reseal: `UPDATE auth_identity_providers
+	         SET client_secret_ciphertext = $1, client_secret_key_id = $2
+	         WHERE tenant_id = $3 AND id = $4 AND client_secret_ciphertext = $5`,
+};
+
+function count(value: number | bigint | string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized)) {
+		throw new Error('The auth database returned an invalid count.');
+	}
+	return normalized;
+}
+
+/**
+ * Re-seals every tenant-owned provider secret that is not on the current key.
+ * The inventory is read once per workspace and each batch is read, opened,
+ * re-sealed and written inside one transaction. It is idempotent: a second run
+ * finds nothing to do, and a sign-in keeps working throughout because the
+ * retired key stays on the ring until the operator drops it.
+ */
+export async function rotateProviderSecrets(
+	options: ProviderRotationOptions,
+): Promise<ProviderRotationReport> {
+	const currentKeyId = options.vault.keyId;
+	const batchSize = options.batchSize ?? PROVIDER_ROTATION_BATCH;
+	const tenants = await options.tenants();
+	const totals = new Map<string, number>();
+	for (const tenantId of tenants) {
+		const rows = await options.database.transaction(
+			async (transaction) =>
+				(
+					await transaction.query<{
+						client_secret_key_id: string;
+						row_count: number | bigint | string;
+					}>({ text: SQL.counts, parameters: [tenantId] })
+				).rows,
+			{ access: 'read', tenantId },
+		);
+		for (const row of rows) {
+			totals.set(
+				row.client_secret_key_id,
+				(totals.get(row.client_secret_key_id) ?? 0) + count(row.row_count),
+			);
+		}
+	}
+	const counts = [...totals]
+		.map(([keyId, rows]) => ({ keyId, rows }))
+		.sort((left, right) => left.keyId.localeCompare(right.keyId));
+	const stale = counts.reduce(
+		(total, entry) =>
+			entry.keyId === currentKeyId ? total : total + entry.rows,
+		0,
+	);
+	const report = {
+		table: PROVIDER_ROTATION_TABLE,
+		currentKeyId,
+		counts,
+		stale,
+	};
+	if (options.apply !== true) return { ...report, rotated: 0, skipped: 0 };
+	let rotated = 0;
+	let skipped = 0;
+	for (const tenantId of tenants) {
+		let cursor = '';
+		for (;;) {
+			const batch = await options.database.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 = { tenantId, providerId: row.id };
+						const sealed = options.vault.seal(
+							context,
+							options.vault.open(
+								context,
+								row.client_secret_ciphertext,
+								row.client_secret_key_id,
+							),
+						);
+						const result = await transaction.execute({
+							text: SQL.reseal,
+							parameters: [
+								sealed.ciphertext,
+								sealed.keyId,
+								tenantId,
+								row.id,
+								row.client_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/auth/src/services/provider-secrets.ts

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { createKeyring, parsePreviousKeys } from '@flowdular/sdk/kernel';
+import { AuthServiceError } from './auth-service-error.ts';
+
+/* The tenant provider secret shares the auth keyring with the enrolled TOTP
+   factors and is separated from them by this context: an envelope sealed for
+   one provider of one workspace cannot be opened as another's, so a stolen row
+   is not portable between workspaces. */
+const SECRET_CONTEXT = 'flowdular:auth:provider-secret:v1';
+const FINGERPRINT_CONTEXT = 'flowdular:auth:provider-fingerprint:v1';
+const FINGERPRINT_LENGTH = 32;
+
+/** The row a sealed secret belongs to; it is the additional authenticated data. */
+export interface ProviderSecretContext {
+	readonly tenantId: string;
+	readonly providerId: string;
+}
+
+export interface SealedProviderSecret {
+	readonly keyId: string;
+	readonly ciphertext: string;
+}
+
+export interface ProviderSecretVault {
+	/** Key id every new envelope is written with; stored rows may carry older ones. */
+	readonly keyId: string;
+	seal(context: ProviderSecretContext, secret: string): SealedProviderSecret;
+	open(
+		context: ProviderSecretContext,
+		ciphertext: string,
+		keyId?: string | null,
+	): string;
+	fingerprint(secret: string): string;
+}
+
+function keyRequired(): AuthServiceError {
+	return new AuthServiceError(
+		'PROVIDER_KEY_REQUIRED',
+		'Workspace identity providers need the deployment authentication encryption key.',
+		409,
+	);
+}
+
+function secretUnreadable(cause?: unknown): AuthServiceError {
+	return new AuthServiceError(
+		'PROVIDER_SECRET_INVALID',
+		'The stored provider secret cannot be opened with the configured keys.',
+		500,
+		cause === undefined ? undefined : { cause },
+	);
+}
+
+function encryptionKey(value: string | undefined): Buffer {
+	if (!value) throw keyRequired();
+	const key = Buffer.from(
+		value,
+		/^[0-9a-f]{64}$/i.test(value) ? 'hex' : 'base64url',
+	);
+	if (key.byteLength !== 32) throw keyRequired();
+	return key;
+}
+
+function additionalData(context: ProviderSecretContext): string {
+	return `${SECRET_CONTEXT}\0${context.tenantId}\0${context.providerId}`;
+}
+
+/**
+ * What an administrator sees instead of a client secret. It is taken over the
+ * secret itself rather than over an envelope, so re-sealing the same secret
+ * under a new key leaves it unchanged and only a rotated secret moves it. It is
+ * taken over workspace secrets only: a deployment secret is shared by every
+ * workspace, so no workspace is shown a value derived from it.
+ */
+export function providerSecretFingerprint(secret: string): string {
+	return createHash('sha256')
+		.update(FINGERPRINT_CONTEXT, 'utf8')
+		.update('\0', 'utf8')
+		.update(secret, 'utf8')
+		.digest('hex')
+		.slice(0, FINGERPRINT_LENGTH);
+}
+
+/**
+ * The client secrets of tenant-owned providers, sealed with the auth keyring
+ * under a provider-specific context. The envelope is `iv.ciphertext.tag` in
+ * base64url beside the id of the key that sealed it, exactly the shape the
+ * enrolled factors use, so `auth secrets-rotate` re-seals both the same way.
+ */
+export function createProviderSecretVault(
+	current: string | undefined,
+	previous: readonly string[] = [],
+): ProviderSecretVault {
+	const keyring = createKeyring({
+		current: encryptionKey(current),
+		previous: previous.map((entry) => encryptionKey(entry)),
+	});
+	return {
+		keyId: keyring.keyId,
+		seal(context, secret) {
+			const sealed = keyring.seal(secret, additionalData(context));
+			return {
+				keyId: sealed.keyId,
+				ciphertext: `${sealed.iv.toString('base64url')}.${sealed.ciphertext.toString('base64url')}.${sealed.tag.toString('base64url')}`,
+			};
+		},
+		open(context, ciphertext, keyId) {
+			const [ivValue, ciphertextValue, tagValue] = ciphertext.split('.');
+			if (!ivValue || !ciphertextValue || !tagValue) throw secretUnreadable();
+			try {
+				return keyring
+					.open(
+						{
+							keyId: keyId ?? undefined,
+							iv: Buffer.from(ivValue, 'base64url'),
+							tag: Buffer.from(tagValue, 'base64url'),
+							ciphertext: Buffer.from(ciphertextValue, 'base64url'),
+						},
+						additionalData(context),
+					)
+					.toString('utf8');
+			} catch (error) {
+				throw secretUnreadable(error);
+			}
+		},
+		fingerprint: providerSecretFingerprint,
+	};
+}
+
+export function providerSecretVaultFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+): ProviderSecretVault {
+	return createProviderSecretVault(
+		environment.FD_AUTH_MFA_KEY,
+		parsePreviousKeys(environment.FD_AUTH_MFA_KEY_PREVIOUS, (entry) => entry),
+	);
+}