@flowdular/sdk 0.1.0

package/modules/automations-workflows-integration/src/server/adapter.ts

@@ -0,0 +1,272 @@
+import {
+	serviceActor,
+	type PlatformCapabilityRegistry,
+} from '@flowdular/sdk/kernel';
+import {
+	AUTOMATION_TARGETS_CAPABILITY,
+	type AutomationTargetAdapter,
+	type AutomationTargetAuthorizationContext,
+	type AutomationTargetInvocationContext,
+	type AutomationTargetRegistry,
+} from '@flowdular/sdk/modules/automations/server';
+import { WORKFLOWS_PERMISSIONS } from '@flowdular/sdk/modules/workflows';
+import {
+	WORKFLOW_EXECUTION_CAPABILITY,
+	type WorkflowExecutionCapability,
+} from '@flowdular/sdk/modules/workflows/server';
+
+type WorkflowInput = Parameters<
+	WorkflowExecutionCapability['enqueue']
+>[0]['input'];
+
+export class WorkflowAutomationTargetError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'WorkflowAutomationTargetError';
+	}
+}
+
+function bounded(
+	value: string,
+	field: string,
+	min: number,
+	max: number,
+): string {
+	const normalized = value.trim();
+	if (
+		normalized.length < min ||
+		normalized.length > max ||
+		normalized.includes('\u0000')
+	) {
+		throw new WorkflowAutomationTargetError(
+			'AUTOMATION_TARGET_INPUT_INVALID',
+			`${field} is invalid.`,
+		);
+	}
+	return normalized;
+}
+
+function workflowsOrRefusal(
+	resolve: () => WorkflowExecutionCapability | null,
+): WorkflowExecutionCapability {
+	const workflows = resolve();
+	if (!workflows) {
+		throw new WorkflowAutomationTargetError(
+			'AUTOMATION_TARGET_UNAVAILABLE',
+			'Workflow execution is unavailable.',
+			503,
+		);
+	}
+	return workflows;
+}
+
+function workflowContext(context: AutomationTargetAuthorizationContext) {
+	return {
+		tenantId: bounded(context.tenantId, 'tenantId', 1, 128),
+		actor: context.actor,
+		authorizationSubject: context.actor,
+		permissionSnapshot: [...new Set(context.permissionSnapshot)].sort(),
+	};
+}
+
+async function requireExecutable(
+	resolve: () => WorkflowExecutionCapability | null,
+	workflowKey: string,
+	context: AutomationTargetAuthorizationContext,
+) {
+	const permissions = new Set(context.permissionSnapshot);
+	for (const permission of [
+		WORKFLOWS_PERMISSIONS.read,
+		WORKFLOWS_PERMISSIONS.runsExecute,
+	]) {
+		if (!permissions.has(permission)) {
+			throw new WorkflowAutomationTargetError(
+				'WORKFLOW_PERMISSION_DENIED',
+				'The workflow target requires workflow read and execute permissions.',
+				403,
+			);
+		}
+	}
+	const reference = await workflowsOrRefusal(resolve).getPublishedReference(
+		bounded(workflowKey, 'workflowKey', 3, 120),
+		workflowContext(context),
+	);
+	if (!reference) {
+		throw new WorkflowAutomationTargetError(
+			'WORKFLOW_NOT_FOUND',
+			'The published workflow target was not found.',
+			404,
+		);
+	}
+	for (const permission of reference.requiredPermissions) {
+		if (!permissions.has(permission)) {
+			throw new WorkflowAutomationTargetError(
+				'WORKFLOW_PERMISSION_DENIED',
+				'The workflow target requires permissions the configuring user does not hold.',
+				403,
+			);
+		}
+	}
+	return reference;
+}
+
+function idempotencyKey(context: AutomationTargetInvocationContext): string {
+	const source = context.source;
+	if (source.kind === 'schedule') {
+		if (!Number.isSafeInteger(source.slot) || source.slot < 0) {
+			throw new WorkflowAutomationTargetError(
+				'AUTOMATION_TARGET_INPUT_INVALID',
+				'Schedule slot is invalid.',
+			);
+		}
+		return `automations-workflows:schedule:${bounded(
+			source.scheduleId,
+			'scheduleId',
+			1,
+			128,
+		)}:${source.slot}`;
+	}
+	if (source.kind === 'webhook') {
+		const digest = bounded(
+			source.acceptedSignatureDigest,
+			'acceptedSignatureDigest',
+			64,
+			64,
+		);
+		if (!/^[a-f0-9]{64}$/.test(digest)) {
+			throw new WorkflowAutomationTargetError(
+				'AUTOMATION_TARGET_INPUT_INVALID',
+				'Accepted signature digest is invalid.',
+			);
+		}
+		return `automations-workflows:webhook:${bounded(
+			source.triggerId,
+			'triggerId',
+			1,
+			128,
+		)}:${digest}`;
+	}
+	return `automations-workflows:run-now:${bounded(
+		source.scheduleId,
+		'scheduleId',
+		1,
+		128,
+	)}:${bounded(source.requestId, 'requestId', 8, 80)}`;
+}
+
+export function createWorkflowAutomationTargetAdapter(
+	resolveWorkflows: () => WorkflowExecutionCapability | null,
+): AutomationTargetAdapter {
+	return {
+		kind: 'workflow',
+		contractVersion: 1,
+		available: () => resolveWorkflows() !== null,
+		async list(context) {
+			const published = await workflowsOrRefusal(
+				resolveWorkflows,
+			).listPublished(workflowContext(context));
+			const entries = [];
+			for (const workflow of published) {
+				try {
+					const executable = await requireExecutable(
+						resolveWorkflows,
+						workflow.key,
+						context,
+					);
+					entries.push({
+						key: executable.key,
+						label: executable.name,
+						revision: executable.revision,
+					});
+				} catch {
+					/* A workflow the configuring user may not execute is simply not
+					   offered as a target. */
+				}
+			}
+			return entries;
+		},
+		async validate(targetKey, context) {
+			const workflow = await requireExecutable(
+				resolveWorkflows,
+				targetKey,
+				context,
+			);
+			return {
+				key: workflow.key,
+				label: workflow.name,
+				revision: workflow.revision,
+			};
+		},
+		async invoke(request, context) {
+			const reference = await requireExecutable(
+				resolveWorkflows,
+				request.targetKey,
+				{
+					tenantId: context.tenantId,
+					actor: context.configuredBy,
+					permissionSnapshot: context.permissionSnapshot,
+				},
+			);
+			const source = context.source;
+			const actor =
+				source.kind === 'run-now'
+					? source.actor
+					: serviceActor({
+							serviceId: 'automations.core',
+							label: 'Automations',
+							configuredBy: context.configuredBy,
+						});
+			const origin =
+				source.kind === 'run-now'
+					? {
+							kind: 'module' as const,
+							moduleId: 'automations.core',
+							operationId: 'schedules.run-now',
+						}
+					: source.kind === 'schedule'
+						? { kind: 'schedule' as const, scheduleId: source.scheduleId }
+						: { kind: 'webhook' as const, triggerId: source.triggerId };
+			const accepted = await workflowsOrRefusal(resolveWorkflows).enqueue(
+				{
+					workflowKey: reference.key,
+					input: request.input as WorkflowInput,
+					idempotencyKey: idempotencyKey(context),
+				},
+				{
+					tenantId: bounded(context.tenantId, 'tenantId', 1, 128),
+					actor,
+					authorizationSubject:
+						source.kind === 'run-now' ? source.actor : context.configuredBy,
+					origin,
+					permissionSnapshot: [...new Set(context.permissionSnapshot)].sort(),
+				},
+			);
+			return {
+				correlationId: accepted.runId,
+				created: accepted.created,
+				status: accepted.status,
+			};
+		},
+	};
+}
+
+export function registerAutomationsWorkflowsIntegration(
+	capabilities: PlatformCapabilityRegistry,
+): boolean {
+	const targets = capabilities.get<AutomationTargetRegistry>(
+		AUTOMATION_TARGETS_CAPABILITY,
+	);
+	if (!targets) return false;
+	targets.register(
+		createWorkflowAutomationTargetAdapter(() =>
+			capabilities.get<WorkflowExecutionCapability>(
+				WORKFLOW_EXECUTION_CAPABILITY,
+			),
+		),
+	);
+	return true;
+}

package/modules/automations-workflows-integration/src/server/index.ts

@@ -0,0 +1,11 @@
+export {
+	createWorkflowAutomationTargetAdapter,
+	registerAutomationsWorkflowsIntegration,
+	WorkflowAutomationTargetError,
+} from './adapter.ts';
+export {
+	AUTOMATION_SCHEDULE_ACTION_ID,
+	createAutomationWorkflowActionTools,
+	WORKFLOW_DISPATCHABLE_TARGET_KINDS,
+	WorkflowAutomationActionError,
+} from './tools.ts';

package/modules/automations-workflows-integration/translations/en.json

@@ -0,0 +1,21 @@
+{
+	"module.name": "Automations Workflow Integration",
+	"navigation.label": "Automations Workflow Integration",
+	"navigation.description": "Connects schedules and signed webhooks owned by automations.core to published workflows through the public workflows.execution.v1 capability.",
+	"page.eyebrow": "Operations",
+	"page.title": "Automations Workflow Integration",
+	"page.description": "Connects schedules and signed webhooks owned by automations.core to published workflows through the public workflows.execution.v1 capability.",
+	"action.refresh": "Refresh",
+	"table.title": "Records",
+	"table.caption": "Automations Workflow Integration records",
+	"table.count": "{count} records",
+	"table.column.name": "Name",
+	"table.column.status": "Status",
+	"table.loading": "Loading records…",
+	"table.emptyTitle": "No records yet",
+	"table.emptyHint": "Records created in this workspace appear here.",
+	"status.active": "Active",
+	"status.archived": "Archived",
+	"error.load": "Could not load records.",
+	"error.request": "The records operation failed."
+}

package/modules/automations-workflows-integration/translations/pl.json

@@ -0,0 +1,21 @@
+{
+	"module.name": "Moduł Automations Workflow Integration",
+	"navigation.label": "Automations Workflow Integration",
+	"navigation.description": "Dane modułu Automations Workflow Integration",
+	"page.eyebrow": "Dane operacyjne",
+	"page.title": "Automations Workflow Integration",
+	"page.description": "Obsługa danych modułu Automations Workflow Integration.",
+	"action.refresh": "Odśwież",
+	"table.title": "Rekordy",
+	"table.caption": "Rekordy modułu Automations Workflow Integration",
+	"table.count": "Liczba rekordów: {count}",
+	"table.column.name": "Nazwa",
+	"table.column.status": "Status",
+	"table.loading": "Wczytywanie rekordów…",
+	"table.emptyTitle": "Brak rekordów",
+	"table.emptyHint": "Utworzone rekordy pojawią się w tym miejscu.",
+	"status.active": "Aktywny",
+	"status.archived": "Zarchiwizowany",
+	"error.load": "Nie udało się wczytać rekordów.",
+	"error.request": "Operacja na rekordach nie powiodła się."
+}

package/modules/profile/migrations/0001_profile_core.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS profile_records;

package/modules/profile/migrations/0001_profile_core.up.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS profile_records (
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS profile_records_tenant_account_idx ON profile_records (tenant_id, account_id);
+ALTER TABLE profile_records ENABLE ROW LEVEL SECURITY;
+ALTER TABLE profile_records FORCE ROW LEVEL SECURITY;
+CREATE POLICY profile_records_tenant_policy ON profile_records
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/profile/migrations/0002_profile_language.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS profile_language_preferences;

package/modules/profile/migrations/0002_profile_language.up.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS profile_language_preferences (
+  tenant_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  locale TEXT NOT NULL CHECK (length(locale) BETWEEN 2 AND 16),
+  updated_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, account_id)
+);
+ALTER TABLE profile_language_preferences ENABLE ROW LEVEL SECURITY;
+ALTER TABLE profile_language_preferences FORCE ROW LEVEL SECURITY;
+CREATE POLICY profile_language_preferences_tenant_policy ON profile_language_preferences
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/profile/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Add ordered, reversible migrations only when the approved spec owns data.

package/modules/profile/module.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "profile.core",
+	"package": "@flowdular/module-profile",
+	"version": "1.5.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations", "integration"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "auth.core",
+			"range": "0.10.0"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental",
+	"platformApi": "0.1.0"
+}

package/modules/profile/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@flowdular/module-profile",
+	"version": "1.5.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/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"octane": "0.1.51",
+		"segment-state": "0.2.0"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@octanejs/app-core": "0.0.47",
+		"@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/profile"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/modules/profile/spec/module.yaml

@@ -0,0 +1,136 @@
+schemaVersion: 1
+id: profile.core
+specVersion: '1.5.0'
+status: approved
+name: Profile
+description: Allows a signed-in user to manage their own tenant-scoped display name and interface language, request a password change after confirming their current password, and review or end their own sessions.
+profile: full
+
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - integration
+
+dependencies:
+  - id: auth.core
+    range: 0.10.0
+
+tenancy: required
+
+locales:
+  - en
+  - pl
+
+invariants:
+  - Every operation requires an authenticated principal and the declared profile permission.
+  - A user can read or change only the profile identified by their authenticated principal in the current tenant.
+  - The trusted tenant identifier and user identifier come from the authenticated principal and are never accepted from request data.
+  - Every profile query and mutation is scoped by both the trusted tenant identifier and authenticated principal identifier.
+  - Profile persistence uses a platform-provided database handle; module code never receives a connection string, owns a production pool, or reaches another module's database.
+  - Every runtime persistence operation executes inside a transaction carrying the authenticated tenant identifier, while every SQL statement also retains an explicit tenant predicate.
+  - PostgreSQL tables owned by profile.core enable and force row-level security, with USING and WITH CHECK policies bound to the transaction-local coreloom.tenant_id value.
+  - Migrations are declared as explicit PostgreSQL SQL; profile.core never rewrites placeholders or translates SQL between dialects.
+  - Adopting the adapter migration ledger on an existing profile schema preserves every profile and language-preference row and refuses a partially present schema.
+  - A personal interface language is stored by authenticated account and tenant; a preference from another account or tenant is never returned or applied.
+  - The server preference is authoritative after authentication; a tenant-and-account-scoped browser value is only an unavailable-server cache.
+  - Only locales declared by profile.core can be stored as a personal interface language.
+  - A display-name change affects only the authenticated user's profile in the current tenant.
+  - Passwords, password hashes, current-password values, session tokens, and provider credentials are never stored, hashed, logged, audited, or returned by profile.core.
+  - A password change is delegated to the registered auth.core password-change endpoint and is never performed directly by profile.core.
+  - Session listing and revocation are delegated to the auth.core session endpoints; profile.core never reads or stores session tokens.
+  - The current password and proposed password are sent only to auth.core for the duration of the password-change request.
+  - A failed display-name change leaves the existing display name unchanged.
+  - A rejected or unavailable password-change request leaves the password unchanged and creates no local password state.
+  - Failure responses contain enough information for the user to correct the request without exposing credentials, password policy details beyond those returned for correction, or another account's existence.
+
+permissions:
+  - id: profile.self.manage
+    description: Allows a signed-in user to view and change only their own display name and language, and request a password change for only their own account.
+
+dataOwnership:
+  - profile.core owns tenant-scoped profile records containing the display name and personal interface-language preference for each user.
+  - profile.core reads the authenticated account identity and password-change result through auth.core services.
+  - auth.core owns passwords, password hashes, password history, password policy, sessions, session tokens, and provider credentials.
+
+acceptanceScenarios:
+  - id: CHANGE-OWN-DISPLAY-NAME
+    given: A user is signed in to a tenant, has profile.self.manage, and has an existing profile in that tenant.
+    when: The user submits a valid new display name for their own profile.
+    then: The display name is updated only for that user's profile in the current tenant and the response returns the updated non-secret profile data.
+
+  - id: REJECT-INVALID-DISPLAY-NAME
+    given: A user is signed in to a tenant, has profile.self.manage, and has an existing display name.
+    when: The user submits a display name that fails the declared profile validation rules.
+    then: The request fails with a corrective validation error and the existing display name remains unchanged.
+
+  - id: CHANGE-OWN-PASSWORD
+    given: A user is signed in to a tenant, has profile.self.manage, and provides their correct current password and an acceptable new password.
+    when: The user requests a password change for their own account.
+    then: profile.core delegates the request to the registered auth.core password-change endpoint, auth.core changes the password, and profile.core stores, logs, audits, and returns no password or password hash.
+
+  - id: REJECT-INCORRECT-CURRENT-PASSWORD
+    given: A user is signed in to a tenant, has profile.self.manage, and provides an incorrect current password.
+    when: The user requests a password change for their own account.
+    then: auth.core rejects the request, the password remains unchanged, profile.core creates no local password state, and the response does not expose credential material.
+
+  - id: HANDLE-AUTH-CORE-UNAVAILABLE
+    given: A user is signed in to a tenant, has profile.self.manage, and auth.core cannot complete the password-change request.
+    when: The user requests a password change for their own account.
+    then: The request fails with a non-success response, the password remains unchanged, no local password state is created, and the user can retry safely.
+
+  - id: DENY-UNAUTHENTICATED-REQUEST
+    given: No authenticated principal is available.
+    when: A request attempts to read or change a profile or change a password.
+    then: The request is denied, no profile or password state changes, and no account data is returned.
+
+  - id: DENY-REQUEST-WITHOUT-PERMISSION
+    given: A user is signed in but does not have profile.self.manage.
+    when: The user attempts to read or change their profile or change their password.
+    then: The request is denied and no profile or password state changes.
+
+  - id: DENY-EDITING-ANOTHER-ACCOUNT
+    given: A user is signed in to a tenant and has profile.self.manage.
+    when: The user attempts to target another user's profile or account.
+    then: The request is denied, the other user's profile and password remain unchanged, and the response does not reveal whether the targeted account exists.
+
+  - id: ISOLATE-PROFILES-BETWEEN-TENANTS
+    given: A signed-in user has profile.self.manage in one tenant and a profile record exists in another tenant.
+    when: The user attempts to read or change the profile record in the other tenant.
+    then: The request is denied or returns no record, the other tenant's data remains unchanged, and the response reveals no profile data from the other tenant.
+
+  - id: REVIEW-OWN-SESSIONS
+    given: A signed-in user with more than one live session.
+    when: The user opens Profile and ends a session that is not the current one.
+    then: The list marks the current device, the ended session no longer resolves, and the current session is unchanged.
+
+  - id: SAVE-OWN-INTERFACE-LANGUAGE
+    given: A user is signed in to a tenant, has profile.self.manage, and selects a locale declared by profile.core.
+    when: The user changes their personal interface language.
+    then: The language is applied immediately, stored only for that account in the current tenant, and restored from the server on the next authenticated application start.
+
+  - id: ISOLATE-INTERFACE-LANGUAGE
+    given: The same account has different personal language preferences in two tenants.
+    when: The account opens either tenant.
+    then: The server returns and the client applies only the preference stored for the active tenant.
+
+  - id: REJECT-UNSUPPORTED-INTERFACE-LANGUAGE
+    given: A user is signed in and has profile.self.manage.
+    when: The user submits a locale that profile.core does not declare.
+    then: The request fails without changing the stored preference or active server-backed language.
+
+  - id: PRESERVE-EXISTING-PROFILES
+    given: A profile database contains profile and language-preference rows created before the database adapter ledger was introduced.
+    when: profile.core starts against that schema for the first time.
+    then: The existing schema is adopted without replaying its migrations, every existing row is preserved, and subsequent starts leave the ledger and data unchanged.
+
+  - id: ENFORCE-POSTGRESQL-TENANT-BOUNDARY
+    given: profile.core runs on PostgreSQL and two tenants have profile records with the same account identifier.
+    when: A runtime transaction is bound to either tenant and reads or writes profile data.
+    then: Only that tenant's rows are visible or mutable, a transaction without a tenant is refused, and the forced row-level security policy rejects a row carrying another tenant identifier.
+
+  - id: RUN-ON-SUPPORTED-DATABASE-ADAPTERS
+    given: The platform provides profile.core a PostgreSQL database handle and a separate migration lease.
+    when: profile.core initializes its persistence runtime.
+    then: It applies or adopts the explicit PostgreSQL migrations, releases the migration lease, and serves the profile repository contract through the tenant-bound runtime lease.

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

@@ -0,0 +1,5 @@
+export const PROFILE_PERMISSIONS = {
+	manageSelf: 'profile.self.manage',
+} as const;
+
+export const permissions = Object.freeze(Object.values(PROFILE_PERMISSIONS));