create-flowdular 0.4.3 → 0.6.0

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

@@ -0,0 +1,111 @@
+/* First-run failures reach the operator screen, the terminal scrollback, and
+   whatever support channel the operator pastes them into. Nothing derived from
+   a driver message is ever returned: the classification below writes the whole
+   sentence, and the secret pass is a second barrier for values that reached a
+   string some other way. */
+
+export type SetupFailureCode =
+	| 'AUTHENTICATION_REJECTED'
+	| 'DATABASE_MISSING'
+	| 'HOST_UNREACHABLE'
+	| 'PERMISSION_DENIED'
+	| 'PROBE_FAILED'
+	| 'ROLE_TOO_PRIVILEGED'
+	| 'TIMED_OUT'
+	| 'TLS_REJECTED';
+
+export interface SetupFailure {
+	readonly code: SetupFailureCode;
+	readonly message: string;
+}
+
+const MESSAGES: Readonly<Record<SetupFailureCode, string>> = Object.freeze({
+	AUTHENTICATION_REJECTED:
+		'The server rejected the credentials for one of the roles. Check the user names and passwords you entered.',
+	DATABASE_MISSING:
+		'The server answered but does not have a database with that name. Create it, then try again.',
+	HOST_UNREACHABLE:
+		'Nothing answered at that host and port. Check the address, the port, and whether the server accepts connections from this machine.',
+	PERMISSION_DENIED:
+		'The server accepted the connection and then refused the operation. Grant the role the rights the deployment needs.',
+	PROBE_FAILED:
+		'The connection attempt failed. Check the values you entered and the server log for the matching entry.',
+	ROLE_TOO_PRIVILEGED:
+		'The runtime role holds SUPERUSER or BYPASSRLS. Tenant isolation depends on that role being unable to bypass row-level security, so this connection is refused.',
+	TIMED_OUT:
+		'The server did not answer within the connection timeout. Check the network path and whether the server is accepting connections.',
+	TLS_REJECTED:
+		'The TLS certificate was not accepted. Supply the certificate authority, or pick a TLS mode that matches how the server is configured.',
+});
+
+/* Mirrors redactSecrets in packages/ai-provider/src/errors.ts: every value the
+   operator typed as a secret is replaced wherever it appears. Short values are
+   skipped because a two-character password would redact ordinary prose. */
+export function redactSetupSecrets(
+	value: string,
+	secrets: Iterable<string>,
+): string {
+	let redacted = value;
+	for (const secret of secrets) {
+		if (secret.length < 4) continue;
+		redacted = redacted.split(secret).join('[redacted]');
+	}
+	return redacted;
+}
+
+function errorCode(error: unknown): string {
+	return typeof error === 'object' && error !== null && 'code' in error
+		? String((error as { code: unknown }).code)
+		: '';
+}
+
+const SQLSTATE: Readonly<Record<string, SetupFailureCode>> = Object.freeze({
+	'28000': 'AUTHENTICATION_REJECTED',
+	'28P01': 'AUTHENTICATION_REJECTED',
+	'3D000': 'DATABASE_MISSING',
+	'42501': 'PERMISSION_DENIED',
+	'53300': 'HOST_UNREACHABLE',
+	'57P03': 'HOST_UNREACHABLE',
+});
+
+const ERRNO: Readonly<Record<string, SetupFailureCode>> = Object.freeze({
+	EAI_AGAIN: 'HOST_UNREACHABLE',
+	ECONNREFUSED: 'HOST_UNREACHABLE',
+	ECONNRESET: 'HOST_UNREACHABLE',
+	EHOSTUNREACH: 'HOST_UNREACHABLE',
+	ENETUNREACH: 'HOST_UNREACHABLE',
+	ENOTFOUND: 'HOST_UNREACHABLE',
+	ETIMEDOUT: 'TIMED_OUT',
+	CERT_HAS_EXPIRED: 'TLS_REJECTED',
+	DEPTH_ZERO_SELF_SIGNED_CERT: 'TLS_REJECTED',
+	ERR_TLS_CERT_ALTNAME_INVALID: 'TLS_REJECTED',
+	SELF_SIGNED_CERT_IN_CHAIN: 'TLS_REJECTED',
+	UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'TLS_REJECTED',
+});
+
+export class SetupProbeError extends Error {
+	constructor(readonly failureCode: SetupFailureCode) {
+		super(MESSAGES[failureCode]);
+		this.name = 'SetupProbeError';
+	}
+}
+
+/**
+ * Turns any failure into one of a fixed set of operator-actionable sentences.
+ * The driver message is read to classify and then discarded, so a DSN, a host,
+ * or a password inside it cannot reach the caller.
+ */
+export function classifySetupFailure(
+	error: unknown,
+	secrets: Iterable<string> = [],
+): SetupFailure {
+	const code =
+		error instanceof SetupProbeError
+			? error.failureCode
+			: (SQLSTATE[errorCode(error)] ??
+				ERRNO[errorCode(error)] ??
+				(error instanceof Error && error.name === 'AbortError'
+					? 'TIMED_OUT'
+					: 'PROBE_FAILED'));
+	return { code, message: redactSetupSecrets(MESSAGES[code], secrets) };
+}

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

@@ -0,0 +1,145 @@
+import type { DatabaseProvider } from '@flowdular/sdk/database';
+import {
+	authRuntimeOptionsFromEnvironment,
+	createAuthRuntime,
+} from '@flowdular/sdk/modules/auth/server';
+/* First-run provisioning uses the same audited auth service as the operator
+   CLI. The operator chooses the first owner; no demo credentials are shipped. */
+
+export const FIRST_RUN_OPERATOR = 'setup:first-run';
+
+export interface SeededAccount {
+	readonly email: string;
+	readonly displayName: string;
+	readonly role: string;
+	readonly scopes: readonly string[];
+}
+
+export interface FirstRunOwner {
+	readonly workspaceName: string;
+	readonly workspaceSlug: string;
+	readonly ownerEmail: string;
+	readonly ownerName: string;
+	readonly ownerPassword: string;
+}
+
+export interface FirstRunSeed {
+	readonly workspace: { readonly name: string; readonly slug: string };
+	readonly accounts: readonly SeededAccount[];
+}
+
+export class SetupSeedError extends Error {
+	constructor(
+		readonly code: 'DATABASE_NOT_EMPTY' | 'SETUP_IN_PROGRESS',
+		message: string,
+	) {
+		super(message);
+		this.name = 'SetupSeedError';
+	}
+}
+
+/**
+ * Migrates auth.core, then creates the chosen workspace and its owner. The
+ * database must still have no workspace, so a stale session cannot re-provision
+ * an existing installation.
+ */
+export async function seedFirstRun(
+	databases: DatabaseProvider,
+	environment: NodeJS.ProcessEnv,
+	workspaceRoot: string,
+	owner: FirstRunOwner,
+): Promise<FirstRunSeed> {
+	const runtime = createAuthRuntime({
+		...authRuntimeOptionsFromEnvironment(environment, workspaceRoot),
+		databases,
+	});
+	try {
+		const service = await runtime.service();
+		const existing = await service.listTenants();
+		if (existing.length > 0) {
+			throw new SetupSeedError(
+				'DATABASE_NOT_EMPTY',
+				`This database already holds ${existing.length} workspace${
+					existing.length === 1 ? '' : 's'
+				}. Setup does not reset an existing installation. Point this deployment at that database and sign in, or choose an empty one.`,
+			);
+		}
+		const provisioned = await service.provisionWorkspace({
+			name: owner.workspaceName,
+			slug: owner.workspaceSlug,
+			ownerEmail: owner.ownerEmail,
+			ownerDisplayName: owner.ownerName,
+			password: owner.ownerPassword,
+			operator: FIRST_RUN_OPERATOR,
+		});
+		return {
+			workspace: {
+				name: provisioned.workspace.name,
+				slug: provisioned.workspace.slug,
+			},
+			accounts: [
+				{
+					email: provisioned.owner.email,
+					displayName: provisioned.owner.displayName,
+					role: provisioned.owner.role,
+					scopes: provisioned.owner.scopes,
+				},
+			],
+		};
+	} finally {
+		await runtime.dispose();
+	}
+}
+
+/**
+ * Runs a first-run seed under a PostgreSQL advisory lock, so two processes on
+ * one database cannot both pass the empty check above and each create a first
+ * workspace. A second claimant is refused, not queued. The lock is held by its
+ * own transaction, and the seed runs outside that transaction's async context
+ * because an adapter refuses nested use from inside one.
+ */
+export async function claimFirstRun<T>(
+	databases: DatabaseProvider,
+	seed: () => Promise<T>,
+): Promise<T> {
+	const lease = await databases.acquire({
+		namespace: 'platform.setup',
+		purpose: 'migration',
+	});
+	try {
+		let release!: () => void;
+		const released = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		let report!: (claimed: boolean) => void;
+		const reported = new Promise<boolean>((resolve) => {
+			report = resolve;
+		});
+		const held = lease.database.transaction(async (transaction) => {
+			const result = await transaction.query<{ claimed: boolean }>({
+				text: 'SELECT pg_try_advisory_xact_lock(hashtext($1), hashtext($2)) AS claimed',
+				parameters: ['flowdular-first-run', 'platform.setup'],
+			});
+			report(result.rows[0]?.claimed === true);
+			await released;
+		});
+		if (!(await Promise.race([reported, held.then(() => false)]))) {
+			release();
+			await held;
+			throw new SetupSeedError(
+				'SETUP_IN_PROGRESS',
+				'Another setup is creating the first workspace right now. Wait a moment, then reload this page.',
+			);
+		}
+		try {
+			return await seed();
+		} finally {
+			release();
+			/* The lock transaction writes nothing, so once the seed has settled a
+			   failure to end it cannot change the outcome. */
+			await held.catch(() => undefined);
+		}
+	} finally {
+		await lease.release();
+	}
+}

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

@@ -0,0 +1,79 @@
+import { flowdularStateDirectory } from '@flowdular/sdk/kernel/runtime-config';
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { generateSetupToken } from './access.ts';
+
+export const SETUP_TOKEN_FILE = 'setup-token';
+
+export interface IssuedSetupToken {
+	readonly token: string;
+	/** Where the token was written, or null when the filesystem refused it. */
+	readonly file: string | null;
+	readonly banner: string;
+}
+
+export interface IssueSetupTokenOptions {
+	readonly workspaceRoot: string;
+	readonly origin: string;
+	readonly token?: string;
+}
+
+function banner(token: string, origin: string, file: string | null): string {
+	const lines = [
+		'',
+		'  Flowdular is not configured yet and started its first-run setup.',
+		'',
+		`  Open   ${origin}/setup`,
+		`  Token  ${token}`,
+		'',
+		file
+			? `  The same token is in ${file} (readable only by this user).`
+			: '  This filesystem is read only, so the token exists only in this output.',
+		'  It is required for every setup request and is not shown again after',
+		'  setup completes. Restarting the process issues a new one.',
+		'',
+	];
+	return lines.join('\n');
+}
+
+/**
+ * Mints the token that binds every first-run request, prints it, and stores it
+ * with owner-only permissions. A filesystem that refuses the write is not an
+ * error: the token is still on stdout, which is where a container operator
+ * reads it anyway.
+ */
+export function issueSetupToken(
+	options: IssueSetupTokenOptions,
+): IssuedSetupToken {
+	const token = options.token ?? generateSetupToken();
+	const directory = flowdularStateDirectory(options.workspaceRoot);
+	const path = resolve(directory, SETUP_TOKEN_FILE);
+	let file: string | null = null;
+	try {
+		mkdirSync(directory, { recursive: true, mode: 0o700 });
+		writeFileSync(path, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+		/* An existing file keeps its old mode through an overwrite, so the mode
+		   is asserted rather than only requested. */
+		chmodSync(path, 0o600);
+		file = path;
+	} catch {
+		/* Read-only root filesystems are a deliberate deployment choice; the
+		   reason is not reported because it cannot change the outcome. */
+		file = null;
+	}
+	return { token, file, banner: banner(token, options.origin, file) };
+}
+
+/**
+ * Removes the token a previous first run left behind. A configured deployment
+ * has no setup routes, so the file is a stale secret with nothing to unlock.
+ */
+export function clearSetupToken(workspaceRoot: string): void {
+	try {
+		rmSync(resolve(flowdularStateDirectory(workspaceRoot), SETUP_TOKEN_FILE), {
+			force: true,
+		});
+	} catch {
+		/* A read-only state directory cannot hold a stale token either. */
+	}
+}

package/template/default/platform/src/server/worker-tick.ts

@@ -0,0 +1,193 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import {
+	defineEndpoint,
+	HttpProblem,
+	jsonResponse,
+	problemResponse,
+	serverLogger,
+	type ModuleServerComposition,
+} from '@flowdular/sdk/server';
+
+export const WORKER_TICK_PATH = '/api/internal/worker/tick';
+const DEFAULT_WINDOW_MS = 50_000;
+const MIN_WINDOW_MS = 1_000;
+const MAX_WINDOW_MS = 240_000;
+const MIN_SECRET_LENGTH = 32;
+/* A request that just queued work asks for a short window: long enough for the
+   first passes to claim it, short enough that a burst of requests is not held
+   behind one long drain. */
+const KICK_WINDOW_MS = 15_000;
+
+export interface WorkerTickConfig {
+	readonly secret: string;
+	readonly windowMs: number;
+}
+
+export function workerTickConfigFromEnvironment(
+	environment: NodeJS.ProcessEnv,
+): WorkerTickConfig {
+	const secret = environment.FD_WORKER_TICK_SECRET?.trim() ?? '';
+	if (secret.length < MIN_SECRET_LENGTH) {
+		throw new Error(
+			`FD_WORKER_TICK_SECRET must hold at least ${MIN_SECRET_LENGTH} characters in the tick role.`,
+		);
+	}
+	const configured = environment.FD_WORKER_TICK_WINDOW_MS?.trim();
+	const windowMs = configured ? Number(configured) : DEFAULT_WINDOW_MS;
+	if (
+		!Number.isSafeInteger(windowMs) ||
+		windowMs < MIN_WINDOW_MS ||
+		windowMs > MAX_WINDOW_MS
+	) {
+		throw new Error(
+			`FD_WORKER_TICK_WINDOW_MS must be an integer between ${MIN_WINDOW_MS} and ${MAX_WINDOW_MS}.`,
+		);
+	}
+	return { secret, windowMs };
+}
+
+export interface WorkerTickReport {
+	readonly status: 'drained' | 'closed';
+	readonly joined: boolean;
+	readonly windowMs: number;
+	readonly durationMs: number;
+}
+
+export interface WorkerTicker {
+	/** Runs the module workers for one window, then drains them. A tick that
+	 *  arrives while a window is open joins it instead of starting another. */
+	tick(windowMs?: number): Promise<WorkerTickReport>;
+	/** Ends an open window early and waits for its drain; later ticks run nothing. */
+	close(): Promise<void>;
+}
+
+export function createWorkerTicker(
+	compositions: readonly ModuleServerComposition[],
+	options: { readonly windowMs: number; readonly now?: () => number },
+): WorkerTicker {
+	const now = options.now ?? Date.now;
+	let current: Promise<WorkerTickReport> | undefined;
+	let closed = false;
+	let endWindow: (() => void) | undefined;
+
+	const run = async (windowMs: number): Promise<WorkerTickReport> => {
+		const startedAt = now();
+		const started: ModuleServerComposition[] = [];
+		let failure: unknown;
+		try {
+			for (const composition of compositions) {
+				if (!composition.startWorker || closed) continue;
+				/* Recorded before the await: a worker that failed halfway through
+				   its start may still hold a timer, and its stop releases it. */
+				started.push(composition);
+				await composition.startWorker();
+			}
+			if (!closed) {
+				await new Promise<void>((resolve) => {
+					const timer = setTimeout(resolve, windowMs);
+					endWindow = () => {
+						clearTimeout(timer);
+						resolve();
+					};
+				});
+			}
+		} catch (error) {
+			failure = error;
+		} finally {
+			endWindow = undefined;
+		}
+		/* Drained before the request answers: the host may freeze the instance
+		   as soon as the response leaves, and a frozen claim waits out its lease. */
+		for (const composition of started.reverse()) {
+			try {
+				await composition.stop?.();
+			} catch (error) {
+				failure ??= error;
+			}
+		}
+		if (failure !== undefined) throw failure;
+		return {
+			status: closed ? 'closed' : 'drained',
+			joined: false,
+			windowMs,
+			durationMs: now() - startedAt,
+		};
+	};
+
+	return {
+		tick(windowMs = options.windowMs) {
+			if (current) {
+				return current.then((report) => ({ ...report, joined: true }));
+			}
+			if (closed) {
+				return Promise.resolve({
+					status: 'closed',
+					joined: false,
+					windowMs,
+					durationMs: 0,
+				});
+			}
+			const pending = run(windowMs).finally(() => {
+				if (current === pending) current = undefined;
+			});
+			current = pending;
+			return pending;
+		},
+		async close() {
+			closed = true;
+			endWindow?.();
+			await current?.catch(() => undefined);
+		},
+	};
+}
+
+function digest(value: string): Buffer {
+	return createHash('sha256').update(value).digest();
+}
+
+export function createWorkerTickEndpoint(
+	ticker: WorkerTicker,
+	config: WorkerTickConfig,
+) {
+	const expected = digest(config.secret);
+	const kickWindowMs = Math.min(KICK_WINDOW_MS, config.windowMs);
+	return defineEndpoint({
+		id: 'system.worker-tick',
+		path: WORKER_TICK_PATH,
+		/* GET is what a scheduler such as Vercel Cron sends; POST is a request
+		   path asking for a pass after it queued work. */
+		methods: ['GET', 'POST'],
+		access: { kind: 'public' },
+		handler: async ({ octane }) => {
+			const header = octane.request.headers.get('authorization') ?? '';
+			const presented = /^Bearer (.+)$/i.exec(header)?.[1]?.trim() ?? '';
+			if (!timingSafeEqual(digest(presented), expected)) {
+				return problemResponse(
+					new HttpProblem(
+						'UNAUTHENTICATED',
+						'Authentication is required.',
+						401,
+					),
+				);
+			}
+			try {
+				const report = await ticker.tick(
+					octane.request.method === 'POST' ? kickWindowMs : config.windowMs,
+				);
+				return jsonResponse(report, report.status === 'closed' ? 503 : 200);
+			} catch (error) {
+				serverLogger().error('worker tick failed', {
+					module: 'platform',
+					err: error,
+				});
+				return problemResponse(
+					new HttpProblem(
+						'WORKER_TICK_FAILED',
+						'The worker tick did not complete.',
+						500,
+					),
+				);
+			}
+		},
+	});
+}

package/template/default/platform/src/server/workspace-root.ts

@@ -0,0 +1,16 @@
+import { basename, dirname } from 'node:path';
+
+export function findWorkspaceRoot(start: string): string {
+	/* Development loads platform/octane.config.ts from platform/. The production
+	   bundle loads it from platform/dist/server/, including in Docker. */
+	if (basename(start) === 'platform') return dirname(start);
+	const dist = dirname(start);
+	const platform = dirname(dist);
+	if (
+		basename(start) === 'server' &&
+		basename(dist) === 'dist' &&
+		basename(platform) === 'platform'
+	)
+		return dirname(platform);
+	throw new Error('Unexpected Flowdular platform entry layout.');
+}

package/template/default/render.yaml

@@ -0,0 +1,70 @@
+# Flowdular requires a persistent web process, external PostgreSQL and object storage.
+# See infra/README.md before connecting this Blueprint.
+services:
+  - type: web
+    runtime: docker
+    name: flowdular
+    plan: 1c-2g
+    dockerfilePath: ./infra/docker/Dockerfile
+    dockerContext: .
+    healthCheckPath: /api/health
+    autoDeployTrigger: 'off'
+    maxShutdownDelaySeconds: 120
+    envVars:
+      - key: NODE_ENV
+        value: production
+      - key: FD_DATABASE_ADAPTER
+        value: postgresql
+      - key: FD_DATABASE_TLS
+        value: verify-full
+      - key: FD_DATABASE_URL
+        sync: false
+      - key: FD_DATABASE_BACKGROUND_URL
+        sync: false
+      - key: FD_DATABASE_MIGRATOR_URL
+        sync: false
+      - key: FD_DATABASE_TLS_CA
+        sync: false
+      - key: FD_AUTH_PUBLIC_ORIGIN
+        fromService:
+          name: flowdular
+          type: web
+          envVarKey: RENDER_EXTERNAL_URL
+      - key: FD_AUTH_SECURE_COOKIE
+        value: 'true'
+      - key: FD_AUTH_ALLOW_SIGN_UP
+        value: 'false'
+      - key: FD_TRUST_PROXY
+        value: 'true'
+      - key: FD_STORAGE_ADAPTER
+        value: s3
+      - key: FD_STORAGE_S3_BUCKET
+        sync: false
+      - key: FD_STORAGE_S3_REGION
+        sync: false
+      - key: FD_STORAGE_S3_ACCESS_KEY_ID
+        sync: false
+      - key: FD_STORAGE_S3_SECRET_ACCESS_KEY
+        sync: false
+      - key: FD_AGENT_CREDENTIAL_KEY
+        generateValue: true
+      - key: FD_AGENT_RUN_GRANT_KEY
+        generateValue: true
+      - key: FD_AUTH_MFA_KEY
+        generateValue: true
+      - key: FD_APPROVAL_GRANT_KEY
+        generateValue: true
+      - key: FD_AUTOMATIONS_CREDENTIAL_KEY
+        generateValue: true
+      - key: FD_NOTIFICATIONS_SECRET_KEY
+        generateValue: true
+      - key: FD_WORKFLOWS_PAYLOAD_KEY
+        generateValue: true
+      - key: FD_WORKFLOWS_CURSOR_KEY
+        generateValue: true
+      - key: FD_STORAGE_ENCRYPTION_KEY
+        generateValue: true
+      - key: FD_CONNECTORS_SECRET_KEY
+        generateValue: true
+      - key: FD_AUDIT_ANCHOR_KEY
+        generateValue: true

package/template/default/vercel.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "https://openapi.vercel.sh/vercel.json",
+	"framework": null,
+	"buildCommand": "node infra/vercel/build.mjs"
+}