feat(workflow): add Workflow 1.0 protocol over DIDComm v2

packages/workflow/jest.config.ts

@@ -0,0 +1,21 @@
+import type { Config } from '@jest/types'
+
+const config: Config.InitialOptions = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          isolatedModules: true,
+        },
+      },
+    ],
+  },
+  displayName: '@credo-ts/workflow',
+  testMatch: ['**/?(*.)test.ts', '**/?(*.)spec.ts'],
+  setupFilesAfterEnv: ['./src/tests/setup.ts'],
+}
+
+export default config

packages/workflow/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@credo-ts/workflow",
+  "main": "src/index",
+  "types": "src/index",
+  "version": "0.5.13",
+  "files": ["build"],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "main": "build/index",
+    "types": "build/index",
+    "access": "public"
+  },
+  "homepage": "https://github.com/openwallet-foundation/credo-ts/tree/main/packages/workflow",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openwallet-foundation/credo-ts",
+    "directory": "packages/workflow"
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run compile",
+    "clean": "rimraf ./build",
+    "compile": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run build",
+    "test": "jest",
+    "test:cov": "jest --coverage --runInBand"
+  },
+  "dependencies": {
+    "@credo-ts/core": "workspace:*",
+    "@credo-ts/didcomm": "workspace:*",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "jmespath": "^0.16.0"
+  },
+  "devDependencies": {
+    "@credo-ts/askar": "workspace:*",
+    "@credo-ts/node": "workspace:*",
+    "@openwallet-foundation/askar-nodejs": "catalog:",
+    "@types/jmespath": "^0.15.2",
+    "reflect-metadata": "catalog:",
+    "rimraf": "catalog:",
+    "typescript": "catalog:"
+  }
+}

packages/workflow/src/WorkflowEvents.ts

@@ -0,0 +1,39 @@
+import type { BaseEvent } from '@credo-ts/core'
+import type { WorkflowInstanceRecord, WorkflowInstanceStatus } from './repository/WorkflowInstanceRecord'
+
+export enum WorkflowEventTypes {
+  WorkflowInstanceStateChanged = 'WorkflowInstanceStateChanged',
+  WorkflowInstanceStatusChanged = 'WorkflowInstanceStatusChanged',
+  WorkflowInstanceCompleted = 'WorkflowInstanceCompleted',
+}
+
+export interface WorkflowInstanceStateChangedEvent extends BaseEvent {
+  type: WorkflowEventTypes.WorkflowInstanceStateChanged
+  payload: {
+    instanceRecord: WorkflowInstanceRecord
+    previousState: string | null
+    newState: string
+    event: string
+    actionKey?: string
+    msgId?: string
+  }
+}
+
+export interface WorkflowInstanceStatusChangedEvent extends BaseEvent {
+  type: WorkflowEventTypes.WorkflowInstanceStatusChanged
+  payload: {
+    instanceRecord: WorkflowInstanceRecord
+    previousStatus: WorkflowInstanceStatus | null
+    newStatus: WorkflowInstanceStatus
+    reason?: string
+  }
+}
+
+export interface WorkflowInstanceCompletedEvent extends BaseEvent {
+  type: WorkflowEventTypes.WorkflowInstanceCompleted
+  payload: {
+    instanceRecord: WorkflowInstanceRecord
+    state: string
+    section?: string
+  }
+}

packages/workflow/src/WorkflowModule.ts

@@ -0,0 +1,105 @@
+import type { AgentContext, DependencyManager, Module } from '@credo-ts/core'
+import { AgentConfig, EventEmitter } from '@credo-ts/core'
+import {
+  DidCommCredentialEventTypes,
+  DidCommCredentialState,
+  DidCommCredentialStateChangedEvent,
+  DidCommFeatureRegistry,
+  DidCommMessageHandlerRegistry,
+  DidCommProofEventTypes,
+  DidCommProofState,
+  DidCommProofStateChangedEvent,
+  DidCommProtocol,
+} from '@credo-ts/didcomm'
+import { WorkflowModuleConfig, WorkflowModuleConfigOptions } from './WorkflowModuleConfig'
+import { WorkflowApi } from './api/WorkflowApi'
+import { AdvanceHandler } from './protocol/handlers/AdvanceHandler'
+import { CancelHandler } from './protocol/handlers/CancelHandler'
+import { CompleteHandler } from './protocol/handlers/CompleteHandler'
+import { PauseHandler } from './protocol/handlers/PauseHandler'
+import { ProblemReportHandler } from './protocol/handlers/ProblemReportHandler'
+import { PublishTemplateHandler } from './protocol/handlers/PublishTemplateHandler'
+import { ResumeHandler } from './protocol/handlers/ResumeHandler'
+import { StartHandler } from './protocol/handlers/StartHandler'
+import { StatusHandler } from './protocol/handlers/StatusHandler'
+import { WorkflowInstanceRepository } from './repository/WorkflowInstanceRepository'
+import { WorkflowTemplateRepository } from './repository/WorkflowTemplateRepository'
+import { WorkflowService } from './services/WorkflowService'
+
+export const WORKFLOW_PROTOCOL_URI = 'https://didcomm.org/workflow/1.0'
+export const WORKFLOW_ROLES = ['processor', 'coordinator'] as const
+
+export class WorkflowModule implements Module {
+  public readonly api = WorkflowApi
+  public readonly config: WorkflowModuleConfig
+
+  public constructor(options?: WorkflowModuleConfigOptions) {
+    this.config = new WorkflowModuleConfig(options)
+  }
+
+  public register(dependencyManager: DependencyManager) {
+    dependencyManager.resolve(AgentConfig).logger.info('Registering WorkflowModule')
+    dependencyManager.registerInstance(WorkflowModuleConfig, this.config)
+
+    dependencyManager.registerSingleton(WorkflowTemplateRepository)
+    dependencyManager.registerSingleton(WorkflowInstanceRepository)
+    dependencyManager.registerSingleton(WorkflowService)
+    dependencyManager.registerSingleton(WorkflowApi)
+
+    dependencyManager.registerSingleton(PublishTemplateHandler)
+    dependencyManager.registerSingleton(StartHandler)
+    dependencyManager.registerSingleton(AdvanceHandler)
+    dependencyManager.registerSingleton(StatusHandler)
+    dependencyManager.registerSingleton(ProblemReportHandler)
+    dependencyManager.registerSingleton(PauseHandler)
+    dependencyManager.registerSingleton(ResumeHandler)
+    dependencyManager.registerSingleton(CancelHandler)
+    dependencyManager.registerSingleton(CompleteHandler)
+  }
+
+  public async initialize(agentContext: AgentContext): Promise<void> {
+    const dm = agentContext.dependencyManager
+    const logger = dm.resolve(AgentConfig).logger
+    const features = dm.resolve(DidCommFeatureRegistry)
+    const handlers = dm.resolve(DidCommMessageHandlerRegistry)
+    logger.info('Initializing WorkflowModule - registering workflow/1.0 protocol')
+    try {
+      features.register(new DidCommProtocol({ id: WORKFLOW_PROTOCOL_URI, roles: [...WORKFLOW_ROLES] }))
+    } catch {}
+    handlers.registerMessageHandler(dm.resolve(PublishTemplateHandler))
+    handlers.registerMessageHandler(dm.resolve(StartHandler))
+    handlers.registerMessageHandler(dm.resolve(AdvanceHandler))
+    handlers.registerMessageHandler(dm.resolve(StatusHandler))
+    handlers.registerMessageHandler(dm.resolve(ProblemReportHandler))
+    handlers.registerMessageHandler(dm.resolve(PauseHandler))
+    handlers.registerMessageHandler(dm.resolve(ResumeHandler))
+    handlers.registerMessageHandler(dm.resolve(CancelHandler))
+    handlers.registerMessageHandler(dm.resolve(CompleteHandler))
+    // Inbound mapping: credentials/proofs → workflow events
+    const events = dm.resolve(EventEmitter)
+    const service = dm.resolve(WorkflowService)
+    events.on<DidCommCredentialStateChangedEvent>(
+      DidCommCredentialEventTypes.DidCommCredentialStateChanged,
+      async (e) => {
+        const rec = e.payload.credentialExchangeRecord
+        const connId = rec.connectionId
+        if (!connId) return
+        if (rec.state === DidCommCredentialState.RequestReceived) {
+          await service.autoAdvanceByConnection(agentContext, connId, 'request_received')
+        } else if (rec.state === DidCommCredentialState.Done) {
+          await service.autoAdvanceByConnection(agentContext, connId, 'issued_ack')
+        }
+      }
+    )
+    events.on<DidCommProofStateChangedEvent>(DidCommProofEventTypes.ProofStateChanged, async (e) => {
+      const rec = e.payload.proofRecord
+      const connId = rec.connectionId
+      if (!connId) return
+      if (rec.state === DidCommProofState.PresentationReceived) {
+        await service.autoAdvanceByConnection(agentContext, connId, 'presentation_received')
+      } else if (rec.state === DidCommProofState.Done) {
+        await service.autoAdvanceByConnection(agentContext, connId, 'verified_ack')
+      }
+    })
+  }
+}

packages/workflow/src/WorkflowModuleConfig.ts

@@ -0,0 +1,22 @@
+export type GuardEngine = 'jmespath' | 'cel' | 'js'
+
+export interface WorkflowModuleConfigOptions {
+  guardEngine?: GuardEngine
+  autoReturnExistingOnSingleton?: boolean
+  actionTimeoutMs?: number
+  enableProblemReport?: boolean
+}
+
+export class WorkflowModuleConfig {
+  public readonly guardEngine: GuardEngine
+  public readonly autoReturnExistingOnSingleton: boolean
+  public readonly actionTimeoutMs: number
+  public readonly enableProblemReport: boolean
+
+  public constructor(options?: WorkflowModuleConfigOptions) {
+    this.guardEngine = options?.guardEngine ?? 'jmespath'
+    this.autoReturnExistingOnSingleton = options?.autoReturnExistingOnSingleton ?? true
+    this.actionTimeoutMs = options?.actionTimeoutMs ?? 15000
+    this.enableProblemReport = options?.enableProblemReport ?? true
+  }
+}