@flowdular/sdk 0.2.4 → 0.3.0

package/modules/automations-workflows-integration/spec/module.yaml

@@ -1,93 +0,0 @@
-schemaVersion: 1
-id: automations-workflows.integration
-specVersion: 0.1.0
-status: approved
-name: Automations Workflow Integration
-description: Connects schedules and signed webhooks owned by automations.core to published workflows through the public workflows.execution.v1 capability.
-profile: integration
-capabilities:
-  - integration
-dependencies:
-  - id: automations.core
-    range: 0.4.0
-  - id: workflows.core
-    range: 0.3.0
-tenancy: required
-locales:
-  - en
-  - pl
-invariants:
-  - The integration registers one versioned workflow target adapter through the public automations target extension contract and invokes workflows only through workflows.execution.v1.
-  - The integration owns no scheduler, polling interval, webhook route, signature verification, secret, workflow worker, execution history, database, HTTP endpoint, client view, or permission.
-  - automations.core remains the sole owner of schedule and webhook firing, target configuration, encrypted trigger secrets, configuredBy provenance, permission snapshots, and ingress audit evidence.
-  - workflows.core remains the sole owner of workflow selection by published key, exact revision snapshotting, durable enqueue, execution, cancellation, payload evidence, cost, run history, and workflow audit evidence.
-  - A schedule or webhook can select a workflow only when the configuring user can read published workflows, execute workflow runs, and satisfy every permission required by the selected published workflow.
-  - Automatic schedule and webhook invocations use a service actor for automations.core whose configuredBy field is the real user actor captured when the target was last configured, while schedule or webhook identity remains a separate execution origin.
-  - A user selecting Run now on a workflow schedule remains the real workflow actor; automations.core records the schedule correlation and invokes the workflow with module origin automations.core and operation schedules.run-now instead of disguising the user as an automatic service invocation.
-  - The workflow permission snapshot is captured by automations.core from trusted authorization context when the target is created or updated and cannot be supplied or widened by a schedule template, webhook body, or integration adapter.
-  - A schedule invocation uses the stable tenant-scoped key automations-workflows:schedule:<schedule-id>:<slot>, where slot is the exact persisted due timestamp owned by automations.core.
-  - A webhook invocation uses the stable tenant-scoped key automations-workflows:webhook:<trigger-id>:<accepted-signature-digest>, where the digest comes from the already verified signed request and exposes neither the trigger secret nor the request body.
-  - Repeating the same schedule slot or accepted signed webhook request resolves to the original workflow run, and a key reused for different workflow input is refused as an idempotency conflict.
-  - Schedule input resolves once through automations.core variable rules and must parse as bounded JSON before enqueue; an accepted webhook body must parse as bounded JSON before it is passed unchanged as workflow input.
-  - The adapter never accepts tenant, actor, configuredBy, permission, origin, workflow revision, mode, or idempotency fields from user-controlled input.
-  - If either required capability is absent, the workflow target is unavailable without weakening agent automations; existing workflow target configuration is retained, automatic firing is skipped with safe audit evidence, and signed webhook callers receive the normal indistinguishable refusal.
-  - A missing, archived, unpublished, or newly unauthorized workflow never falls back to another workflow or agent and never substitutes a latest revision selected outside workflows.core.
-  - Uninstalling the integration leaves automations.core agent schedules and triggers, workflows.core definitions and runs, and both modules' owned data fully usable and unchanged.
-dataOwnership:
-  - automations-workflows.integration owns no persistent records.
-  - automations.core owns the target kind, published workflow key reference, schedule input template, webhook ingress, service configuredBy user snapshot, trusted permission snapshot, stable source slot or accepted signature digest, and automation audit correlation.
-  - workflows.core owns the workflow run identifier, selected published revision, execution payload, node and edge evidence, usage, cost, status, cancellation, history, and workflow audit correlation.
-  - The integration passes stable correlation identifiers between the two owners and never copies private workflow evidence, webhook secrets, credentials, unrestricted bodies, or another module's database records.
-acceptanceScenarios:
-  - id: AUTO-WORKFLOW-REGISTER
-    given: automations.core, workflows.core, and the integration are composed.
-    when: Platform composition completes before module start hooks run.
-    then: Exactly one workflow target adapter is available to automations.core, duplicate registration stops boot, and no second scheduler, webhook ingress, or workflow worker starts.
-  - id: AUTO-WORKFLOW-OPTIONAL
-    given: The integration is not installed or workflows.core is unavailable.
-    when: A user opens automations or an automatic trigger becomes due.
-    then: Agent targets continue to work, workflow targets are hidden or marked unavailable, existing workflow target configuration is retained, no workflow run is created, and automations records a safe unavailable outcome without reading workflow storage.
-  - id: AUTO-WORKFLOW-CONFIGURE
-    given: A user can manage the schedule or trigger, read workflow definitions, execute workflow runs, and holds every permission required by a published workflow.
-    when: The user selects that workflow as the automation target.
-    then: automations.core stores the workflow key, service configuredBy user, trusted permission snapshot, and target input configuration without copying a workflow revision, graph, secret, or execution record.
-  - id: AUTO-WORKFLOW-CONFIGURE-DENY
-    given: A user lacks automation management, workflow read, workflow execution, or one permission required by the selected workflow.
-    when: The user attempts to create or update a workflow schedule or trigger.
-    then: automations.core refuses before persisting the target or invoking the adapter, and the integration grants no permission of its own.
-  - id: AUTO-WORKFLOW-SCHEDULE
-    given: An enabled workflow schedule is due for a persisted slot and its once-resolved input template produces schema-valid bounded JSON.
-    when: The automations worker fires that slot more than once because of polling or recovery.
-    then: The adapter enqueues one workflow by published key with a schedule origin, automations.core service actor, configuring user, trusted permission snapshot, and the same slot-derived idempotency key, and automations stores the returned run correlation.
-  - id: AUTO-WORKFLOW-RUN-NOW
-    given: An authorized user selects Run now on a workflow schedule and still holds every permission required by its published workflow.
-    when: automations.core asks the adapter to invoke the target with a bounded request identifier.
-    then: The adapter uses the real requesting user actor, module origin automations.core with operation schedules.run-now, the caller's current trusted permission snapshot, and a request-derived idempotency key while automations stores the schedule and run correlation.
-  - id: AUTO-WORKFLOW-WEBHOOK
-    given: An enabled workflow trigger receives a fresh valid signature and a bounded JSON body.
-    when: The same signed request is delivered more than once.
-    then: automations.core verifies ingress once per delivery, the adapter passes the parsed JSON unchanged with a webhook origin and stable signature-digest key, workflows.core returns the same run, and neither module exposes the secret or raw signature.
-  - id: AUTO-WORKFLOW-WEBHOOK-REFUSE
-    given: A workflow webhook has an invalid signature, stale timestamp, unknown identifier, disabled target, invalid JSON body, unavailable workflow capability, or workflow refusal.
-    when: The public fire route handles the request.
-    then: Every case returns the same external refusal, no alternate target runs, and the real bounded reason is stored only in tenant-scoped automation audit evidence.
-  - id: AUTO-WORKFLOW-ACTOR
-    given: A schedule or signed webhook was configured by a real user and later fires automatically.
-    when: Automation audit and workflow run history are inspected.
-    then: The automation event and workflow run share stable correlation identifiers, the workflow actor is the automations.core service with that user in configuredBy, and the schedule or trigger identifier appears only in the separate origin.
-  - id: AUTO-WORKFLOW-TENANT
-    given: Two tenants use the same workflow key and equivalent schedule or trigger identifiers and payloads.
-    when: Their automations fire.
-    then: Each adapter call uses only its trusted tenant context, idempotency is isolated per tenant, each run resolves that tenant's published workflow, and neither tenant can observe or affect the other's target or run.
-  - id: AUTO-WORKFLOW-UNAVAILABLE-TARGET
-    given: A configured workflow is archived, unpublished, missing, or no longer authorized by the stored permission snapshot.
-    when: Its schedule or webhook attempts to fire.
-    then: workflows.core refuses with its stable code, no fallback target or revision is selected, automations records a safe correlated failure, and the schedule or trigger is made visibly unavailable until an authorized user updates it.
-  - id: AUTO-WORKFLOW-IDEMPOTENCY-CONFLICT
-    given: An automation source reuses a persisted slot or accepted signature digest with a different workflow key or parsed input hash.
-    when: The adapter calls workflows.execution.v1 with the existing idempotency key.
-    then: workflows.core returns WORKFLOW_IDEMPOTENCY_CONFLICT, no second run is created, and automations records the refusal without retrying under a new key.
-  - id: AUTO-WORKFLOW-BOUNDARY
-    given: A workflow automation succeeds, fails, is refused, or is cancelled after durable enqueue.
-    when: The automation source reads its last outcome.
-    then: automations stores only target and run correlation plus a safe status summary, workflows retains the complete execution history, and the integration writes no duplicate run, audit, payload, usage, cost, or secret record.

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

@@ -1,14 +0,0 @@
-import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
-import manifest from '../module.json' with { type: 'json' };
-
-export const moduleDefinition = {
-	manifest: manifest as ModuleManifest,
-	navigation: [],
-	permissions: [],
-} satisfies RegisteredModule;
-
-export {
-	createWorkflowAutomationTargetAdapter,
-	registerAutomationsWorkflowsIntegration,
-	WorkflowAutomationTargetError,
-} from './server/adapter.ts';

package/modules/automations-workflows-integration/src/platform.ts

@@ -1,24 +0,0 @@
-import type {
-	PlatformServerComposition,
-	PlatformServerContext,
-} from '@flowdular/sdk/modules/auth/server';
-import {
-	AUTOMATION_EXECUTION_CAPABILITY,
-	type AutomationExecutionCapability,
-} from '@flowdular/sdk/modules/automations/server';
-import { registerAutomationsWorkflowsIntegration } from './server/adapter.ts';
-import { createAutomationWorkflowActionTools } from './server/tools.ts';
-
-export function createServerComposition(
-	context: PlatformServerContext,
-): PlatformServerComposition {
-	registerAutomationsWorkflowsIntegration(context.capabilities);
-	context.agentTools.register(
-		createAutomationWorkflowActionTools(() =>
-			context.capabilities.get<AutomationExecutionCapability>(
-				AUTOMATION_EXECUTION_CAPABILITY,
-			),
-		),
-	);
-	return { routes: [] };
-}

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

@@ -1,11 +0,0 @@
-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

@@ -1,21 +0,0 @@
-{
-	"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

@@ -1,21 +0,0 @@
-{
-	"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/workflows/src/services/cursor-codec.ts

@@ -1,62 +0,0 @@
-import { createHmac, timingSafeEqual } from 'node:crypto';
-
-export interface WorkflowCursorCodec {
-	encode(kind: 'wfrc1' | 'wfac1' | 'wfre1', payload: object): string;
-	decode<T extends object>(
-		kind: 'wfrc1' | 'wfac1' | 'wfre1',
-		cursor: string,
-	): T;
-}
-
-export function createWorkflowCursorCodec(secret: Buffer): WorkflowCursorCodec {
-	if (secret.length < 32)
-		throw new Error('Workflow cursor signing requires 32 bytes.');
-	return {
-		encode(kind, payload) {
-			const body = Buffer.from(JSON.stringify({ kind, ...payload })).toString(
-				'base64url',
-			);
-			const signature = createHmac('sha256', secret)
-				.update(body)
-				.digest('base64url');
-			return `${kind}.${body}.${signature}`;
-		},
-		decode<T extends object>(
-			kind: 'wfrc1' | 'wfac1' | 'wfre1',
-			cursor: string,
-		): T {
-			if (cursor.length > 2048) throw new Error('WORKFLOW_CURSOR_INVALID');
-			const [prefix, body, signature, extra] = cursor.split('.');
-			if (prefix !== kind || !body || !signature || extra !== undefined) {
-				throw new Error('WORKFLOW_CURSOR_INVALID');
-			}
-			const expected = createHmac('sha256', secret).update(body).digest();
-			let supplied: Buffer;
-			try {
-				supplied = Buffer.from(signature, 'base64url');
-			} catch {
-				throw new Error('WORKFLOW_CURSOR_INVALID');
-			}
-			if (
-				expected.length !== supplied.length ||
-				!timingSafeEqual(expected, supplied)
-			) {
-				throw new Error('WORKFLOW_CURSOR_INVALID');
-			}
-			let value: unknown;
-			try {
-				value = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
-			} catch {
-				throw new Error('WORKFLOW_CURSOR_INVALID');
-			}
-			if (
-				value === null ||
-				typeof value !== 'object' ||
-				(value as { kind?: unknown }).kind !== kind
-			) {
-				throw new Error('WORKFLOW_CURSOR_INVALID');
-			}
-			return value as T;
-		},
-	};
-}