Sprint 216: Nodes Full Integration — merge feature/CODUX-216-nodes-full-integration into dev

[numnx]

🚀 Sprint Completion: Sprint 216 · Nodes Full Integration

Automated sprint completion PR opened by Code UX.

📋 Summary

Sprint: Sprint 216 · Nodes Full Integration Tasks: 23/23 completed

🧭 Planning

Planning provider	Codex CLI
Planning model	gpt-5.6-luna

Metric	Value
Input tokens	73,347
Cached input tokens	301,312
Output tokens	17,629
Total tokens	392,288
Invocations	1
Tool calls	6
Active time	5m 28s

Included usage estimate (subscription/local login): $0.21

🎯 Original Sprint Prompt

Implementation Plan

Status: Proposed architecture and implementation plan. This document describes planned work, not currently shipped capability.

Executive Summary

Code UX has a useful backend node-flow foundation, but it is not yet a complete n8n-style automation platform. Agents can create and run simple JSON-defined flows through MCP, but they cannot yet generate safely sandboxed custom-code nodes, resolve reusable encrypted credentials, build rich branching workflows, or publish production-ready automations entirely from natural language.

The recommended direction is to turn the existing node-flow foundation into a versioned automation control plane with:

• one canonical graph shared by agents, backend, and dashboard
• a typed node-definition registry
• encrypted and externally managed credentials
• a durable execution engine
• isolated custom-code node builds
• an agent authoring and verification loop
• explicit governance for external side effects
• a deployment model that works locally and later in authenticated headless-server mode

The correct implementation order is:

1. Canonical contracts and encrypted credentials.
2. Durable and version-pinned execution.
3. Hardened built-in integrations.
4. Sandboxed custom-code nodes.
5. Autonomous agent construction and publishing.
6. Authenticated headless-server operation.

This ordering ensures that agents build on enforceable security and execution guarantees rather than generating workflows the platform cannot safely operate.

1. Current State

1.1 What Already Works

Capability	Current state
Persistence	Project-scoped flows, immutable version snapshots, runs, node runs, and agent attachments exist in SQLite.
MCP authoring	Project-manager agents with manage_node_flows access can list, create, update, validate, run, and delete flows.
Scheduling	Saved flows can be selected by scheduler entries and executed when due.
Basic execution	Six runtime types work: input, set_fields, template, provider_prompt, http_request, and output.
External requests	HTTP nodes support common methods, headers, query parameters, request bodies, timeouts, and response-path extraction.
AI processing	provider_prompt nodes invoke configured Code UX CLI providers.
Failure handling	Node failures can stop descendants or continue through continueOnError.
Observability	Parent and externally observable node invocations are persisted alongside run and node-run records.
Focused validation	The focused node-flow, scheduling, MCP, repository, dashboard, and validation suites currently pass.

Relevant foundations include:

• src/contracts/node-flow-types.ts
• src/domain/node-flows/node-flow-validation.ts
• src/services/node-flow-runtime-service.ts
• src/services/node-flow-service.ts
• src/mcp/management/node-flow-actions.ts
• src/repositories/node-flow-repository.ts
• src/services/scheduler-service.ts

1.2 Material Gaps

Gap	Impact
No custom-code runtime	Agents cannot write and execute TypeScript or JavaScript nodes.
No credential vault	secretRef is only a string/widget type and is never resolved.
No application encryption	Existing SQLite secret storage is not encrypted by Code UX.
Split graph models	The visible Nodes canvas and backend node-flow runtime use different contracts.
Local-only Nodes UI	The current /nodes page persists to browser localStorage, not the backend node-flow tables.
Feature flagged	Nodes are automatically available in development but disabled by default in production builds unless explicitly enabled.
No real attached-flow skill	Agent-flow attachment records exist, but no runtime consumes them to expose callable flow tools to the attached agent.
No branching or iteration	There are no executable condition, switch, foreach, loop, merge, delay, or approval nodes.
Sequential execution only	Topological execution is sequential, with no controlled parallel fan-out or durable work queue.
Weak version pinning	Scheduler flowVersion is recorded as trigger metadata, but runtime still loads the latest saved flow.
HTTP security gaps	The HTTP node has no private-network blocking, egress policy, response-size limit, retry policy, or rate limiting.
No OAuth lifecycle	There is no authorization-code flow, token refresh, expiry handling, revocation, or credential health check.
Limited semantic validation	Graph shape is validated, but most node configuration is validated only during execution.
No side-effect guarantees	Email sends and other mutations would lack outbox, deduplication, approval, and idempotency controls.

1.3 Current Capability Conclusion

Agents are not yet fully capable of creating complex, secure, repeatable n8n-style automations. They can author and execute a narrow built-in graph through MCP, including generic HTTP requests and provider prompts. They cannot yet safely create arbitrary code nodes, manage reusable encrypted credentials, execute rich workflow control flow, or reliably govern external side effects.

2. Target Architecture

flowchart TD
  U[User automation request] --> A[Automation Builder Agent]
  A --> C[Node Definition Catalog]
  A --> D[Workflow Draft API]
  D --> V[Structural and Policy Validation]
  A --> G[Custom Node Generator]
  G --> B[Isolated Build and Test Pipeline]
  B --> P[Immutable Node Artifact]
  V --> R[Review and Publish]
  P --> R

  R --> F[(Published Flow Version)]
  F --> T[Manual / Schedule / Webhook Trigger]
  T --> Q[Durable Run Queue]
  Q --> O[Workflow Orchestrator]

  O --> BI[Built-in Node Executor]
  O --> CX[Custom Node Sandbox]
  O --> AP[Approval and Outbox Service]

  BI --> CB[Credential Broker]
  CX --> CB
  CB --> VS[External Vault / Encrypted Local Store]
  VS --> KP[KMS / OS Keychain / Key Provider]

  BI --> EG[Controlled Egress Proxy]
  CX --> EG
  EG --> EXT[External APIs]

Loading

The design separates four planes:

1. Management plane: drafts, graph editing, validation, credentials, publishing, and versions.
2. Execution plane: queues, runs, retries, node attempts, cancellation, and recovery.
3. Build plane: custom-node source, compilation, tests, policy scans, and immutable artifacts.
4. Security plane: credentials, key management, capability grants, egress control, and audit.

3. Canonical Workflow Contract

The first architectural change must eliminate the two competing graph formats.

3.1 Graph v2

Extend the flow graph with:

• schemaVersion
• flow-level input and output JSON Schemas
• stable node-definition references
• typed ports
• credential bindings
• retry and timeout policies
• side-effect classification
• capability declarations
• disabled state
• immutable publication metadata

A canonical node should resemble:

interface AutomationNode {
  id: string;
  definition: {
    type: string;
    version: string;
  };
  title: string;
  position: { x: number; y: number };
  config: JsonObject;
  credentialBindings: Record<string, string>;
  retryPolicy?: RetryPolicy;
  timeoutMs?: number;
  continueOnError?: boolean;
  disabled?: boolean;
}

Secrets and custom-node source code must never be stored in the graph.

3.2 Typed Edges

Edges need:

• source node and output port
• target node and input port
• optional branch condition
• optional mapping or expression
• branch priority
• disabled state

Arbitrary graph cycles should remain prohibited. Repetition should be represented by explicit foreach, loop, or subflow nodes with bounded execution semantics.

3.3 Compatibility and Migration

Introduce deterministic graph migrators:

local canvas v1 -> canonical flow v2
backend flow v1 -> canonical flow v2

Existing flows remain readable. Migration creates a new immutable version and retains the original snapshot for rollback.

4. Node-Definition Registry

Every executable node type should come from a registry rather than a runtime string allowlist.

4.1 Node Manifest

Each definition needs:

• type and semantic version
• name, description, category, and icon reference
• execution kind: builtin, custom, or subflow
• configuration JSON Schema
• UI schema
• input and output port schemas
• credential requirements
• requested capabilities
• side-effect classification
• retry safety and idempotency declaration
• default timeout and resource limits
• documentation reference
• deprecation and replacement metadata

Example credential requirement:

{
  "slot": "emailAccount",
  "credentialTypes": ["smtp", "gmail_oauth", "microsoft_oauth"],
  "capabilities": ["email.send"],
  "required": true
}

4.2 Initial Built-in Catalog

The first executable catalog should include:

• Manual Trigger
• Schedule Trigger
• Webhook Trigger
• Input
• Set Fields
• Template
• HTTP Request
• AI Prompt
• Condition
• Switch
• Foreach
• Merge
• Delay
• Approval
• Email Draft
• Email Send
• Output
• Execute Subflow
• Custom Code

The palette, inspector, MCP agent descriptions, validation, and runtime must consume the same registry.

5. Credential and Encryption Architecture

5.1 Storage Hierarchy

Use this priority:

1. Headless production: external Vault or managed secret store.
2. Desktop: operating-system credential storage.
3. Offline/self-hosted fallback: envelope-encrypted SQLite.
4. Missing secure backend: fail closed.

The database must never contain the root encryption key.

For desktop mode, Electron safeStorage can use macOS Keychain, Windows DPAPI, or Linux Secret Service/keyring backends. Code UX must detect and reject insecure plaintext-style fallback backends.

For server mode, use envelope encryption with a KMS-managed key-encryption key or store credential values entirely in an external secret manager and retain only references in SQLite.

5.2 Provider Abstractions

Implement separate secret-store and key-provider interfaces:

interface SecretStore {
  putSecret(...args: PutSecretArgs): Promise<SecretReference>;
  resolveSecret(...args: ResolveSecretArgs): Promise<SecretMaterial>;
  deleteSecret(...args: DeleteSecretArgs): Promise<void>;
  rotateSecret(...args: RotateSecretArgs): Promise<void>;
}

interface KeyProvider {
  wrapDataKey(...args: WrapDataKeyArgs): Promise<WrappedKey>;
  unwrapDataKey(...args: UnwrapDataKeyArgs): Promise<Buffer>;
  getActiveKeyVersion(): Promise<string>;
  healthCheck(): Promise<KeyProviderHealth>;
}

Initial providers:

• ExternalVaultSecretStore
• EncryptedSqliteSecretStore
• ElectronSafeStorageKeyProvider
• MountedKeyFileProvider
• VaultTransitKeyProvider
• deployment-specific cloud KMS providers

5.3 Envelope Encryption

For every local credential:

1. Generate a unique random 256-bit data-encryption key.
2. Encrypt secret JSON using AES-256-GCM.
3. Generate a fresh 96-bit nonce.
4. Bind immutable credential and workspace identifiers as authenticated additional data.
5. Wrap the data key using the configured key-encryption key.
6. Store ciphertext, nonce, authentication tag, wrapped data key, algorithm, key ID, and key version.
7. Clear plaintext buffers as soon as practical.
8. Never reuse a nonce with the same data key.

5.4 Credential Data Model

Add:

• automation_credentials
• automation_credential_bindings
• automation_credential_access_events
• automation_credential_rotations

Important fields include:

• workspace or installation owner
• project or global scope
• optional project ID
• credential type and schema version
• display metadata
• encrypted payload or external secret reference
• key provider, key ID, and version
• configured, expired, and revoked status
• last validation and last use timestamps
• creator and updater principal IDs for future server authorization

Global credentials should not automatically become available to every project. Promotion to global scope requires:

• explicit approval
• project-access policy or allowlist
• impact preview
• audit event
• optional re-encryption when cryptographic context changes

5.5 Credential UX

Credentials live outside the canvas in:

• a Project Credentials panel
• a Global Credential Center
• a flow-level Missing Credentials banner
• node credential-binding controls

Supported actions:

• create
• bind
• test
• rotate
• revoke
• replace
• promote to global
• restrict to selected projects

Secret fields are write-only. APIs return configuration state, never stored values:

{
  "configured": true,
  "status": "healthy",
  "lastValidatedAt": "2026-01-01T00:00:00.000Z",
  "fields": [
    { "id": "clientSecret", "configured": true }
  ]
}

5.6 OAuth Broker

Add a dedicated OAuth broker supporting:

• authorization code with PKCE
• encrypted state
• strict callback origins
• refresh-token rotation
• expiry tracking
• provider-specific scopes
• revocation
• reconnect flow
• credential health testing

Agents may request OAuth credential requirements, but only the user can complete authorization.

5.7 Runtime Credential Broker

At execution:

1. Validate node-to-credential binding and project access.
2. Validate the requested capability.
3. Retrieve or decrypt only the required credential.
4. Inject it into that one node executor.
5. Record a metadata-only access audit event.
6. Destroy the transient plaintext representation.
7. Return only redacted results.

Agents, prompts, graphs, and normal run inspection must never receive decrypted secrets.

6. Durable Runtime v2

6.1 Execution Lifecycle

Introduce:

queued
-> claimed
-> running
-> waiting_for_approval / waiting_for_retry
-> succeeded / failed / cancelled / timed_out

Every run pins an immutable published flow version. Schedules explicitly select either:

• follow latest published version, or
• remain pinned to a particular version

The existing behavior that records a requested flowVersion without executing that version must be corrected before production use.

6.2 Node Attempts

Add node_flow_node_attempts instead of overwriting one node-run record.

Each attempt stores:

• attempt number
• executor identity
• start and end timestamps
• redacted input and output
• failure classification
• retry decision
• invocation ID
• artifact digest
• credential IDs used, never values
• resource and usage telemetry

6.3 Branching and Iteration

Implement:

• conditional edges
• switch nodes
• foreach with bounded item count
• controlled parallelism
• merge strategies
• explicit loops with maximum iterations
• subflows
• skipped-branch persistence

Default safeguards:

• maximum nodes per flow
• maximum iterations
• maximum fan-out
• maximum run duration
• maximum JSON payload size
• maximum output size per node
• project-level concurrency quota

6.4 Retries and Idempotency

Retry policy includes:

• maximum attempts
• exponential backoff
• jitter
• retryable error classes
• retryable HTTP statuses
• maximum total retry window

Side-effect nodes need idempotency keys derived from:

published flow version + run + node + logical item

Email and other irreversible operations pass through an outbox table with a unique idempotency constraint.

6.5 Crash Recovery

Run and node-attempt claims use leases:

• claim owner
• lease expiry
• heartbeat
• recovery eligibility

After restart:

• deterministic nodes may be replayed
• idempotent external nodes may be retried
• unknown side-effect outcomes require attention
• approval-waiting runs remain paused
• no run silently starts twice

7. HTTP and External API Security

The existing HTTP node must be hardened before it receives credentials.

Required controls:

• HTTPS required by default
• explicit opt-in for plain HTTP
• URL credential rejection
• redirect limit and validation after every redirect
• DNS resolution before connect
• private, loopback, link-local, multicast, broadcast, and cloud-metadata blocking
• DNS rebinding protection
• destination host allowlists
• allowed-port policy
• request and response size limits
• content-type validation
• timeout and abort propagation
• rate limits
• retry policy
• restricted and normalized headers
• redaction based on key names and known secret values

Custom nodes should not receive unrestricted host networking. Outbound requests should pass through a controlled egress proxy or broker applying the same policy.

8. Custom-Code Node System

Agent-generated code must never execute inside the main Code UX process.

8.1 Custom Node Package

A generated node should contain:

.code-ux/nodes/<node-id>/
|- node.manifest.json
|- src/index.ts
|- tests/index.test.ts
|- fixtures/
|- package.json
`- lockfile

The SDK contract should remain small:

export async function execute(
  context: NodeExecutionContext,
  input: JsonValue,
  config: JsonObject,
): Promise<NodeExecutionResult>;

Context exposes only approved capabilities:

• structured logger with secret redaction
• bounded HTTP client
• credential slot access
• clock
• abort signal
• temporary storage
• emitted artifacts
• run and correlation IDs

It must not expose raw Docker, unrestricted filesystem, arbitrary subprocesses, host environment, or the complete project workspace.

8.2 Build Pipeline

A custom-node revision moves through:

draft -> validating -> passed/failed -> published -> deprecated

Validation includes:

• manifest schema
• TypeScript typecheck
• deterministic unit tests
• dependency lockfile verification
• vulnerability audit
• prohibited API scan
• capability-manifest comparison
• resource-limit test
• network-policy test
• secret-leak canary test
• fixture execution
• output-schema validation

Publishing produces an immutable, content-addressed artifact containing:

• source revision ID
• build digest
• runtime image digest
• dependency inventory
• validation report
• creating agent and invocation
• declared capabilities

8.3 Runtime Isolation

Custom nodes run in a hardened container with:

• non-root user
• read-only root filesystem
• no Docker socket
• no host network
• no project mount by default
• dropped Linux capabilities
• no-new-privileges
• seccomp or AppArmor where available
• bounded CPU, memory, PIDs, time, and output
• tmpfs scratch directory
• egress only through the policy broker
• one credential bundle containing only bound slots
• removal after completion

Content-addressed images may be cached, but containers must not retain plaintext credentials or cross-run state.

8.4 Trust Boundary

Arbitrary custom code allowed to use a credential can intentionally send that credential to an allowed destination. Isolation reduces impact but does not make malicious code harmless.

Publication must therefore show:

• code diff
• requested credentials
• requested domains
• requested filesystem and network capabilities
• side-effect classification
• test results

High-risk changes require explicit user approval.

9. Agent Authoring Workflow

The natural-language builder should operate as a governed compiler rather than a one-shot graph generator.

9.1 Agent Lifecycle

1. Understand the requested outcome.
2. Identify missing decisions and compliance constraints.
3. Query the node-definition catalog.
4. Prefer built-in nodes.
5. Identify required credentials and capabilities.
6. Create a draft.
7. Generate custom nodes only where necessary.
8. Generate fixtures and tests.
9. Validate graph, code, schemas, and policy.
10. Request credentials through the dashboard.
11. Run connection tests.
12. Execute a dry run with fixtures or sandbox destinations.
13. Present graph, code, permissions, and side-effect diff.
14. Obtain approval.
15. Publish an immutable flow version.
16. Optionally schedule or activate triggers.
17. Monitor initial runs and report failures.

9.2 MCP Surface

Evolve manage_node_flows into granular actions:

• catalog_nodes
• get_node_definition
• create_draft
• apply_graph_patch
• validate_draft
• create_custom_node
• update_custom_node
• validate_custom_node
• request_credentials
• list_credential_bindings
• bind_credential
• dry_run
• publish
• compare_versions
• rollback
• run
• cancel_run
• retry_run
• inspect_run

Use optimistic concurrency:

{
  "draftRevision": 14,
  "operations": []
}

Conflicting edits return a structured conflict rather than overwriting the flow.

9.3 Functional Agent Skill Integration

When a flow is attached to an agent:

• add it to that agent's callable capability catalog
• expose its input schema and description
• provide a narrow run_attached_flow operation
• enforce project ownership and credential policy
• record the initiating agent and conversation
• never inject the complete graph or credentials into the agent prompt

This closes the current gap where attachments are persisted but do not affect runtime behavior.

10. Dashboard Integration

Replace the local-only page with one canonical project-scoped Nodes workspace.

10.1 Main Layout

• Flow library
• Version and publication selector
• Canvas
• Node catalog
• Dynamic inspector
• Agent Builder panel
• Credential requirements panel
• Validation and policy panel
• Run debugger
• Deployment and scheduling panel

10.2 Agent Builder Panel

The user should be able to request an automation in natural language. The panel should show:

• current agent step
• graph changes
• generated node files
• required credentials
• requested network destinations
• validation results
• dry-run results
• approval requests

Agent changes appear as reviewable graph and code diffs before publication.

10.3 Credentials Outside the Graph

A flow-level banner should show configuration state without showing values:

2 credentials required
[configured] Job source configured for this project
[missing] Email provider not configured

The canvas node stores only a binding ID. Secret values never appear in exported graph JSON.

10.4 Run Debugger

Provide:

• graph overlay with live states
• per-node attempt history
• redacted inputs and outputs
• retry reasons
• invocation links
• timing and token usage
• replay from safe checkpoints
• cancellation
• exportable redacted diagnostics

11. Example Automation Design

The requested job automation should compile into something resembling:

Schedule/Manual Trigger
  -> Job Source Connector
  -> Limit/Paginate to 20
  -> Normalize Job Records
  -> Enrich Company Information
  -> Foreach Job
      -> AI Benefits and Company Scoring
      -> Draft Application Email
  -> Review/Approval Gate
  -> Email Outbox
  -> Email Provider Send
  -> Summary Output

Credential requirements:

• job source or API credential when required
• company enrichment service credential when used
• Gmail, Microsoft, or SMTP credential
• optional applicant profile data stored separately from secrets

Guardrails:

• prefer official APIs or authorized data sources
• do not assume scraping is permitted
• cap records and request rate
• make scoring criteria visible and editable
• default to draft-only email mode
• require approval before initial sends
• deduplicate applications by job identity
• preserve sent-message IDs
• prevent duplicate sends after restart
• retain a user-visible audit trail

12. Data-Model Changes

Reuse existing node-flow tables where practical and add:

Table or change	Purpose
node_definition_revisions	Versioned built-in and custom definition manifests.
custom_node_revisions	Generated source revisions.
custom_node_builds	Validation sessions and immutable build artifacts.
node_flow_publications	Published flow versions and policy snapshots.
automation_credentials	Encrypted payload or external vault reference.
automation_credential_bindings	Flow and node credential-slot mappings.
automation_credential_access_events	Metadata-only secret-use audit.
node_flow_node_attempts	Retry and executor attempt history.
automation_approvals	Durable approval requests and decisions.
automation_outbox	Idempotent external side effects.
automation_webhook_triggers	Authenticated webhook configuration.
Run-table columns	Published version, initiating principal, idempotency key, policy snapshot, lease, and recovery state.

All tables need project or workspace ownership, indexes, cascading behavior, and future principal IDs for headless authorization.

13. Headless-Server Readiness

Encryption alone is insufficient for server operation.

Before remotely managing credentials, add:

• authenticated dashboard and administrative APIs
• OIDC or trusted reverse-proxy identity
• service identities for runners
• roles such as credential admin, automation author, publisher, runner, and viewer
• project-scoped authorization
• TLS termination
• CSRF and origin protection
• request-rate limits
• audit logs
• KMS or Vault readiness checks
• startup failure when encrypted data exists but its key is unavailable

Until this exists, headless server mode may execute already configured credentials but should not expose unauthenticated credential-management routes.

14. Phased Delivery Plan

Phase 0: Architecture and Stabilization

Deliverables:

• architecture decision records
• threat model
• Graph v2 contract
• node-definition manifest
• workflow publication model
• credential and key-provider interfaces
• custom-code trust policy
• migration design
• documentation reconciliation

Immediate fixes:

• actual scheduler version pinning
• semantic node validation
• HTTP response-size bounds
• correlation IDs across all node-flow paths
• accurate secretRef behavior and documentation

Exit gate: one reviewed canonical design with no ambiguity between UI and runtime contracts.

Phase 1: Encrypted Credential Platform

Deliver:

• envelope encryption
• key-provider abstraction
• encrypted SQLite provider
• OS keychain integration
• Vault and KMS-compatible provider boundary
• project and global scopes
• credential schemas
• write-only REST APIs
• credential UI
• audit events
• rotation, revocation, backup, and recovery
• fail-closed readiness

Exit gate: a credential can be created, encrypted, bound, used, rotated, promoted, revoked, and audited without plaintext appearing in database rows, logs, API responses, or agent context.

Phase 2: Canonical Nodes Workspace

Deliver:

• backend-backed project flow library
• Graph v2 canvas
• registry-driven palette and inspector
• version history
• run panel
• credential dependency panel
• import migration from the local canvas
• production feature-flag rollout
• consistent canonical and public documentation

Exit gate: dashboard, MCP, persistence, and runtime all manipulate the same graph.

Phase 3: Durable Runtime v2

Deliver:

• immutable publications
• durable queue and leases
• version-pinned runs
• node attempts
• retry policies
• conditional branches
• foreach and merge
• approval waiting
• outbox and idempotency
• crash recovery
• cancellation propagation
• execution quotas

Exit gate: restarts and retries cannot duplicate approved external side effects.

Phase 4: Hardened Built-in Integrations

Deliver:

• secured HTTP broker
• OAuth broker
• email draft and send nodes
• webhook trigger
• subflow execution
• connection tests
• provider rate limits
• policy and compliance metadata

Exit gate: the target job-to-email workflow can run using built-in nodes against mock APIs without custom code.

Phase 5: Custom Node SDK and Sandbox

Deliver:

• custom-node project format
• TypeScript SDK
• agent code generation
• build and test service
• immutable artifacts
• dependency and policy scans
• hardened runtime containers
• egress broker
• permission review and publication gate

Exit gate: an agent can generate a custom external-API node, tests, and manifest; Code UX can validate and execute it without running generated code in the main process.

Phase 6: Agent Automation Builder

Deliver:

• builder agent instructions
• granular MCP actions
• graph patching
• code and permission diffs
• credential request workflow
• dry runs
• publication approval
• operational follow-up
• functional attached-flow skills

Exit gate: a user can request an automation in natural language and reach a validated draft without manually editing graph JSON or source code.

Phase 7: Headless and Production Hardening

Deliver:

• authenticated management APIs
• RBAC and service identities
• external KMS and Vault deployments
• distributed runner ownership
• audit export
• SLO dashboards
• backup and restore drills
• key-rotation drills
• upgrade and rollback testing

Exit gate: credentialed automations can run on a remote headless deployment with documented recovery and no dependency on Electron or a logged-in desktop session.

15. Validation Strategy

15.1 Cryptography

Test:

• known AES-GCM vectors
• nonce uniqueness
• ciphertext tampering
• authentication-tag tampering
• incorrect key and additional authenticated data
• key-provider unavailability
• rotation and rewrapping
• backup restore with and without recovery keys
• rejection of insecure OS-keychain fallback
• absence of plaintext in database files and logs

15.2 Runtime

Test:

• every built-in node
• graph validation failures
• schema mismatches
• retries and backoff
• cancellation
• timeout
• branch selection
• bounded iteration
• fan-out concurrency
• restart recovery
• version pinning
• approval persistence
• outbox deduplication

15.3 Security

Test:

• SSRF attempts
• cloud metadata targets
• DNS rebinding
• redirect to private networks
• oversized responses
• restricted headers
• container filesystem access
• Docker socket access
• resource exhaustion
• cross-project credential binding
• agent attempts to retrieve secret values
• secret canaries in logs, outputs, traces, and diagnostics

15.4 End-to-End

Use only the approved local test project and mocked external boundaries:

1. Ask an agent to build the example automation.
2. Verify credential requirements appear outside the graph.
3. Configure test credentials.
4. Generate any required custom node.
5. Build and validate.
6. Run against a fixture job API.
7. Verify exactly 20 normalized records.
8. Verify scoring and email drafts.
9. Approve selected drafts.
10. Deliver to a mock email outbox.
11. Restart Code UX during execution.
12. Verify no duplicate email.
13. Rotate a credential and rerun.
14. Roll back the flow version and rerun.

16. Observability and SLOs

Add correlation IDs and structured events for:

• management API calls
• MCP agent actions
• builds and validations
• credential access
• flow runs
• node attempts
• external requests
• approvals
• outbox deliveries

Track:

• flow enqueue latency
• scheduler start lag
• node execution latency
• retry and failure rates
• queue depth
• build duration and failure rate
• credential resolution latency and failures
• approval waiting time
• external API status distribution
• duplicate-prevention events
• redaction and security-policy violations

Set final SLO values after collecting a development baseline. Initial production gates should include zero known secret disclosures, bounded scheduler lag, bounded queue age, and explicit alerting on sustained runtime or credential-resolution failures.

17. Rollout and Rollback

Roll out behind separate flags:

• canonical backend workspace
• encrypted credentials
• durable runtime
• custom-code nodes
• external side effects
• remote credential management

Recommended sequence:

1. Internal development with mock credentials.
2. Built-in nodes only.
3. Encrypted credential beta.
4. Dry-run-only custom nodes.
5. Explicit opt-in custom execution.
6. Draft-only email.
7. Approved side effects.
8. Headless deployment preview.
9. Production availability after recovery drills.

Every migration must be forward-compatible and preserve old flow versions. Rollback should disable new executions while leaving run history and encrypted credential data intact.

18. Key Risks and Mitigations

Risk	Mitigation
Agent-generated code exfiltrates credentials	Per-node credential slots, egress allowlists, isolated execution, code diff review, and explicit publication approval.
Database or backup theft	Envelope encryption with key material stored outside the database.
Live process compromise	External KMS/Vault authorization, short-lived credentials, least privilege, and isolated runners.
Duplicate email or other mutation	Durable outbox, idempotency keys, provider message IDs, and unknown-outcome attention states.
SSRF through HTTP/custom nodes	Central egress broker, DNS and redirect revalidation, network blocking, and allowlists.
Dependency supply-chain compromise	Locked dependencies, immutable builds, vulnerability scans, provenance, and artifact digests.
Graph/UI/runtime divergence	One canonical contract and one shared node registry.
Breaking old flows	Schema-versioned migration and immutable retained versions.
Headless API exposes credentials	Authenticated APIs, RBAC, TLS, write-only secret responses, and remote-management feature gate.
Vault or KMS outage	Readiness failure, bounded cache policy where approved, clear retry semantics, and operational recovery runbook.

19. Documentation Requirements

Each implementation phase must update:

• canonical architecture documentation under docs/
• user-facing workflow and dashboard documentation
• MCP contracts and examples
• credential and security documentation
• operations and recovery runbooks
• matching public pages under docs-web/

Documentation must never imply that planned node types, custom-code execution, credential resolution, or encrypted storage are available before their corresponding phase ships.

20. Definition of Done

The vision is complete when a user can provide only the desired outcome and:

• the agent creates a coherent flow
• built-in nodes are preferred
• required custom code is generated and tested
• missing credentials become secure external forms
• credentials can be project-scoped or explicitly promoted
• no agent sees secret values
• the flow passes graph, code, security, and policy validation
• a fixture-based dry run succeeds
• the user reviews permissions and side effects
• an immutable version is published
• the automation runs manually, on schedule, or by webhook
• restart and retry do not duplicate external mutations
• runs are inspectable and redacted
• credentials can be rotated without editing the flow
• the flow can be rolled back
• the same architecture works locally and in authenticated headless-server mode

✅ Task Checklist

• T01: Define canonical Graph v2 and node registry — codex (PR)
• T02: Build encrypted credential and key-provider platform — codex (PR)
• T03: Make publications and execution durable — codex (PR)
• T04: Harden built-in nodes and external effects — codex (PR)
• T05: Build the custom-node SDK and sandbox — codex (PR)
• T06: Extend MCP authoring and attached-flow skills — codex (PR)
• T07: Replace local canvas with the canonical Nodes workspace — codex (PR)
• T08: Add authenticated headless readiness and recovery coverage — codex (PR)
• T09: Enforce project-scoped authorization on node-flow APIs — codex (PR)
• T10: Make legacy canvas migration canonical and validation-safe — codex (PR)
• T11: Resume durable runs after approval decisions — codex (PR)
• T12: Redact resolved credential values from runtime records — codex (PR)
• T13: Add the real authenticated headless automation drill — codex (PR)
• T14: Exercise the real authenticated automation authoring and durable runtime drill — codex (PR)
• T15: Synchronize canonical and public Nodes workspace documentation — codex (PR)
• T16: Harden Graph v2 validation against malformed input — codex (PR)
• T17: Complete dashboard agent attachment integration — codex (PR)
• T18: Expose redacted node attempts through MCP inspection — codex (PR)
• T19: Implement governed HTTP capability for custom nodes — codex (PR)
• T20: Implement bounded Foreach fan-out — codex (PR)
• T21: Synchronize all public Nodes documentation — codex (PR)
• T22: Restore governed custom-node HTTP bridge after integration merge — codex (PR)
• T23: Wire agent attachments into the canonical Nodes workspace — codex (PR)

👥 Provider Breakdown

23 by codex

⏱️ Sprint Timing

Started	2026-07-12 06:50:34 UTC
Finished	2026-07-12 16:57:27 UTC
Duration	10h 6m 53s

📊 Aggregate CLI Token Usage

Metric	Value
Input tokens	6,660,846
Cached input tokens	222,197,760
Output tokens	832,669
Total tokens	229,691,275
Invocations	54
Tool calls	1,964
Active time	6h 32m 59s

Included usage estimate (subscription/local login): $133.57

🕵️ QA Review Summary

Outcome: pass

Sprint integration passes. Typechecks, build, docs sync, audit, dashboard suite, focused automation suites, authenticated E2E drill, and runtime probes succeeded. One backend Docker-dependent test was unavailable because Docker is absent.

🌿 Branch Info

Base: dev
Head: feature/CODUX-216-nodes-full-integration

---

🤖 Generated by Code UX