@flowdular/sdk 0.1.0

package/modules/sandbox/src/domain/types.ts

@@ -0,0 +1,125 @@
+export type SandboxGrantCapability =
+	| 'sandbox.access.use'
+	| 'sandbox.sessions.read'
+	| 'sandbox.preview.data'
+	| 'sandbox.modules.eject';
+
+export interface SandboxAccessGrant {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly capabilities: readonly SandboxGrantCapability[];
+	readonly note: string | null;
+	readonly grantedBy: string;
+	readonly grantedAt: number;
+	readonly expiresAt: number | null;
+	readonly revokedAt: number | null;
+	readonly revokedBy: string | null;
+}
+
+export interface SandboxAccessCandidate {
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly role: string;
+	readonly status: 'active' | 'disabled';
+	readonly availableCapabilities: readonly SandboxGrantCapability[];
+}
+
+export type SandboxAuthorityDenial =
+	| 'grant-missing'
+	| 'grant-revoked'
+	| 'grant-expired'
+	| 'scope-missing';
+
+export interface SandboxAuthorityGranted {
+	readonly granted: true;
+	readonly grantId: string;
+	readonly tenantId: string;
+	readonly accountId: string;
+	readonly capabilities: readonly SandboxGrantCapability[];
+	readonly expiresAt: number | null;
+}
+
+export interface SandboxAuthorityDenied {
+	readonly granted: false;
+	readonly reason: SandboxAuthorityDenial;
+}
+
+export type SandboxAuthority = SandboxAuthorityGranted | SandboxAuthorityDenied;
+
+export type SandboxSessionState =
+	| 'draft'
+	| 'classified'
+	| 'planned'
+	| 'editing'
+	| 'validating'
+	| 'previewing'
+	| 'awaiting-approval'
+	| 'accepted'
+	| 'failed'
+	| 'blocked'
+	| 'archived'
+	| 'deleted';
+
+export const SANDBOX_SESSION_STATES: readonly SandboxSessionState[] = [
+	'draft',
+	'classified',
+	'planned',
+	'editing',
+	'validating',
+	'previewing',
+	'awaiting-approval',
+	'accepted',
+	'failed',
+	'blocked',
+	'archived',
+	'deleted',
+];
+
+export type SandboxRuntimeMode = 'loopback' | 'self-hosted';
+
+export interface SandboxSessionRecord {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly accountId: string;
+	readonly moduleId: string;
+	readonly title: string;
+	readonly blueprint: string;
+	readonly driver: string;
+	readonly mode: SandboxRuntimeMode;
+	readonly state: SandboxSessionState;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+	readonly ejectedAt: number | null;
+	readonly archivedAt: number | null;
+}
+
+export interface SandboxAuditEvent {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly sequence: number;
+	readonly actorId: string;
+	readonly action: string;
+	readonly subjectType: 'grant' | 'session' | 'module';
+	readonly subjectId: string;
+	readonly metadata: Readonly<Record<string, string | number | boolean>>;
+	readonly occurredAt: number;
+	readonly previousHash: string | null;
+	readonly eventHash: string;
+}
+
+export interface SandboxAuditPage {
+	readonly events: readonly SandboxAuditEvent[];
+	/** `${occurredAt}:${sequence}` of the last event, or null when exhausted. */
+	readonly nextCursor: string | null;
+}
+
+/* Whether the tenant hash chain reproduces, and the id of the first row that
+   does not. The same walk backs the audit-verify CLI and the HTTP endpoint. */
+export interface SandboxAuditChainVerification {
+	readonly verified: boolean;
+	readonly brokenAt: string | null;
+}

package/modules/sandbox/src/index.ts

@@ -0,0 +1,33 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { SANDBOX_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'sandbox.navigation',
+			label: 'Sandbox',
+			href: '/sandbox',
+			order: 70,
+			permission: SANDBOX_PERMISSIONS.manage,
+		},
+	],
+	permissions: Object.values(SANDBOX_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export {
+	SANDBOX_GRANT_CAPABILITIES,
+	SANDBOX_PERMISSIONS,
+} from './acl/permissions.ts';
+export type {
+	SandboxAccessCandidate,
+	SandboxAccessGrant,
+	SandboxAuditEvent,
+	SandboxAuthority,
+	SandboxAuthorityDenial,
+	SandboxGrantCapability,
+	SandboxRuntimeMode,
+	SandboxSessionRecord,
+	SandboxSessionState,
+} from './domain/types.ts';

package/modules/sandbox/src/platform.ts

@@ -0,0 +1,28 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	createSandboxRoutes,
+	createSandboxRuntime,
+	sandboxSettingsFromEnvironment,
+} from './server/index.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createSandboxRuntime({
+		...sandboxSettingsFromEnvironment(context.environment),
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+	});
+	return {
+		routes: createSandboxRoutes(context.auth, runtime),
+		dispose: () => runtime.dispose(),
+	};
+}

package/modules/sandbox/src/server/index.ts

@@ -0,0 +1,20 @@
+export { createSandboxRoutes, endpoints } from '../api/endpoints.ts';
+export {
+	createSandboxRuntime,
+	sandboxSettingsFromEnvironment,
+} from './runtime.ts';
+export type { SandboxRuntime, SandboxRuntimeOptions } from './runtime.ts';
+export {
+	DatabaseSandboxRepository,
+	directoryFromAuthRuntime,
+	migrateSandboxDatabase,
+	SandboxService,
+	SandboxServiceError,
+} from '../services/index.ts';
+export type {
+	GrantSandboxAccessInput,
+	RegisterSandboxSessionInput,
+	SandboxDirectory,
+	SandboxDirectoryMember,
+	SandboxRepository,
+} from '../services/index.ts';

package/modules/sandbox/src/server/runtime.ts

@@ -0,0 +1,119 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import { directoryFromAuthRuntime } from '../services/directory.ts';
+import { SandboxService } from '../services/sandbox-service.ts';
+import {
+	DatabaseSandboxRepository,
+	migrateSandboxDatabase,
+} from '../services/database-repository.ts';
+
+export interface SandboxRuntimeSettings {
+	/* Where the sandbox application is reachable. The platform only links to
+	   it; it never proxies sandbox traffic. */
+	readonly sandboxUrl: string;
+}
+
+export interface SandboxRuntimeOptions extends SandboxRuntimeSettings {
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+}
+
+export interface SandboxRuntime {
+	readonly options: SandboxRuntimeOptions;
+	service(auth: AuthRuntime): Promise<SandboxService>;
+	dispose(): Promise<void>;
+}
+
+function sandboxUrl(value: string | undefined): string {
+	const candidate = value?.trim() || 'http://127.0.0.1:4320';
+	let url: URL;
+	try {
+		url = new URL(candidate);
+	} catch {
+		throw new Error('FD_SANDBOX_URL must be an absolute URL.');
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+		throw new Error('FD_SANDBOX_URL must use http or https.');
+	}
+	return url.origin;
+}
+
+export function sandboxSettingsFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+): SandboxRuntimeSettings {
+	return { sandboxUrl: sandboxUrl(environment.FD_SANDBOX_URL) };
+}
+
+export function createSandboxRuntime(
+	options: SandboxRuntimeOptions,
+): SandboxRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<SandboxService> | undefined;
+
+	const initialize = async (auth: AuthRuntime): Promise<SandboxService> => {
+		/* Migrations take their own short lease: the runtime role is tenant
+		   scoped and may not run schema operations. */
+		const migrationLease = await options.databases.acquire({
+			namespace: 'sandbox.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		try {
+			await migrateSandboxDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = options.databases.acquire({
+			namespace: 'sandbox.core',
+			purpose: options.purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return new SandboxService(
+			new DatabaseSandboxRepository(lease.database),
+			directoryFromAuthRuntime(auth),
+		);
+	};
+
+	return {
+		options,
+		service: (auth) => {
+			if (disposed) {
+				return Promise.reject(new Error('Sandbox runtime is disposed.'));
+			}
+			servicePromise ??= initialize(auth);
+			return servicePromise;
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}