@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/lib/definition-grant.ts

@@ -0,0 +1,211 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import { hasFeature } from '@open-mercato/shared/security/features'
+import {
+  normalizeFeatureList,
+  provisionExecutionPrincipal,
+  resolveExecutionPrincipalUserId,
+} from '../../auth/lib/executionPrincipal'
+
+/**
+ * Workflow execution identity (`grantedFeatures`).
+ *
+ * A workflow needs an acting user to write anything: `executeUpdateEntity`
+ * refuses without one and then checks that user's LIVE features against the
+ * command's `requiredFeatures`. Historically that user was whoever started the
+ * run — so a workflow started by an admin silently ran with admin powers, and an
+ * event-triggered run (whose `initiatedBy` is `trigger:<id>`) had no actor at
+ * all and could not write.
+ *
+ * A definition may instead declare its own least-privilege grant. Two rules,
+ * both deliberate:
+ *
+ *  - **No grant ⇒ today's behaviour, byte-for-byte.** The run borrows the
+ *    starting user's identity. The feature is additive and opt-in; every
+ *    pre-existing definition is unaffected.
+ *  - **A grant ⇒ the run ALWAYS acts as its own principal**, regardless of who
+ *    started it. That is the point: the grant is a ceiling, not a floor, so a
+ *    run started by an admin must not gain the admin's powers. It also gives the
+ *    no-actor triggered case a real identity.
+ *
+ * The grant lives on the definition ROW (a real column), so it is per version:
+ * publishing a new version mints a new row, hence a new principal, hence a
+ * re-authorised grant.
+ */
+
+/** The `auth` execution-principal namespace this module owns. */
+export function workflowPrincipalKey(definitionId: string): string {
+  return `workflow:${definitionId}`
+}
+
+export function normalizeGrantedFeatures(value: unknown): string[] {
+  return normalizeFeatureList(value)
+}
+
+export type WorkflowDefinitionGrantLike = {
+  id: string
+  tenantId: string
+  organizationId: string
+  workflowId?: string
+  grantedFeatures?: string[] | null
+}
+
+export function definitionDeclaresGrant(definition: WorkflowDefinitionGrantLike | null | undefined): boolean {
+  return normalizeGrantedFeatures(definition?.grantedFeatures).length > 0
+}
+
+/**
+ * The features in `requested` that `granted` does not cover.
+ *
+ * Wildcard-aware on purpose: `workflows.*` in the author's own grants satisfies
+ * `workflows.definitions.view` in the request, and a plain `includes()` would
+ * refuse a grant the author demonstrably holds. Uses the shared matcher so this
+ * agrees with every other ACL decision in the platform.
+ */
+export function findUngrantableFeatures(requested: string[], granted: string[]): string[] {
+  return normalizeGrantedFeatures(requested).filter((feature) => !hasFeature(granted, feature))
+}
+
+export const WORKFLOW_GRANT_FEATURE = 'workflows.definitions.grant_features'
+
+export type WorkflowGrantAuthorizationFailure = {
+  status: number
+  body: {
+    error: string
+    code: 'WORKFLOW_GRANT_FEATURE_REQUIRED' | 'WORKFLOW_GRANT_EXCEEDS_GRANTOR_FEATURES'
+    details?: { missingFeatures: string[] }
+  }
+}
+
+type RbacServiceLike = {
+  userHasAllFeatures: (
+    userId: string,
+    features: string[],
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<boolean>
+  getGrantedFeatures?: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<string[]>
+}
+
+/**
+ * Authorises a change to a definition's grant. Returns null when the change is
+ * allowed, otherwise the response body/status the route should return.
+ *
+ * Two gates, both required:
+ *  1. `workflows.definitions.grant_features` — declaring an execution identity
+ *     is not implied by ordinary `definitions.edit`.
+ *  2. The requested grant must be a SUBSET of the saving user's own current
+ *     features. `userHasAllFeatures` is the authority (it is the same primitive
+ *     every other route uses, so it honours super-admin, wildcards, module
+ *     enablement and organization visibility identically); the missing-feature
+ *     list in the error body is derived with the shared wildcard-aware matcher,
+ *     never `includes()`.
+ *
+ * A no-op change (`requested` deep-equals `current`) is not a change and needs
+ * neither gate — otherwise every ordinary metadata save of a granted definition
+ * would demand the grant feature. Callers that mint a NEW principal from an
+ * existing grant (publish) MUST pass `current: []` so the copy is re-authorised.
+ */
+export async function authorizeWorkflowGrantChange(
+  rbacService: RbacServiceLike,
+  params: {
+    userId: string
+    scope: { tenantId: string | null; organizationId: string | null }
+    requested: string[]
+    current: string[]
+  },
+): Promise<WorkflowGrantAuthorizationFailure | null> {
+  const requested = normalizeGrantedFeatures(params.requested)
+  const current = normalizeGrantedFeatures(params.current)
+  if (requested.length === current.length && requested.every((feature, index) => feature === current[index])) {
+    return null
+  }
+
+  const mayGrant = await rbacService.userHasAllFeatures(params.userId, [WORKFLOW_GRANT_FEATURE], params.scope)
+  if (!mayGrant) {
+    return {
+      status: 403,
+      body: { error: 'Insufficient permissions', code: 'WORKFLOW_GRANT_FEATURE_REQUIRED' },
+    }
+  }
+
+  if (!requested.length) return null
+
+  const withinOwnGrants = await rbacService.userHasAllFeatures(params.userId, requested, params.scope)
+  if (withinOwnGrants) return null
+
+  const granted = rbacService.getGrantedFeatures
+    ? await rbacService.getGrantedFeatures(params.userId, params.scope)
+    : []
+  return {
+    status: 403,
+    body: {
+      error: 'Insufficient permissions',
+      code: 'WORKFLOW_GRANT_EXCEEDS_GRANTOR_FEATURES',
+      details: { missingFeatures: findUngrantableFeatures(requested, granted) },
+    },
+  }
+}
+
+export class WorkflowExecutionPrincipalMissingError extends Error {
+  readonly code = 'EXECUTION_PRINCIPAL_MISSING'
+  constructor(public readonly definitionId: string) {
+    super(
+      `[internal] workflow definition ${definitionId} declares granted features but its execution ` +
+        `principal is not provisioned; refusing to fall back to the starting user`,
+    )
+    this.name = 'WorkflowExecutionPrincipalMissingError'
+  }
+}
+
+/**
+ * Provisions (idempotently) the definition's execution principal and re-scopes
+ * its role ACL to exactly the declared grant — on every create, update and
+ * publish, so an over-granted principal self-heals instead of lingering.
+ *
+ * A definition that never declared a grant provisions nothing (the opt-in stays
+ * opt-in), but CLEARING a grant re-scopes the existing principal to no features
+ * rather than leaving the old ACL behind for anything that still resolves it.
+ */
+export async function syncWorkflowDefinitionPrincipal(
+  container: AwilixContainer,
+  definition: WorkflowDefinitionGrantLike,
+  options?: { previousFeatures?: string[] | null },
+): Promise<void> {
+  const features = normalizeGrantedFeatures(definition.grantedFeatures)
+  const previous = normalizeGrantedFeatures(options?.previousFeatures)
+  // Nothing declared and nothing to revoke ⇒ no principal, no writes at all.
+  if (!features.length && !previous.length) return
+  await provisionExecutionPrincipal(
+    container,
+    { tenantId: definition.tenantId, organizationId: definition.organizationId },
+    {
+      principalKey: workflowPrincipalKey(definition.id),
+      displayName: `Workflow ${definition.workflowId ?? definition.id}`,
+      features,
+    },
+  )
+}
+
+/**
+ * The user id a run of `definition` acts as.
+ *
+ * Fails CLOSED: a definition that declares a grant whose principal cannot be
+ * resolved throws rather than silently reverting to `fallbackUserId`, because
+ * that fallback is precisely the escalation the grant exists to prevent.
+ */
+export async function resolveWorkflowDefinitionExecutionUserId(
+  em: EntityManager,
+  definition: WorkflowDefinitionGrantLike | null | undefined,
+  fallbackUserId: string | null | undefined,
+): Promise<string | null> {
+  if (!definition || !definitionDeclaresGrant(definition)) return fallbackUserId ?? null
+  const userId = await resolveExecutionPrincipalUserId(em, workflowPrincipalKey(definition.id), {
+    tenantId: definition.tenantId,
+    organizationId: definition.organizationId,
+  })
+  if (!userId) throw new WorkflowExecutionPrincipalMissingError(definition.id)
+  return userId
+}

package/src/modules/workflows/lib/definition-json-locations.ts

@@ -0,0 +1,226 @@
+/**
+ * Workflows Module — Code-view issue locations (spec section 2.2, stage 2)
+ *
+ * Stage 2 is *"two-way live sync with error squiggles that highlight the
+ * corresponding node"*. `collectValidationIssues` already carries `nodeId` /
+ * `edgeId` on every issue, so the missing half is purely positional: WHERE in
+ * the JSON text does the step or transition with that id live.
+ *
+ * The scan is a minimal JSON tokenizer rather than a regex over
+ * `"id": "<value>"`, because the author is editing free text: a step id can
+ * appear inside a `{{context.*}}` template, inside a transition's
+ * `fromStepId`, or inside a note's markdown, and a regex would happily point
+ * the squiggle at any of them. Tracking the container path is the only way to
+ * mean "the element of `steps` at index i".
+ *
+ * PURE: no ORM, no DI, no React.
+ */
+
+export type JsonLineRange = {
+  /** 1-based, inclusive. */
+  startLine: number
+  /** 1-based, inclusive. */
+  endLine: number
+}
+
+export type DefinitionJsonLocations = {
+  steps: Map<string, JsonLineRange>
+  transitions: Map<string, JsonLineRange>
+}
+
+type ArrayElementRange = { index: number } & JsonLineRange
+
+/**
+ * Line ranges of the elements of the top-level `steps` and `transitions`
+ * arrays, by ARRAY INDEX. Ids are attached separately from the parsed document,
+ * so a malformed id (missing, non-string, duplicated) cannot desynchronise the
+ * scan.
+ */
+function scanTopLevelArrayElements(text: string): {
+  steps: ArrayElementRange[]
+  transitions: ArrayElementRange[]
+} {
+  const steps: ArrayElementRange[] = []
+  const transitions: ArrayElementRange[] = []
+
+  let line = 1
+  let inString = false
+  let escaped = false
+  // Depth 1 is the document object. A tracked array's elements sit at depth 3.
+  let depth = 0
+  let pendingKey: string | null = null
+  let currentStringStart = -1
+  let trackedArray: 'steps' | 'transitions' | null = null
+  let trackedArrayDepth = -1
+  let elementIndex = 0
+  let elementStartLine = -1
+  let elementDepth = -1
+
+  for (let position = 0; position < text.length; position += 1) {
+    const char = text[position]
+
+    if (char === '\n') {
+      line += 1
+      // A newline cannot appear inside a valid JSON string literal, so this
+      // also self-heals if the author is mid-edit.
+      inString = false
+      escaped = false
+      continue
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (char === '\\') {
+        escaped = true
+      } else if (char === '"') {
+        inString = false
+        const literal = text.slice(currentStringStart, position)
+        // A string immediately followed by `:` is an object key.
+        let lookahead = position + 1
+        while (lookahead < text.length && /\s/.test(text[lookahead])) lookahead += 1
+        if (text[lookahead] === ':') pendingKey = literal
+      }
+      continue
+    }
+
+    if (char === '"') {
+      inString = true
+      currentStringStart = position + 1
+      continue
+    }
+
+    if (char === '[') {
+      if (depth === 1 && (pendingKey === 'steps' || pendingKey === 'transitions')) {
+        trackedArray = pendingKey
+        trackedArrayDepth = depth
+        elementIndex = 0
+      }
+      depth += 1
+      pendingKey = null
+      continue
+    }
+
+    if (char === '{') {
+      if (trackedArray && depth === trackedArrayDepth + 1 && elementStartLine === -1) {
+        elementStartLine = line
+        elementDepth = depth
+      }
+      depth += 1
+      pendingKey = null
+      continue
+    }
+
+    if (char === '}') {
+      depth -= 1
+      if (trackedArray && elementStartLine !== -1 && depth === elementDepth) {
+        const range: ArrayElementRange = { index: elementIndex, startLine: elementStartLine, endLine: line }
+        if (trackedArray === 'steps') steps.push(range)
+        else transitions.push(range)
+        elementIndex += 1
+        elementStartLine = -1
+        elementDepth = -1
+      }
+      pendingKey = null
+      continue
+    }
+
+    if (char === ']') {
+      depth -= 1
+      if (trackedArray && depth === trackedArrayDepth) {
+        trackedArray = null
+        trackedArrayDepth = -1
+        elementStartLine = -1
+        elementDepth = -1
+      }
+      pendingKey = null
+      continue
+    }
+  }
+
+  return { steps, transitions }
+}
+
+function readIdsAt(parsed: unknown, key: 'steps' | 'transitions', idField: string): Array<string | null> {
+  if (!parsed || typeof parsed !== 'object') return []
+  const collection = (parsed as Record<string, unknown>)[key]
+  if (!Array.isArray(collection)) return []
+  return collection.map((element) => {
+    if (!element || typeof element !== 'object') return null
+    const value = (element as Record<string, unknown>)[idField]
+    return typeof value === 'string' && value.length > 0 ? value : null
+  })
+}
+
+/**
+ * Map every step id and transition id in `text` to its line range.
+ *
+ * `parsed` must be the result of `JSON.parse(text)`; the caller already has it
+ * (it cannot decide whether to apply an edit without parsing) and passing it in
+ * keeps this function from parsing the same text twice.
+ */
+export function locateDefinitionJsonEntities(text: string, parsed: unknown): DefinitionJsonLocations {
+  const scanned = scanTopLevelArrayElements(text)
+  const stepIds = readIdsAt(parsed, 'steps', 'stepId')
+  const transitionIds = readIdsAt(parsed, 'transitions', 'transitionId')
+
+  const steps = new Map<string, JsonLineRange>()
+  for (const element of scanned.steps) {
+    const id = stepIds[element.index]
+    // First occurrence wins: a duplicated id is itself a validation error, and
+    // pointing at the first one is more useful than at an arbitrary later one.
+    if (id && !steps.has(id)) steps.set(id, { startLine: element.startLine, endLine: element.endLine })
+  }
+
+  const transitions = new Map<string, JsonLineRange>()
+  for (const element of scanned.transitions) {
+    const id = transitionIds[element.index]
+    if (id && !transitions.has(id)) {
+      transitions.set(id, { startLine: element.startLine, endLine: element.endLine })
+    }
+  }
+
+  return { steps, transitions }
+}
+
+export type LocatedIssue = {
+  issueId: string
+  severity: 'error' | 'warning'
+  line: number
+}
+
+/**
+ * Project issues onto lines. An issue whose node/edge is not in the text (or
+ * which names neither) is simply not located — the issue list still shows it,
+ * it just gets no gutter marker rather than a marker on a wrong line.
+ */
+export function locateIssues(
+  issues: Array<{ id: string; severity: 'error' | 'warning'; nodeId?: string; edgeId?: string }>,
+  locations: DefinitionJsonLocations,
+): LocatedIssue[] {
+  const located: LocatedIssue[] = []
+  for (const issue of issues) {
+    const range = issue.nodeId
+      ? locations.steps.get(issue.nodeId)
+      : issue.edgeId
+        ? locations.transitions.get(issue.edgeId)
+        : undefined
+    if (!range) continue
+    located.push({ issueId: issue.id, severity: issue.severity, line: range.startLine })
+  }
+  return located
+}
+
+/**
+ * Highest severity per line, so a line carrying both an error and a warning
+ * paints as an error. Errors sort before warnings for the same reason.
+ */
+export function severityByLine(located: LocatedIssue[]): Map<number, 'error' | 'warning'> {
+  const byLine = new Map<number, 'error' | 'warning'>()
+  for (const issue of located) {
+    const existing = byLine.get(issue.line)
+    if (existing === 'error') continue
+    byLine.set(issue.line, issue.severity)
+  }
+  return byLine
+}

package/src/modules/workflows/lib/definition-payload.ts

@@ -0,0 +1,81 @@
+/**
+ * Pure payload builders for the visual editor's save and draft round trips.
+ *
+ * The editor rebuilds the definition from the graph and rebuilds metadata from
+ * three edited fields on every save, so anything it does not explicitly carry
+ * (the declared contextSchema, the sub-workflow io port contract, future
+ * metadata.editor.* keys) would be silently dropped. These helpers centralize
+ * that assembly: the definition payload re-attaches triggers, contextSchema,
+ * and io next to the graph output, and the metadata payload spreads the
+ * metadata object loaded from the server before overlaying the edited fields
+ * so unknown keys survive load → save.
+ */
+
+import type {
+  WorkflowContextSchema,
+  WorkflowDefinitionData,
+  WorkflowDefinitionTrigger,
+  WorkflowIoContract,
+} from '../data/entities'
+import type { WorkflowErrorHandlerConfig } from '../data/validators'
+import { writeEditorAnnotations, type WorkflowEditorAnnotations } from './editor-annotations'
+import { resolveRequiredEngineVersion, type EngineVersionedDefinition } from './engine-version'
+import type { WorkflowInterpolationMode } from './interpolation-pipeline'
+
+export type DefinitionPayloadInput = {
+  graphDefinition: WorkflowDefinitionData
+  triggers: WorkflowDefinitionTrigger[]
+  contextSchema?: WorkflowContextSchema | null
+  io?: WorkflowIoContract | null
+  interpolation?: WorkflowInterpolationMode | null
+  errorHandler?: WorkflowErrorHandlerConfig | null
+}
+
+export function buildDefinitionPayload({ graphDefinition, triggers, contextSchema, io, interpolation, errorHandler }: DefinitionPayloadInput): WorkflowDefinitionData {
+  return {
+    ...graphDefinition,
+    triggers: triggers.length > 0 ? triggers : undefined,
+    contextSchema: contextSchema ?? undefined,
+    io: io ?? undefined,
+    interpolation: interpolation ?? undefined,
+    errorHandler: errorHandler ?? undefined,
+  }
+}
+
+export type MetadataPayloadInput = {
+  loadedMetadata: Record<string, unknown> | null
+  tags: string[]
+  category: string
+  icon: string
+  /**
+   * Definition being saved. Used to stamp `minEngineVersion` when the graph
+   * contains a step or transition capability older engines cannot execute
+   * (spec section 5.8).
+   * Definitions that need nothing beyond the baseline keep no such key, so
+   * saving an existing workflow stays byte-identical.
+   */
+  definition?: EngineVersionedDefinition | null
+  /**
+   * Sticky notes and groups (spec section 4.5). The canvas owns them as nodes,
+   * so they are derived back out of the node array on every persistence path and
+   * written to `metadata.editor.annotations` here. Omitting the field leaves
+   * whatever the loaded metadata carried untouched, which is what keeps callers
+   * that never render a canvas (tests, migrations) byte-compatible.
+   */
+  annotations?: WorkflowEditorAnnotations | null
+}
+
+export function buildMetadataPayload({ loadedMetadata, tags, category, icon, definition, annotations }: MetadataPayloadInput): Record<string, unknown> | null {
+  const base = annotations === undefined ? loadedMetadata : writeEditorAnnotations(loadedMetadata, annotations)
+  const metadata: Record<string, unknown> = { ...(base ?? {}) }
+  if (category) metadata.category = category
+  else delete metadata.category
+  if (tags.length > 0) metadata.tags = [...tags]
+  else delete metadata.tags
+  if (icon) metadata.icon = icon
+  else delete metadata.icon
+  const requiredEngineVersion = resolveRequiredEngineVersion(definition ?? null)
+  if (requiredEngineVersion > 1) metadata.minEngineVersion = requiredEngineVersion
+  else delete metadata.minEngineVersion
+  return Object.keys(metadata).length > 0 ? metadata : null
+}

package/src/modules/workflows/lib/draft-restore.ts

@@ -0,0 +1,72 @@
+/**
+ * Draft restore decision helpers (spec §4.7 save model, Step 8.3).
+ *
+ * Pure logic behind the visual editor's per-user draft layer: whether a
+ * definition id can have a server draft at all, a stable (key-order
+ * insensitive) serialization used to compare editor state against persisted
+ * drafts, and the restore-banner decision (draft exists? differs from the
+ * loaded definition? was it based on an older definition version?).
+ */
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export function isServerDraftEligible(definitionId: string | null | undefined): boolean {
+  if (!definitionId) return false
+  return UUID_PATTERN.test(definitionId)
+}
+
+function stableSerializeValue(value: unknown): string | undefined {
+  if (value === undefined) return undefined
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) {
+    const items = value.map((item) => stableSerializeValue(item) ?? 'null')
+    return `[${items.join(',')}]`
+  }
+  const record = value as Record<string, unknown>
+  const entries = Object.keys(record)
+    .sort((left, right) => left.localeCompare(right))
+    .map((key) => {
+      const serialized = stableSerializeValue(record[key])
+      return serialized === undefined ? undefined : `${JSON.stringify(key)}:${serialized}`
+    })
+    .filter((entry): entry is string => entry !== undefined)
+  return `{${entries.join(',')}}`
+}
+
+export function stableSerializeDefinition(value: unknown): string {
+  return stableSerializeValue(value) ?? 'null'
+}
+
+export type DraftRestoreDecision =
+  | { offerRestore: false }
+  | { offerRestore: true; baseMismatch: boolean }
+
+export type DraftRestoreInput = {
+  draftDefinition: unknown
+  draftBaseUpdatedAt: string | null
+  loadedDefinition: unknown
+  definitionUpdatedAt: string | null
+}
+
+function timestampsDiffer(base: string | null, current: string | null): boolean {
+  if (!base || !current) return false
+  const baseMs = Date.parse(base)
+  const currentMs = Date.parse(current)
+  if (Number.isNaN(baseMs) || Number.isNaN(currentMs)) return base !== current
+  return baseMs !== currentMs
+}
+
+export function decideDraftRestore(input: DraftRestoreInput): DraftRestoreDecision {
+  if (input.draftDefinition === null || input.draftDefinition === undefined) {
+    return { offerRestore: false }
+  }
+  const draftSerialized = stableSerializeDefinition(input.draftDefinition)
+  const loadedSerialized = stableSerializeDefinition(input.loadedDefinition)
+  if (draftSerialized === loadedSerialized) {
+    return { offerRestore: false }
+  }
+  return {
+    offerRestore: true,
+    baseMismatch: timestampsDiffer(input.draftBaseUpdatedAt, input.definitionUpdatedAt),
+  }
+}