Skip to main content

Security

Documentation Map​

Security

Auth Model​

  • inbound workflow webhooks use a single standardized auth model switch:
    • INGRESS_AUTH_MODE=network-trust (default, backward compatible)
    • INGRESS_AUTH_MODE=shared-secret (enforces x-ingress-secret header on all ingress workflows)
  • outbound callbacks to Helpifyr Spindle are protected with HMAC:
    • X-Signature
    • X-Idempotency-Key
  • MCP calls to Helpifyr Spindle use canonical X-JHF-Spindle-Key (legacy X-ClawLedger-Key transition fallback is still emitted by jhf-wire)
  • provider APIs use their respective auth models:
    • finAPI OAuth2 bearer tokens
    • Storecove API key
    • internal ERiC and Aleph stack-internal trust

Access Control​

  • Git/Gitea controls source changes
  • n8n API must stay protected by N8N_API_KEY
  • runtime secrets stay in host-local env or equivalent runtime injection

Sensitive Data​

  • provider credentials
  • callback shared secret
  • MCP API key
  • ELSTER certificate material and PIN
  • Aleph secrets and database password
  • user-context finAPI credentials

Secret Model​

  • secrets must not be committed
  • .env.example is a contract only, not secret storage
  • placeholders and pending-* markers remain explicit until real onboarding is complete

Protected Interfaces​

  • inbound workflow webhooks from Helpifyr Spindle
  • callback path to Helpifyr Spindle
  • MCP import path to Helpifyr Spindle
  • n8n API
  • provider-facing auth exchanges

Inputs That Must Never Be Open​

  • ingress webhooks outside the trusted platform network segment
  • unauthenticated n8n admin API
  • MCP access without key
  • any status export that leaks secret values

Actions That Must Not Be Uncontrolled​

  • real SEPA or provider submissions
  • secret rotation
  • direct workflow mutation outside Git
  • Fabric-triggered live provider actions

Risks​

  • false trust in ingress webhooks if network isolation, allowlisting, or reverse-proxy boundaries break down
  • callback signature mismatch or secret drift
  • provider credential leakage
  • runtime drift between Git and n8n
  • upstream Helpifyr Spindle callback failures being misread as repo regressions

Ingress Webhook Decision​

  • Current decision:
    • keep one repo-wide ingress auth mechanism with environment-controlled mode
    • default stays network-trust to avoid breaking existing dispatch emitters
    • optional hardening mode shared-secret is already implemented in all ingress workflows
  • Current non-features:
    • no per-workflow custom auth variants
    • no public internet exposure is assumed
  • Required operational guardrail:
    • only Helpifyr Spindle and trusted operator paths may reach webhook paths
    • use INGRESS_AUTH_MODE=shared-secret where network-trust assumptions are weak

OAuth Note​

OAuth is used where the provider requires it, especially finAPI. It is not the general auth model for this repository as a whole because most repo-relevant surfaces are Git-, CLI-, or stack-internal contracts rather than a single public API service.

OAuth is required when:

  • external users interact directly
  • a multi-tenant scenario exists
  • access comes from outside the platform network boundary

OAuth is not required when:

  • communication is strictly internal service-to-service traffic
  • Fabric reads metadata or status contracts without user context
  • no user-context or delegated-user authorization exists in the contract at all

License: AGPLv3 Project website: https://helpifyr.com