Security

Documentation Map

• Overview

• Quick Start

• Installation

• Configuration

• Operations

• Troubleshooting

• Release Notes

• Compatibility

• Architecture

• API Reference

• Security

• Integrations

• Capabilities

• Data Model

• Roadmap

• Project Plan

• Contract Governance

• OSS Inventory

• Channel: latest

• Source repo: JaddaHelpifyr/jhf-shuttle

Security

Auth Model

• live n8n operations use:
  • N8N_API_KEY
  • alias: N8N_EXPERT_API_KEY
• base URL comes from N8N_BASE_URL
• TLS behavior is influenced by N8N_VERIFY_SSL
• optional API runtime uses bearer token via jhf_shuttle_API_TOKEN
• mailbox adapter can use MAILBOX_ADAPTER_PUBLISH_TOKEN

Sensitive Data Types

• API keys and bearer tokens
• callback URLs if they carry operational routing semantics
• runtime event artifacts that may contain workflow/operator metadata
• policy and override files that influence dispatch behavior

Interfaces That Must Be Protected

• /api/v1/* when exposed beyond local development
• mailbox /publish
• callback/status/result webhook paths carrying operational control signals
• any event sink with external reachability

Webhook And Callback Signature Policy

• today:
  • wire-format headers exist for callback contracts
  • repo-wide HMAC enforcement is not yet standardized
• should require signature or token enforcement first if they become remotely reachable:
  • mailbox /publish
  • status/result callback webhook paths
  • any future external event webhook sink
• should stay internal-only:
  • operator-owned dispatch webhook paths
  • internal callback relay paths used only inside the operator stack

Actions That Must Not Be Uncontrolled

• workflow create/update/activate/deactivate from external orchestrators
• mailbox publish/dispatch triggering
• policy file mutation
• destructive cleanup of executions, contexts, or durable delivery state

OAuth

OAuth is not a meaningful primary auth model for this repository today. OAuth would become justified only if:

• external users interact directly with the runtime
• a multi-tenant scenario exists
• access is expected from outside the platform/operator network boundary

Known Security Gaps

• no single repo-wide HMAC signature standard across all webhook/callback surfaces
• optional API auth can still be disabled intentionally for local/dev operation
• some security boundaries remain environment-specific rather than centrally enforced in code

Standalone And Integrated Credential Contract

Mode	Allowed Sources	Not Allowed
standalone	operator-managed env vars, env files, compose runtime env injection	committing secrets to repository files
integrated (current)	same as standalone, still operator-managed in tool runtime	implicit Fabric push of runtime secrets
integrated (planned)	explicit Fabric shared-credential handoff contract once approved	silent re-initialization or overwrite of existing credentials

Required naming for sensitive values in this repository:

• N8N_API_KEY / N8N_EXPERT_API_KEY
• jhf_shuttle_API_TOKEN
• MAILBOX_ADAPTER_PUBLISH_TOKEN
• OPENCLAW_HOOK_TOKEN

Operator guardrail:

• rotation and replacement remain operator-controlled until the Fabric secret contract is finalized and explicitly adopted.

AGPLv3. Learn more at helpifyr.com.