create-flowdular 0.5.1 → 0.6.0

package/template/default/platform/src/server/runtime-role.ts

@@ -0,0 +1,33 @@
+import type { ModuleServerComposition } from '@flowdular/sdk/server';
+
+/* combined serves HTTP and runs every module worker in one process. web serves
+   HTTP only: its compositions start, but no module worker loop, poller or
+   wake-driven claim runs there, so a host that freezes idle instances never
+   strands work. The loops a web process still runs are auth.core's expired
+   session sweep (auth.core.sessions) and settings log sweep
+   (auth.core.settings-log), which start with the auth service in every role;
+   freezing them only delays deleting rows no lookup needs and writing a
+   platform settings event its saving process deferred. tick runs the module
+   workers only inside an authenticated tick request, which drains them before
+   it answers. */
+export type PlatformRuntimeRole = 'combined' | 'web' | 'tick';
+
+export function platformRuntimeRole(
+	environment: NodeJS.ProcessEnv,
+): PlatformRuntimeRole {
+	const role = environment.FD_RUNTIME_ROLE?.trim() || 'combined';
+	if (role !== 'combined' && role !== 'web' && role !== 'tick') {
+		throw new Error('FD_RUNTIME_ROLE must be "combined", "web" or "tick".');
+	}
+	return role;
+}
+
+/* Awaited in composition order, so a failed worker start fails the boot before
+   the process reports itself ready. */
+export async function startModuleWorkers(
+	compositions: readonly ModuleServerComposition[],
+	role: PlatformRuntimeRole,
+): Promise<void> {
+	if (role !== 'combined') return;
+	for (const composition of compositions) await composition.startWorker?.();
+}

package/template/default/platform/src/server/setup/access.ts

@@ -0,0 +1,160 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+/* The first-run screen runs before any account exists, so there is nothing to
+   authenticate against. Access is bound to a token minted at boot, printed to
+   stdout and written to the state directory, the way Grafana and Jupyter hand
+   an operator their first credential. */
+
+export const SETUP_TOKEN_BYTES = 32;
+export const SETUP_SESSION_COOKIE = 'flowdular_setup';
+export const SETUP_CSRF_FIELD = 'setupCsrf';
+
+const MAX_TOKEN_FAILURES = 5;
+const LOCKOUT_MS = 5 * 60 * 1000;
+const SESSION_TTL_MS = 30 * 60 * 1000;
+
+export type SetupAccessVerdict = 'granted' | 'denied' | 'locked';
+
+export interface SetupSession {
+	readonly id: string;
+	readonly csrfToken: string;
+	expiresAt: number;
+	/* The configuration under review, held only in this process. Secrets never
+	   reach a cookie, a log, or the disk before the operator confirms. */
+	pending: unknown;
+}
+
+export interface SetupAccess {
+	/** Constant-time token check with a shared lockout after repeated failures. */
+	open(presented: string | null): {
+		readonly verdict: SetupAccessVerdict;
+		readonly session: SetupSession | null;
+		readonly retryAfterMs: number;
+	};
+	/** The live session for a cookie value, or null once it expired or rotated. */
+	resume(sessionId: string | null): SetupSession | null;
+	/** True only for the CSRF token minted with this session. */
+	verifyCsrf(session: SetupSession, presented: string | null): boolean;
+	close(): void;
+}
+
+/* timingSafeEqual needs equal lengths, and the length of the presented value is
+   attacker chosen. Comparing digests keeps the comparison constant time without
+   leaking how long the real token is. */
+function constantTimeEquals(left: string, right: string): boolean {
+	return timingSafeEqual(
+		createHash('sha256').update(left, 'utf8').digest(),
+		createHash('sha256').update(right, 'utf8').digest(),
+	);
+}
+
+export function generateSetupToken(): string {
+	return randomBytes(SETUP_TOKEN_BYTES).toString('base64url');
+}
+
+/** What FD_SETUP_TOKEN_SHA256 holds: the lowercase hex SHA-256 of the token
+ *  `flowdular deploy start` printed, so the token itself never reaches the host. */
+export function setupTokenDigest(token: string): string {
+	return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+export function createSetupAccess(
+	expected: string | { readonly sha256: string },
+	now: () => number = Date.now,
+): SetupAccess {
+	if (typeof expected !== 'string' && !/^[0-9a-f]{64}$/.test(expected.sha256)) {
+		throw new Error(
+			'FD_SETUP_TOKEN_SHA256 must be the 64 character lowercase hex SHA-256 of the setup token.',
+		);
+	}
+	const expectedDigest = Buffer.from(
+		typeof expected === 'string' ? setupTokenDigest(expected) : expected.sha256,
+		'hex',
+	);
+	let failures = 0;
+	let lockedUntil = 0;
+	/* One operator installs one deployment. Holding a single session makes the
+	   state O(1) and means a second successful token presentation supersedes the
+	   first rather than accumulating sessions. */
+	let session: SetupSession | null = null;
+
+	const expire = (): void => {
+		if (session && session.expiresAt <= now()) session = null;
+	};
+
+	return {
+		open(presented) {
+			const at = now();
+			if (at < lockedUntil) {
+				return {
+					verdict: 'locked',
+					session: null,
+					retryAfterMs: lockedUntil - at,
+				};
+			}
+			if (
+				presented === null ||
+				presented.length === 0 ||
+				!timingSafeEqual(
+					createHash('sha256').update(presented, 'utf8').digest(),
+					expectedDigest,
+				)
+			) {
+				failures += 1;
+				if (failures >= MAX_TOKEN_FAILURES) {
+					failures = 0;
+					lockedUntil = at + LOCKOUT_MS;
+					return { verdict: 'locked', session: null, retryAfterMs: LOCKOUT_MS };
+				}
+				return { verdict: 'denied', session: null, retryAfterMs: 0 };
+			}
+			failures = 0;
+			session = {
+				id: randomBytes(32).toString('base64url'),
+				csrfToken: randomBytes(32).toString('base64url'),
+				expiresAt: at + SESSION_TTL_MS,
+				pending: null,
+			};
+			return { verdict: 'granted', session, retryAfterMs: 0 };
+		},
+		resume(sessionId) {
+			expire();
+			if (!session || sessionId === null || sessionId.length === 0) return null;
+			if (!constantTimeEquals(sessionId, session.id)) return null;
+			session.expiresAt = now() + SESSION_TTL_MS;
+			return session;
+		},
+		verifyCsrf(current, presented) {
+			return (
+				presented !== null &&
+				presented.length > 0 &&
+				constantTimeEquals(presented, current.csrfToken)
+			);
+		},
+		close() {
+			session = null;
+		},
+	};
+}
+
+export function setupSessionCookie(sessionId: string, secure: boolean): string {
+	return [
+		`${SETUP_SESSION_COOKIE}=${sessionId}`,
+		'Path=/',
+		'HttpOnly',
+		'SameSite=Strict',
+		`Max-Age=${Math.floor(SESSION_TTL_MS / 1000)}`,
+		...(secure ? ['Secure'] : []),
+	].join('; ');
+}
+
+export function readSetupSessionCookie(header: string | null): string | null {
+	if (!header) return null;
+	for (const part of header.split(';')) {
+		const separator = part.indexOf('=');
+		if (separator < 0) continue;
+		if (part.slice(0, separator).trim() !== SETUP_SESSION_COOKIE) continue;
+		return part.slice(separator + 1).trim() || null;
+	}
+	return null;
+}