n8n-nodes-trustplane

Community-style n8n node package for Trustplane-signed n8n workflows.

Status

• Current version: 0.1.11
• Stable demo path: Trustplane HTTP Request in default mode
• Optional migration path: HTTP Request compatibility mode

Scope (v1)

• Trustplane-signed outbound HTTP requests
• Manual credentials (tenant/api/client/key/private key)
• Auto-enroll operation via trust-anchor proof (POST /enroll-requests)
• Response mapping with Trustplane decision headers

Install

Self-hosted n8n from npm

In n8n:

1. Settings -> Community Nodes
2. Install package: n8n-nodes-trustplane
3. Restart n8n if prompted

Local dev from this repository

From this repository root:

./scripts/wedge3_demo_up.sh

This starts self-hosted n8n and mounts this package as a custom extension.

Release

Before publishing:

cd integrations/n8n-nodes-trustplane
npm ci
npm run release:check

Publish:

From repository root:

./scripts/publish_n8n_node.sh

Or manually:

cd integrations/n8n-nodes-trustplane
npm ci
npm test
npm pack --dry-run
npm publish --access public

Release checklist:

1. Bump package.json version using semver.
2. Add a changelog entry in CHANGELOG.md.
3. Run npm run release:check.
4. Verify example workflow JSON files still import cleanly.
5. Publish to npm.
6. Update any docs/runbooks that mention the previous version.

Node Operations

• Trustplane HTTP Request

Signed Request

1. Builds canonical signing path from URL (or optional override)
2. Signs proof and generates x-tp-* headers
3. Sends request to target API
4. Returns response data plus Trustplane decision metadata:
   • tp.decision
   • tp.reason
   • tp.requestId
   • tp.auditId (alias of tp.requestId)
   • tp.auditUrl (if auditBaseUrl configured)
   • signedRequest (full signed packet for deterministic replay demos)
5. On non-2xx responses, throws an execution error in n8n with status/decision/reason/request id (unless "continue on fail" is enabled)

Compatibility mode:

• Optional toggle for users migrating from n8n's built-in HTTP Request node
• Adds native-feeling request fields:
  • query params JSON
  • request headers JSON
  • body mode: none / JSON / text
• Adds richer output metadata:
  • http.statusCode
  • http.headers
  • http.method
  • http.url
• Default Trustplane mode remains unchanged to preserve existing happy paths

Replay/stale demo options:

• Replay Signed Request From Input=true:
  • resends method, url, headers, and body from input JSON without re-signing
• Use Signing Overrides From Input=true:
  • reads nonce, timeBucket, sessionId from input JSON before signing
  • useful for stale timestamp / deterministic security demos

Auto Enroll (Trust Anchor)

1. Checks for existing auth material first:
   • workflow cached key (same control URL + tenant + client + API + proof kind)
   • credential key (if tenant/client/API match)
2. If found and still fresh (within Expected Key TTL Seconds minus refresh skew), reuses it and skips new enrollment.
3. If not found (or Force Re-Enroll=true), generates a fresh Ed25519 keypair and calls POST /enroll-requests with:
   • tenant_id
   • client_id
   • public_key_b64url
   • proof_kind
   • proof_payload
   • auto_approve
4. Returns:
   • enrollment.requestId
   • enrollment.keyId
   • reused + reuseSource (workflow_cache or credential) when reused
   • tpAuth object (tenant/api/client/key/privateKey/publicKey + local enrolledAt / keyExpiresAt) for downstream Signed Request nodes

Recommended demo settings:

• Expected Key TTL Seconds = 1800
• Refresh Skew Seconds = 60

Production sizing note:

• Server key TTL and max active keys are enforced by Trustplane (CLIENT_KEY_TTL_SECONDS, MAX_ACTIVE_KEYS_PER_CLIENT).
• Short client-side refresh intervals can exhaust active keys.
• Capacity rule:
  • required_clients = ceil((server_key_ttl_seconds / client_rotation_seconds) / max_active_keys_per_client)

Autonomous proof notes:

• oidc: requires a fresh OIDC JWT (replay protection applies).
• aws_iid: if Proof Payload is empty and Use TP_OIDC_TOKEN Env Fallback=true, node auto-fetches EC2 IID document+signature from IMDSv2.

Credentials

Credential type: Trustplane API

• tenantId
• apiId
• clientId
• keyId
• auditBaseUrl (optional, for audit deep-links)
• privateKey (base64url Ed25519 private key)
• bucketSeconds

Quick Start

Existing happy path

1. Create a Trustplane API credential with your tenant / api / client / key / private key.
2. Add Trustplane HTTP Request.
3. Use Signed Request.
4. Set Method, URL, optional Path Override, and optional JSON body.

Auto-enroll happy path

1. Add Trustplane HTTP Request.
2. Set Operation = Auto Enroll (Trust Anchor).
3. Use your tenant/client/api IDs and trust-anchor proof settings.
4. Feed the output tpAuth object into a downstream Signed Request node.

HTTP compatibility mode

1. Enable HTTP Request Compatibility Mode.
2. Set Method and URL.
3. Put query params in Query Params (JSON) if needed.
4. Put headers in Request Headers (JSON).
5. Choose Body Mode:
   • None
   • JSON
   • Text
6. Keep Trustplane auth material via credential or upstream tpAuth.

Example Target Routes

For the marketplace wedge demo, use routes behind the existing mock gateway:

• GET /api/crm/customers
• GET /api/crm/contacts
• GET /api/crm/deals
• PUT /api/crm/deals/:id
• POST /api/crm/workflows/:id/trigger
• GET /api/crm/contacts/export

Canonical Workflows

• examples/wedge3-allowed-auto-enroll.json
• examples/wedge3-denied-scope.json
• examples/wedge3-denied-replay.json
• examples/wedge3-denied-stale.json
• examples/wedge3-rate-limit.json
• examples/wedge3-agent-tool-customers.json (tool workflow)
• examples/wedge3-ai-agent-orchestrator.json (AI Agent + tool wiring)

AI Agent Wiring (n8n built-in Agent node)

For agent-native demos, import both workflow templates above:

1. wedge3-agent-tool-customers.json is called as a tool and performs Trustplane auto-enroll + signed customer fetch.
2. wedge3-ai-agent-orchestrator.json uses:
   • AI Agent (@n8n/n8n-nodes-langchain.agent)
   • OpenAI Chat Model (@n8n/n8n-nodes-langchain.lmChatOpenAi)
   • Call n8n Workflow Tool (@n8n/n8n-nodes-langchain.toolWorkflow)
3. Set the tool node workflowId to the imported tool workflow ID.
4. Agent output should include decision, reason, request_id, and audit_url from tool data for demo evidence.

Troubleshooting

Workflow is not active and cannot be executed

• Activate the workflow used by Call n8n Workflow Tool
• Ensure it starts with When Executed by Another Workflow

auto_enroll_not_approved

• Check trust anchor issuer/account/region constraints
• For aws_iid, verify IMDSv2 access from the n8n host
• Check the reason value returned in the node error

Trustplane request denied/failed

• Inspect:
  • status
  • tp.decision
  • tp.reason
  • tp.requestId
• Then open the audit_url if configured

Webhook HTML mode returns undefined

• Your previous node must return json.html
• Respond to Webhook should use {{$json.html}}
• Add header: Content-Type: text/html; charset=utf-8

Visual Webhook Mode (optional)

For a browser-friendly demo page:

1. Start from wedge3-allowed-auto-enroll.json.
2. Replace trigger with Webhook (GET, respond using Respond to Webhook node).
3. Final code node returns { json: { html: "<html>...</html>" } }.
4. Respond to Webhook returns {{$json.html}} with header Content-Type: text/html; charset=utf-8.