@flowdular/sdk 0.1.0

package/modules/sandbox/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@flowdular/module-sandbox",
+	"version": "0.4.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/cli-protocol": "workspace:*",
+		"@flowdular/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"@octanejs/app-core": "0.0.47",
+		"octane": "0.1.51",
+		"segment-state": "0.2.0"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "modules/sandbox"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/modules/sandbox/spec/module.yaml

@@ -0,0 +1,111 @@
+schemaVersion: 1
+id: sandbox.core
+specVersion: 0.4.0
+status: approved
+name: Sandbox Access
+description: Owns sandbox access grants, sandbox session records, and the audit evidence that lets an authorized account open the Flowdular sandbox, preview a draft module against live platform data, and eject an accepted module into the workspace.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - cli
+dependencies:
+  - id: system.core
+    range: 0.5.0
+  - id: auth.core
+    range: 0.10.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on PostgreSQL through the shared asynchronous database contract. The module receives a leased handle from platform composition, never a driver or a connection string, and writes explicit PostgreSQL SQL.
+  - Migrations are declared as explicit PostgreSQL SQL; sandbox.core never rewrites placeholders or translates SQL between dialects.
+  - PostgreSQL grant, session, and audit tables enable and force row-level security with USING and WITH CHECK policies bound to transaction-local coreloom.tenant_id, and the runtime role holds neither SUPERUSER nor BYPASSRLS. Migrations use a separate lease.
+  - Every access grant, session record, and audit event is owned by exactly one tenant, and every repository query receives the trusted tenant identifier.
+  - The sandbox is a separate application. It never receives platform authority implicitly; it must resolve an authenticated account, the sandbox.access.use scope on the selected membership, and an active grant before it opens a session.
+  - A grant is created only by an authorized owner through the platform API or through the sandbox CLI capability. Both paths write the same record and the same audit evidence.
+  - A grant is revocable and may carry an expiry. A revoked or expired grant denies sandbox sign-in and every sandbox capability check without further lookup.
+  - Grant capabilities are a subset of the sandbox scopes held by the granted membership. A grant can narrow authority and can never widen it beyond the account's platform scopes.
+  - Sandbox sessions are metadata only. Draft source code, chat transcripts, and provider credentials are owned by the sandbox application and never enter this module's database or API responses.
+  - Preview data bridging requires the sandbox.preview.data scope on the grant. Without it the sandbox serves fixtures and never forwards a request to the full application.
+  - Ejecting a draft module requires the sandbox.modules.eject scope, an explicit apply flag, and passing module and specification gates. The eject path never edits the platform composition by hand.
+  - Local coding agent binaries are offered only by a sandbox in loopback mode. A self-hosted sandbox exposes bring-your-own-key providers only.
+  - Access changes, session lifecycle transitions, and eject attempts are recorded as append-only tenant-scoped audit events with the actor, action, subject, timestamp, and safe metadata.
+  - Passwords, session tokens, provider credentials, and draft source contents are never stored, logged, or returned by this module.
+  - Sandbox navigation is development surface. It is visible to tenant owners, and server scopes remain authoritative.
+permissions:
+  - id: sandbox.access.use
+    description: Sign in to the sandbox and open sessions for the active tenant.
+  - id: sandbox.access.manage
+    description: Grant, narrow, and revoke sandbox access for members of the active tenant.
+  - id: sandbox.sessions.read
+    description: Read sandbox session records of the active tenant.
+  - id: sandbox.preview.data
+    description: Allow a sandbox preview to read live platform data through the bridge.
+  - id: sandbox.modules.eject
+    description: Eject an accepted sandbox module into the workspace module tree.
+dataOwnership:
+  - sandbox.core owns sandbox access grants, their capability subset, expiry, revocation state, and the identity of the granting actor.
+  - 'sandbox.core owns sandbox session records: identifier, owning account, target module identifier, blueprint, lifecycle state, driver identifier, and timestamps.'
+  - sandbox.core owns the append-only sandbox audit chain for access, session, and eject events.
+  - The sandbox application owns session workspaces, draft source files, chat transcripts, ephemeral preview databases, and provider credentials. Business modules own their records and answer bridged preview requests through their own services and ACL rules.
+acceptanceScenarios:
+  - id: SANDBOX-GRANT-API
+    given: An owner with sandbox.access.manage and a member of the active tenant.
+    when: The owner grants sandbox access with a capability subset.
+    then: A tenant-scoped grant is persisted, capabilities are intersected with the member's platform scopes, and an audit event records the actor and subject.
+  - id: SANDBOX-GRANT-CLI
+    given: A local operator running the sandbox CLI capability with an explicit apply flag.
+    when: The operator grants sandbox access to an existing account of a tenant.
+    then: The same grant record and audit event are written and the command returns the resulting capabilities as machine-readable evidence.
+  - id: SANDBOX-GRANT-DRY-RUN
+    given: A local operator running the sandbox grant capability without an apply flag.
+    when: The command executes.
+    then: The resolved account, tenant, and capability subset are reported, no record is written, and the response is marked as a dry run.
+  - id: SANDBOX-REVOKE
+    given: An active grant for a member.
+    when: An owner revokes it from the platform or from the CLI.
+    then: The grant is marked revoked with a timestamp, sandbox authorization fails immediately, and an audit event is appended.
+  - id: SANDBOX-AUTHORIZE
+    given: An authenticated account with sandbox.access.use and an active grant on the selected tenant.
+    when: The sandbox resolves sandbox authority for that account and tenant.
+    then: The effective capability set is returned as the intersection of platform scopes and grant capabilities.
+  - id: SANDBOX-AUTHORIZE-DENY
+    given: An account whose grant is missing, revoked, or expired, or whose membership lacks sandbox.access.use.
+    when: The sandbox resolves sandbox authority.
+    then: Authority is denied with a stable reason and no session is opened.
+  - id: SANDBOX-SESSION-RECORD
+    given: An authorized sandbox principal opens a session for a draft module.
+    when: The session is registered.
+    then: A tenant-scoped session record is persisted with its lifecycle state, and later state transitions update the same record with audit evidence.
+  - id: SANDBOX-BRIDGE-DENY
+    given: A sandbox session whose grant lacks sandbox.preview.data.
+    when: The preview requests platform data through the bridge.
+    then: The request is denied before any call to the full application and the preview continues on fixtures.
+  - id: SANDBOX-EJECT-DRY-RUN
+    given: A session in the accepted state and an operator with sandbox.modules.eject.
+    when: The eject capability runs without an apply flag.
+    then: Every target path and every gate that will run is reported and no file is written into the module tree.
+  - id: SANDBOX-EJECT-APPLY
+    given: The same session and operator with an explicit apply flag.
+    when: The eject capability runs.
+    then: The module is copied into the module tree, module and specification gates pass, module enable is invoked through the existing capability, and an audit event records the result.
+  - id: SANDBOX-TENANT-ISOLATION
+    given: Grants and sessions exist in two tenants.
+    when: Any read or write is executed with a tenant identifier.
+    then: Only records of that tenant are visible and cross-tenant access is denied by the server.
+  - id: SANDBOX-DENY-UNAUTHORIZED
+    given: A principal that is unauthenticated or lacks the required sandbox scope.
+    when: The principal reads grants, manages grants, or requests eject.
+    then: The server denies the operation before data or workspace effects are exposed.
+  - id: SANDBOX-AUDIT-READ
+    given: A principal reads the sandbox audit trail over HTTP.
+    when: The principal lacks sandbox.sessions.read, or holds it and pages with a cursor.
+    then: The request is denied before any row is read without the scope, and with it only the active tenant's events are returned newest first with a stable occurred-at and sequence cursor and the chain fields.
+  - id: SANDBOX-AUDIT-VERIFY
+    given: A stored sandbox audit row is altered after it was written.
+    when: A principal with sandbox.sessions.read verifies the chain over HTTP, reusing the same walk as the audit-verify CLI.
+    then: The response reports the chain as not verified and names the identifier of the first broken row.

package/modules/sandbox/src/acl/permissions.ts

@@ -0,0 +1,18 @@
+export const SANDBOX_PERMISSIONS = {
+	use: 'sandbox.access.use',
+	manage: 'sandbox.access.manage',
+	sessionsRead: 'sandbox.sessions.read',
+	previewData: 'sandbox.preview.data',
+	eject: 'sandbox.modules.eject',
+} as const;
+
+/* Capabilities a grant can carry. Managing grants stays a platform scope and
+   is never delegated into the sandbox application. */
+export const SANDBOX_GRANT_CAPABILITIES = Object.freeze([
+	SANDBOX_PERMISSIONS.use,
+	SANDBOX_PERMISSIONS.sessionsRead,
+	SANDBOX_PERMISSIONS.previewData,
+	SANDBOX_PERMISSIONS.eject,
+]);
+
+export const permissions = Object.freeze(Object.values(SANDBOX_PERMISSIONS));

package/modules/sandbox/src/api/endpoints.ts

@@ -0,0 +1,439 @@
+import {
+	defineEndpoint,
+	HttpProblem,
+	jsonResponse,
+	problemResponse,
+	readJsonObject,
+	requiredString,
+} from '@flowdular/sdk/server';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import {
+	endpointIdentityFromContext,
+	isTokenPrincipal,
+	principalFromContext,
+	sessionMutationDenial,
+} from '@flowdular/sdk/modules/auth/server';
+import type { Context } from '@octanejs/app-core';
+import { SANDBOX_PERMISSIONS } from '../acl/permissions.ts';
+import type { SandboxSessionState } from '../domain/types.ts';
+import { SandboxServiceError } from '../services/sandbox-service-error.ts';
+import type { SandboxRuntime } from '../server/runtime.ts';
+
+/* A browser session is guarded by CSRF. An API token is never sent
+   automatically by a browser, so it carries no CSRF risk and is checked by its
+   scopes alone. */
+function mutationDenial(context: Context, auth: AuthRuntime): Response | null {
+	return isTokenPrincipal(context)
+		? null
+		: sessionMutationDenial(context, auth);
+}
+
+function failure(error: unknown): Response {
+	if (error instanceof SandboxServiceError) {
+		return jsonResponse(
+			{ error: { code: error.code, message: error.message } },
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The sandbox operation failed.');
+}
+
+function optionalCapabilities(
+	value: Record<string, unknown>,
+): readonly string[] | undefined {
+	const raw = value.capabilities;
+	if (raw === undefined || raw === null) return undefined;
+	if (
+		!Array.isArray(raw) ||
+		raw.length > 8 ||
+		raw.some((entry) => typeof entry !== 'string')
+	) {
+		throw new HttpProblem(
+			'INVALID_CAPABILITIES',
+			'capabilities must be an array of capability identifiers.',
+			400,
+		);
+	}
+	return raw as readonly string[];
+}
+
+function optionalExpiry(value: Record<string, unknown>): number | null {
+	const raw = value.expiresAt;
+	if (raw === undefined || raw === null) return null;
+	if (typeof raw !== 'number' || !Number.isSafeInteger(raw)) {
+		throw new HttpProblem(
+			'INVALID_EXPIRY',
+			'expiresAt must be an integer timestamp in milliseconds.',
+			400,
+		);
+	}
+	return raw;
+}
+
+function optionalNote(value: Record<string, unknown>): string | null {
+	const raw = value.note;
+	if (raw === undefined || raw === null || raw === '') return null;
+	if (typeof raw !== 'string' || raw.length > 280) {
+		throw new HttpProblem(
+			'INVALID_NOTE',
+			'note must be a string of at most 280 characters.',
+			400,
+		);
+	}
+	return raw;
+}
+
+function ejectMetadata(
+	value: Record<string, unknown>,
+): Readonly<Record<string, string | number | boolean>> {
+	const raw = value.metadata;
+	if (raw === undefined || raw === null) return {};
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+		throw new HttpProblem(
+			'INVALID_METADATA',
+			'metadata must be an object of strings, numbers, and booleans.',
+			400,
+		);
+	}
+	const entries = Object.entries(raw as Record<string, unknown>);
+	if (entries.length > 20) {
+		throw new HttpProblem(
+			'INVALID_METADATA',
+			'metadata may hold at most 20 entries.',
+			400,
+		);
+	}
+	const metadata: Record<string, string | number | boolean> = {};
+	for (const [key, entry] of entries) {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(key) ||
+			(typeof entry !== 'boolean' &&
+				typeof entry !== 'number' &&
+				(typeof entry !== 'string' || entry.length > 500))
+		) {
+			throw new HttpProblem(
+				'INVALID_METADATA',
+				'metadata must be an object of strings, numbers, and booleans.',
+				400,
+			);
+		}
+		metadata[key] = entry;
+	}
+	return metadata;
+}
+
+export function createSandboxRoutes(
+	auth: AuthRuntime,
+	runtime: SandboxRuntime,
+) {
+	const access = defineEndpoint({
+		id: 'sandbox.access.snapshot',
+		path: '/api/sandbox/access',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const principal = principalFromContext(octane)!;
+			const service = await runtime.service(auth);
+			return jsonResponse({
+				sandbox: { url: runtime.options.sandboxUrl },
+				grants: await service.listGrants(principal.tenantId),
+				candidates: await service.listCandidates(principal.tenantId),
+			});
+		},
+	});
+
+	const grant = defineEndpoint({
+		id: 'sandbox.access.create-grant',
+		path: '/api/sandbox/access',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const principal = principalFromContext(octane)!;
+				const value = await readJsonObject(octane.request);
+				return jsonResponse(
+					{
+						grant: await (
+							await runtime.service(auth)
+						).grant({
+							tenantId: principal.tenantId,
+							actorId: principal.accountId,
+							accountId: requiredString(value, 'accountId', { max: 128 }),
+							capabilities: optionalCapabilities(value),
+							expiresAt: optionalExpiry(value),
+							note: optionalNote(value),
+						}),
+					},
+					201,
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const revoke = defineEndpoint({
+		id: 'sandbox.access.revoke-grant',
+		path: '/api/sandbox/access/revoke',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const principal = principalFromContext(octane)!;
+				const value = await readJsonObject(octane.request);
+				return jsonResponse({
+					grant: await (
+						await runtime.service(auth)
+					).revoke(
+						principal.tenantId,
+						requiredString(value, 'accountId', { max: 128 }),
+						principal.accountId,
+					),
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const sessions = defineEndpoint({
+		id: 'sandbox.sessions.snapshot',
+		path: '/api/sandbox/sessions',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: SANDBOX_PERMISSIONS.sessionsRead,
+		},
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const principal = principalFromContext(octane)!;
+			return jsonResponse({
+				sessions: await (
+					await runtime.service(auth)
+				).listSessions(principal.tenantId, 50),
+			});
+		},
+	});
+
+	const audit = defineEndpoint({
+		id: 'sandbox.audit.snapshot',
+		path: '/api/sandbox/audit',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: SANDBOX_PERMISSIONS.sessionsRead,
+		},
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const url = new URL(octane.request.url);
+				const limit = Number(url.searchParams.get('limit') ?? '50');
+				return jsonResponse(
+					await (
+						await runtime.service(auth)
+					).pageAuditEvents(
+						principal.tenantId,
+						url.searchParams.get('cursor'),
+						Number.isSafeInteger(limit) ? limit : 50,
+					),
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const verifyAudit = defineEndpoint({
+		id: 'sandbox.audit.verify',
+		path: '/api/sandbox/audit/verify',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: SANDBOX_PERMISSIONS.sessionsRead,
+		},
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				return jsonResponse(
+					await (await runtime.service(auth)).verifyAudit(principal.tenantId),
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const authority = defineEndpoint({
+		id: 'sandbox.authority.resolve',
+		path: '/api/sandbox/authority',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.use },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const principal = principalFromContext(octane)!;
+			return jsonResponse({
+				principal: {
+					accountId: principal.accountId,
+					tenantId: principal.tenantId,
+					email: principal.email,
+					displayName: principal.displayName,
+					role: principal.role,
+					scopes: principal.scopes,
+					tenantName:
+						principal.tenants.find(
+							(tenant) => tenant.tenantId === principal.tenantId,
+						)?.name ?? principal.tenantId,
+					tenantSlug:
+						principal.tenants.find(
+							(tenant) => tenant.tenantId === principal.tenantId,
+						)?.slug ?? '',
+				},
+				authority: await (
+					await runtime.service(auth)
+				).authorize(principal.tenantId, principal.accountId, principal.scopes),
+				sandbox: { url: runtime.options.sandboxUrl },
+			});
+		},
+	});
+
+	const registerSession = defineEndpoint({
+		id: 'sandbox.sessions.register',
+		path: '/api/sandbox/sessions',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.use },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = mutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const principal = principalFromContext(octane)!;
+				const value = await readJsonObject(octane.request);
+				const mode = requiredString(value, 'mode', { max: 16 });
+				if (mode !== 'loopback' && mode !== 'self-hosted') {
+					throw new HttpProblem(
+						'INVALID_MODE',
+						'mode must be loopback or self-hosted.',
+						400,
+					);
+				}
+				return jsonResponse(
+					{
+						session: await (
+							await runtime.service(auth)
+						).registerSession({
+							tenantId: principal.tenantId,
+							accountId: principal.accountId,
+							sessionId: requiredString(value, 'sessionId', { max: 128 }),
+							moduleId: requiredString(value, 'moduleId', { max: 128 }),
+							title: requiredString(value, 'title', { min: 2, max: 120 }),
+							blueprint: requiredString(value, 'blueprint', { max: 120 }),
+							driver: requiredString(value, 'driver', { max: 64 }),
+							mode,
+						}),
+					},
+					201,
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const updateSessionState = defineEndpoint({
+		id: 'sandbox.sessions.transition',
+		path: '/api/sandbox/sessions/state',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.use },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = mutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const principal = principalFromContext(octane)!;
+				const value = await readJsonObject(octane.request);
+				return jsonResponse({
+					session: await (
+						await runtime.service(auth)
+					).updateSessionState(
+						principal.tenantId,
+						requiredString(value, 'sessionId', { max: 128 }),
+						requiredString(value, 'state', {
+							max: 32,
+						}) as SandboxSessionState,
+						principal.accountId,
+					),
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	/* Eject evidence, written by the sandbox after every step of a delivery
+	   passed. Metadata is bounded scalars: what landed, never the sources. */
+	const recordEject = defineEndpoint({
+		id: 'sandbox.sessions.eject-record',
+		path: '/api/sandbox/sessions/eject',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: SANDBOX_PERMISSIONS.eject },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = mutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const principal = principalFromContext(octane)!;
+				const value = await readJsonObject(octane.request);
+				return jsonResponse(
+					{
+						event: await (
+							await runtime.service(auth)
+						).recordEject(
+							principal.tenantId,
+							requiredString(value, 'sessionId', { max: 128 }),
+							principal.accountId,
+							ejectMetadata(value),
+						),
+					},
+					201,
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	return [
+		authority.serverRoute,
+		registerSession.serverRoute,
+		updateSessionState.serverRoute,
+		recordEject.serverRoute,
+		access.serverRoute,
+		grant.serverRoute,
+		revoke.serverRoute,
+		sessions.serverRoute,
+		audit.serverRoute,
+		verifyAudit.serverRoute,
+	] as const;
+}
+
+export const endpoints = [
+	'sandbox.authority.resolve',
+	'sandbox.sessions.register',
+	'sandbox.sessions.transition',
+	'sandbox.sessions.eject-record',
+	'sandbox.access.snapshot',
+	'sandbox.access.create-grant',
+	'sandbox.access.revoke-grant',
+	'sandbox.sessions.snapshot',
+	'sandbox.audit.snapshot',
+	'sandbox.audit.verify',
+] as const;