@flowdular/sdk 0.1.0

package/modules/auth/spec/module.yaml

@@ -0,0 +1,190 @@
+schemaVersion: 1
+id: auth.core
+specVersion: 0.10.0
+status: approved
+name: Authentication Core
+description: Provides tenant-aware accounts, password authentication, sessions, scopes, tenant roles, API tokens for machine clients, the module settings store, the auth audit trail, security headers, authentication screens, and server authorization middleware.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - cli
+dependencies:
+  - id: system.core
+    range: 0.5.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Passwords are stored only as salted memory-hard hashes.
+  - Raw session tokens are never persisted and never exposed to browser JavaScript.
+  - Greenfield reset is restricted to the workspace-local development database and requires explicit typed confirmation.
+  - Authentication cookies are HttpOnly, same-site, host-only, and secure outside explicitly configured local development.
+  - Every authenticated principal belongs to exactly one active tenant context.
+  - An account may belong to multiple tenants, while every session is bound to one selected membership.
+  - Switching tenant context rotates the session and loads scopes from the target membership.
+  - Authorization is evaluated server-side and missing scopes are denied.
+  - Sign-up availability is controlled by the auth.allowSignUp module setting and is enforced by both the API and client.
+  - Bundled module scopes are assigned from explicit owner and member defaults and migrated for existing tenant memberships.
+  - An API token is a tenant-scoped machine credential bound to one membership. Only its hash is stored, the raw value is returned exactly once at creation, and it is never recoverable afterwards.
+  - API token authority is the intersection of its recorded scopes with the live membership scopes at every request. Revoking a scope or disabling the membership takes effect immediately without touching the token.
+  - An API token can never pass a session-guarded mutation. Requests carrying a token instead of a browser session are denied before the handler runs.
+  - Issuing, listing, and revoking API tokens require a browser session with the token management scope. A machine credential cannot mint or revoke another credential.
+  - A revoked or expired API token authenticates nothing, and token lifetime is bounded to one year.
+  - Sign-in attempts are throttled per submitted address and per trusted client address, and repeated failures lock the address for a fixed period with a stable error that never reveals whether an account exists.
+  - Sign-up and sign-in errors never confirm that an email address is registered.
+  - Every response carries the platform security headers; the content security policy is enforced in production and report-only in development.
+  - A session ends at its absolute lifetime or after the configured idle period, whichever comes first; expired rows are swept periodically.
+  - Every tenant carries the built-in owner and member roles as rows; custom roles are tenant-scoped, grant only grantable scopes, and cannot be edited, deleted, or shadowed when built in or in use.
+  - Assigning a role replaces the membership scopes with the role's scopes and keeps the role key on the membership in sync.
+  - Module settings are declared by their owning module, stored per tenant (or once for the platform), validated against the declaration on every write, and secret values are never returned.
+  - Email confirmation cannot be enabled without a composed mail transport.
+  - Password reset and tenant invitation tokens are random, hashed at rest, short lived, single use, and never returned by HTTP APIs.
+  - Operator provisioning creates a workspace, its owner and the owner scopes exactly as sign-up does, works against the deployment database, and never reads the sign-up setting.
+  - An operator command never returns a password the operator did not supply. It emits a single-use setup or invitation link once, and a supplied password is read from the environment rather than from a command flag.
+  - Every operator provisioning command appends an audit row whose actor identifies the operator shell that ran it.
+  - TOTP secrets are encrypted with a deployment-provided AES-256 key; a successful password check creates a short-lived, single-use MFA challenge rather than a session.
+  - External email delivery is an injected deployment adapter. The local in-memory adapter is development-only and never exposes tokens over HTTP or logs.
+  - Authentication and administration events are appended to an auth audit trail that is readable per tenant and never contains credentials or raw tokens.
+  - Every request-time read and write runs on a tenant-scoped database handle, under forced row-level security bound to the transaction tenant.
+  - A lookup that arrives with a key and no workspace, such as a session cookie, a bearer token, an invitation link or an email address, resolves the owning tenant on a read-only cross-tenant handle that is granted only the routing columns, and the work that follows runs under the tenant that lookup named.
+permissions:
+  - id: auth.profile.read
+    description: Read the current account profile.
+  - id: auth.session.manage
+    description: Create, inspect, and revoke the current account session.
+  - id: auth.account.manage
+    description: Manage account security settings.
+  - id: auth.tenant.switch
+    description: Switch the active session to another granted tenant membership.
+  - id: auth.tokens.read
+    description: Read API token metadata of the active tenant.
+  - id: auth.tokens.manage
+    description: Issue and revoke API tokens for the active tenant.
+  - id: auth.roles.read
+    description: Read the tenant role catalog and the grantable scopes.
+  - id: auth.roles.manage
+    description: Create, change, and delete custom tenant roles.
+  - id: auth.audit.read
+    description: Read the authentication and administration audit trail of the active tenant.
+dataOwnership:
+  - Accounts, tenant memberships, scope grants, and hashed sessions are owned by auth.core.
+  - API token identity, hashed secret, recorded scopes, expiry, revocation state, and last use are owned by auth.core.
+  - Tenant roles, sign-in failure counters, module settings values, and the auth audit trail are owned by auth.core.
+  - Other modules may reference account and tenant identifiers but may not write authentication tables.
+acceptanceScenarios:
+  - id: AUTH-TOKEN-ISSUE
+    given: An owner with auth.tokens.manage and an active browser session.
+    when: The owner issues an API token with a label, a scope subset, and an optional expiry.
+    then: The raw token is returned once, only its hash and safe metadata are persisted, and the recorded scopes are the intersection with the membership scopes.
+  - id: AUTH-TOKEN-AUTHENTICATE
+    given: A live API token and a read endpoint that requires one of its scopes.
+    when: A client sends the token as a bearer credential without a session cookie.
+    then: The request is authorized as that membership with the token scopes, and the token's last use is recorded.
+  - id: AUTH-TOKEN-MUTATION-DENY
+    given: A live API token and an endpoint protected by the session mutation guard.
+    when: The client attempts the mutation with the token.
+    then: The server denies the request with a stable token error before the handler runs.
+  - id: AUTH-TOKEN-REVOKE
+    given: An issued API token.
+    when: An owner revokes it, or its expiry passes, or its membership loses the scope.
+    then: The next request carrying that token is unauthenticated, and no further lookup grants authority.
+  - id: AUTH-SIGNUP
+    given: A visitor provides a valid unique email, organization, display name, and password.
+    when: The visitor submits the sign-up form from the same origin.
+    then: An account, tenant membership, scoped session, and protected cookie are created atomically.
+  - id: AUTH-SIGNIN
+    given: An active account exists with a stored password hash.
+    when: Correct credentials are submitted from the same origin.
+    then: A new rotated session is returned without exposing its token to JavaScript.
+  - id: AUTH-DENY
+    given: A request has no valid session or lacks a required scope.
+    when: It reaches a protected middleware boundary.
+    then: The server returns 401 or 403 and does not invoke the protected handler.
+  - id: AUTH-SIGNOUT
+    given: An authenticated session and matching CSRF token exist.
+    when: The user signs out from the same origin.
+    then: The server revokes the session and expires the browser cookie.
+  - id: AUTH-GREENFIELD
+    given: A developer requests a fresh local authentication database while the application is stopped.
+    when: The developer supplies both apply authorization and the exact reset-local-auth confirmation token.
+    then: Only the workspace-local auth database is reset; documented admin and user accounts plus two isolated tenants are seeded.
+  - id: AUTH-TENANT-SWITCH
+    given: An authenticated account has memberships in more than one tenant.
+    when: The account selects another granted tenant with its current CSRF token.
+    then: The old session is revoked and a rotated session is bound to the selected tenant and its scopes.
+  - id: AUTH-SIGNUP-DISABLED
+    given: The auth.allowSignUp module setting is false.
+    when: A visitor opens or submits sign-up.
+    then: The client routes to sign-in and the server rejects account creation without writing authentication data.
+  - id: AUTH-AGENT-SCOPES
+    given: The bundled agents.core module is enabled.
+    when: Default owner and member scope grants are created or migrated.
+    then: Owners can manage and execute agents while members receive only the explicitly declared read and execute scopes.
+  - id: AUTH-LOCKOUT
+    given: Five failed sign-in attempts for one address within the window.
+    when: The next sign-in for that address arrives, correct or not.
+    then: The server returns the stable ACCOUNT_LOCKED error until the lock period passes, and the audit trail records the lock for a known account.
+  - id: AUTH-SECURITY-HEADERS
+    given: Any request served by the platform.
+    when: The response is produced.
+    then: It carries nosniff, frame denial, referrer, and permissions policies, HSTS when secure cookies are on, and a content security policy.
+  - id: AUTH-ROLE-CUSTOM
+    given: An owner with auth.roles.manage.
+    when: The owner creates a role with a subset of grantable scopes and assigns it to a member.
+    then: The role is listed for the tenant only, the member's scopes equal the role's scopes, and deleting the role is refused while a member holds it.
+  - id: AUTH-ROLE-BUILTIN
+    given: The built-in owner or member role.
+    when: Anyone tries to rename, rescope, delete, or recreate it.
+    then: The server refuses with a stable error and the role is unchanged.
+  - id: AUTH-SETTINGS-STORE
+    given: A module setting is written through the shared settings runtime by an identified actor.
+    when: The value passes the declared validation and the write commits.
+    then: The value is persisted in auth.db per tenant (or once for the platform), the next read returns it, and a settings.updated audit event records the actor, the setting, and whether the value was cleared.
+  - id: AUTH-WORKSPACE-SETTINGS
+    given: An owner with system.settings.manage on Administration > Settings.
+    when: The owner renames the workspace or picks a default locale.
+    then: The tenant name is updated and reflected in the session, the defaultLocale tenant setting is stored through the platform settings API, and the session payload serves it as tenantSettings.defaultLocale.
+  - id: AUTH-AUDIT-READ
+    given: A principal with auth.audit.read.
+    when: The principal pages through the audit trail with action and actor filters.
+    then: Only the active tenant's events are returned, newest first, with a cursor for the next page.
+  - id: AUTH-AUDIT-SOURCES
+    given: A principal who opens the unified audit screen holding a subset of auth.audit.read, agents.runs.read, and sandbox.sessions.read.
+    when: The screen offers audit sources.
+    then: Only the sources whose scope the principal holds are selectable, and the agent and sandbox sources show a chain-integrity indicator driven by their verify endpoint.
+  - id: AUTH-SESSIONS-OWN
+    given: An account with several live sessions.
+    when: The account lists its sessions and revokes one that is not current.
+    then: The revoked session no longer resolves and the current one is unchanged.
+  - id: AUTH-PASSWORD-RECOVERY
+    given: A visitor has access to the email address of an active account.
+    when: The visitor requests a reset and submits the delivered, unexpired, single-use token with a policy-compliant password.
+    then: The password changes, earlier sessions are revoked, the token cannot be reused, and the request response never reveals whether the address exists.
+  - id: AUTH-INVITATION-ACCEPT
+    given: A workspace administrator delivered a tenant invitation through the configured mail adapter.
+    when: The invited person submits the unexpired, single-use token with account details.
+    then: The account gains only the invited workspace role, the token cannot be reused, and no token appears in logs or audit metadata.
+  - id: AUTH-MFA-ENROLL
+    given: An authenticated account and a configured MFA encryption key.
+    when: The account enrolls a TOTP authenticator and confirms a valid rotating code.
+    then: The secret stays encrypted at rest, recovery codes are returned only during enrollment, and future sign-in requires a TOTP or unused recovery code.
+  - id: AUTH-MFA-OIDC
+    given: An account with confirmed TOTP signs in through an enabled, configured OIDC provider.
+    when: The provider returns a verified email for that account.
+    then: Flowdular redirects to the MFA challenge using a short-lived HttpOnly proof cookie and creates no session before the second factor succeeds.
+  - id: AUTH-SECURITY-SURFACES
+    given: A browser opens account recovery, invitation acceptance, or personal security from a supported route.
+    when: The corresponding operation is unavailable, loading, denied, invalid, successful, or pending confirmation.
+    then: The screen renders a translated explicit state and never exposes a stored credential or reusable token.
+  - id: AUTH-OPERATOR-WORKSPACE
+    given: A deployment with public sign-up disabled and no workspace yet.
+    when: An operator runs the workspace creation command with a workspace name, an owner address and a display name, and authorizes it with apply.
+    then: The workspace, the owner account, the owner membership and the owner scopes are created exactly as a sign-up creates them, an audit row names the operator, and the owner's first credential is returned once as a single-use setup link unless the operator supplied a password through the environment.
+  - id: AUTH-OPERATOR-MEMBER
+    given: An existing workspace in a deployment with public sign-up disabled.
+    when: An operator adds an email address to that workspace with a role.
+    then: A known account joins immediately with that role's scopes, an unknown address receives a single-use invitation link that is shown once, and either outcome is appended to the workspace audit trail with the operator as the actor.

package/modules/auth/src/acl/scopes.ts

@@ -0,0 +1,86 @@
+export const AUTH_SCOPES = {
+	profileRead: 'auth.profile.read',
+	sessionManage: 'auth.session.manage',
+	accountManage: 'auth.account.manage',
+	tenantSwitch: 'auth.tenant.switch',
+	tokensRead: 'auth.tokens.read',
+	tokensManage: 'auth.tokens.manage',
+	rolesRead: 'auth.roles.read',
+	rolesManage: 'auth.roles.manage',
+	auditRead: 'auth.audit.read',
+} as const;
+
+export const PLATFORM_SCOPES = {
+	workspaceAccess: 'system.workspace.access',
+	modulesRead: 'system.modules.read',
+	specsRead: 'system.specs.read',
+	runsRead: 'system.runs.read',
+	settingsRead: 'system.settings.read',
+	settingsManage: 'system.settings.manage',
+} as const;
+
+export const BUNDLED_MODULE_SCOPES = {
+	usersRead: 'users.members.read',
+	usersManage: 'users.members.manage',
+	partiesRead: 'parties.records.read',
+	partiesManage: 'parties.records.manage',
+	catalogRead: 'catalog.items.read',
+	catalogManage: 'catalog.items.manage',
+	agentDefinitionsRead: 'agents.definitions.read',
+	agentDefinitionsManage: 'agents.definitions.manage',
+	agentRunsRead: 'agents.runs.read',
+	agentRunsExecute: 'agents.runs.execute',
+	agentProvidersRead: 'agents.providers.read',
+	agentProvidersManage: 'agents.providers.manage',
+	agentProvidersTest: 'agents.providers.test',
+	agentSkillsRead: 'agents.skills.read',
+	agentSkillsManage: 'agents.skills.manage',
+	sandboxAccessUse: 'sandbox.access.use',
+	sandboxAccessManage: 'sandbox.access.manage',
+	sandboxSessionsRead: 'sandbox.sessions.read',
+	sandboxPreviewData: 'sandbox.preview.data',
+	sandboxModulesEject: 'sandbox.modules.eject',
+} as const;
+
+export const OWNER_SCOPES = Object.freeze([
+	...Object.values(AUTH_SCOPES),
+	...Object.values(PLATFORM_SCOPES),
+	...Object.values(BUNDLED_MODULE_SCOPES),
+]);
+
+export const MEMBER_SCOPES = Object.freeze([
+	AUTH_SCOPES.profileRead,
+	AUTH_SCOPES.sessionManage,
+	AUTH_SCOPES.tenantSwitch,
+	AUTH_SCOPES.rolesRead,
+	PLATFORM_SCOPES.workspaceAccess,
+	BUNDLED_MODULE_SCOPES.usersRead,
+	BUNDLED_MODULE_SCOPES.partiesRead,
+	BUNDLED_MODULE_SCOPES.catalogRead,
+	BUNDLED_MODULE_SCOPES.agentDefinitionsRead,
+	BUNDLED_MODULE_SCOPES.agentRunsRead,
+	BUNDLED_MODULE_SCOPES.agentRunsExecute,
+	BUNDLED_MODULE_SCOPES.agentSkillsRead,
+]);
+
+/* Built-in roles; every tenant gets a row per entry in auth_roles. */
+export const BUILTIN_ROLES = Object.freeze([
+	{
+		key: 'owner',
+		name: 'Owner',
+		description:
+			'Full workspace administration, module management, and operational access.',
+		scopes: OWNER_SCOPES,
+	},
+	{
+		key: 'member',
+		name: 'Member',
+		description:
+			'Standard workspace access with read-only access to bundled records.',
+		scopes: MEMBER_SCOPES,
+	},
+] as const);
+
+export type AuthScope =
+	| (typeof OWNER_SCOPES)[number]
+	| (typeof MEMBER_SCOPES)[number];

package/modules/auth/src/api/attempt-limiter.ts

@@ -0,0 +1,42 @@
+/* Fixed-window counter per key, bounded by evicting the least recently touched
+   key once the table is full. A flood of new keys can therefore only shorten
+   other attackers' windows, never lock legitimate first-time callers out. */
+export class AttemptLimiter {
+	readonly #attempts = new Map<string, { count: number; resetAt: number }>();
+	readonly #limit: number;
+	readonly #windowMs: number;
+	readonly #maxEntries: number;
+
+	constructor(limit = 5, windowMs = 5 * 60 * 1000, maxEntries = 10_000) {
+		this.#limit = limit;
+		this.#windowMs = windowMs;
+		this.#maxEntries = maxEntries;
+	}
+
+	consume(key: string, now = Date.now()): boolean {
+		const current = this.#attempts.get(key);
+		if (current && current.resetAt > now) {
+			if (current.count >= this.#limit) return false;
+			current.count += 1;
+			this.#attempts.delete(key);
+			this.#attempts.set(key, current);
+			return true;
+		}
+		if (current) {
+			this.#attempts.delete(key);
+		} else if (this.#attempts.size >= this.#maxEntries) {
+			const oldest = this.#attempts.keys().next().value;
+			if (oldest !== undefined) this.#attempts.delete(oldest);
+		}
+		this.#attempts.set(key, { count: 1, resetAt: now + this.#windowMs });
+		return true;
+	}
+
+	clear(key: string): void {
+		this.#attempts.delete(key);
+	}
+
+	get size(): number {
+		return this.#attempts.size;
+	}
+}

package/modules/auth/src/api/client-address.ts

@@ -0,0 +1,14 @@
+const ADDRESS_PATTERN = /^[0-9a-fA-F.:]{3,45}$/;
+
+/* Octane hands routes a Web Request without the socket address, so the client
+   address is only known behind a reverse proxy that is explicitly trusted to
+   set x-forwarded-for. Callers skip address-based limits on null. */
+export function clientAddress(
+	request: Request,
+	trustProxy: boolean,
+): string | null {
+	if (!trustProxy) return null;
+	const forwarded = request.headers.get('x-forwarded-for');
+	const first = forwarded?.split(',')[0]?.trim() ?? '';
+	return ADDRESS_PATTERN.test(first) ? first.toLowerCase() : null;
+}

package/modules/auth/src/api/cookies.ts

@@ -0,0 +1,52 @@
+export interface AuthCookieConfig {
+	readonly name: string;
+	readonly secure: boolean;
+	readonly maxAgeSeconds: number;
+}
+
+export function readCookie(
+	request: globalThis.Request,
+	name: string,
+): string | null {
+	const header = request.headers.get('cookie');
+	if (!header) return null;
+	for (const item of header.split(';')) {
+		const separator = item.indexOf('=');
+		if (separator < 1) continue;
+		const key = item.slice(0, separator).trim();
+		if (key !== name) continue;
+		try {
+			return decodeURIComponent(item.slice(separator + 1).trim());
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+
+export function sessionCookie(token: string, config: AuthCookieConfig): string {
+	return [
+		`${config.name}=${encodeURIComponent(token)}`,
+		'Path=/',
+		'HttpOnly',
+		'SameSite=Strict',
+		`Max-Age=${config.maxAgeSeconds}`,
+		config.secure ? 'Secure' : '',
+	]
+		.filter(Boolean)
+		.join('; ');
+}
+
+export function expiredSessionCookie(config: AuthCookieConfig): string {
+	return [
+		`${config.name}=`,
+		'Path=/',
+		'HttpOnly',
+		'SameSite=Strict',
+		'Max-Age=0',
+		'Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+		config.secure ? 'Secure' : '',
+	]
+		.filter(Boolean)
+		.join('; ');
+}

package/modules/auth/src/api/origin.ts

@@ -0,0 +1,40 @@
+import type { Context } from '@octanejs/app-core';
+import { AuthServiceError } from '../services/auth-service-error.ts';
+
+export function assertSameOrigin(context: Context): void {
+	const site = context.request.headers.get('sec-fetch-site');
+	if (site === 'cross-site' || site === 'same-site') {
+		throw new AuthServiceError(
+			'CROSS_ORIGIN_REQUEST',
+			'Cross-origin request rejected.',
+			403,
+		);
+	}
+
+	const origin = context.request.headers.get('origin');
+	if (origin) {
+		if (origin !== context.url.origin) {
+			throw new AuthServiceError(
+				'CROSS_ORIGIN_REQUEST',
+				'Request origin does not match.',
+				403,
+			);
+		}
+		return;
+	}
+
+	const referer = context.request.headers.get('referer');
+	if (referer) {
+		try {
+			if (new URL(referer).origin === context.url.origin) return;
+		} catch {
+			// The generic failure below does not disclose header parsing details.
+		}
+	}
+
+	throw new AuthServiceError(
+		'ORIGIN_REQUIRED',
+		'A same-origin request is required.',
+		403,
+	);
+}

package/modules/auth/src/cli/commands.json

@@ -0,0 +1,74 @@
+{
+	"protocolVersion": 1,
+	"moduleId": "auth.core",
+	"commands": [
+		{
+			"path": ["auth", "scopes"],
+			"capability": {
+				"id": "auth.scopes.list",
+				"version": 1,
+				"summary": "List authentication and platform scopes granted to new tenant owners.",
+				"risk": "read",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": false
+			}
+		},
+		{
+			"path": ["auth", "sync-scopes"],
+			"capability": {
+				"id": "auth.scopes.sync",
+				"version": 1,
+				"summary": "Grant the scopes an enabled module declares to every workspace owner.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		},
+		{
+			"path": ["auth", "workspaces"],
+			"capability": {
+				"id": "auth.workspace.list",
+				"version": 1,
+				"summary": "List the workspaces of this deployment and their owners.",
+				"risk": "read",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": false
+			}
+		},
+		{
+			"path": ["auth", "workspace-create"],
+			"capability": {
+				"id": "auth.workspace.create",
+				"version": 1,
+				"summary": "Create a workspace with its owner account without opening public sign-up.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		},
+		{
+			"path": ["auth", "member-add"],
+			"capability": {
+				"id": "auth.member.add",
+				"version": 1,
+				"summary": "Add an account to a workspace with a role, or invite an unknown address.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		},
+		{
+			"path": ["auth", "greenfield"],
+			"capability": {
+				"id": "auth.greenfield.reset",
+				"version": 1,
+				"summary": "Reset local auth and seed demo tenants, an admin, and a reduced-scope user.",
+				"risk": "destructive",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true,
+				"localOnly": true,
+				"confirmation": "reset-local-auth"
+			}
+		}
+	]
+}

package/modules/auth/src/cli/database.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import {
+	createDatabaseProvider,
+	databaseProviderConfigFromEnvironment,
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	type DatabaseProvider,
+	type DatabaseProviderConfig,
+} from '@flowdular/sdk/database';
+import { createPgliteCluster } from '@flowdular/sdk/database-pglite';
+import { Pool } from 'pg';
+
+export const MIGRATION_REQUIREMENTS = {
+	dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+	capabilities: [
+		DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+		DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+		DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+	],
+} as const;
+
+export interface CliDatabase {
+	readonly config: DatabaseProviderConfig;
+	/** Where the data lives, for the evidence an operator command reports. */
+	readonly location: string;
+	create(): DatabaseProvider;
+}
+
+/* The CLI protocol carries no provider, so an operator command opens the same
+   database the platform would open from this workspace and this environment.
+   The drivers are supplied here for the same reason the deployable supplies
+   them: @flowdular/sdk/database owns none. */
+export function localDatabaseProvider(workspaceRoot: string): CliDatabase {
+	const config = databaseProviderConfigFromEnvironment(
+		process.env,
+		workspaceRoot,
+	);
+	return {
+		config,
+		location:
+			config.adapter === 'pglite'
+				? (config.pglite?.dataDirectory ??
+					resolve(workspaceRoot, '.flowdular', 'data', 'pglite'))
+				: 'the configured PostgreSQL database',
+		create: () =>
+			createDatabaseProvider(config, {
+				postgresPool: (options) => new Pool(options),
+				pgliteCluster: (options) => createPgliteCluster(options),
+			}),
+	};
+}