Skip to main content

Security

Documentation Map​

Security

Auth Model​

ERP / HTTP surfaces​

  • health/presence endpoints may be guest-readable only where explicitly documented
  • webhook and callback surfaces rely on HMAC signature validation with repo-configured shared secrets

MCP​

  • productive MCP execution requires X-JHF-Spindle-Key
  • auth-exempt methods are intentionally narrow
  • tool ACLs, company scope, write/approve flags, audit logging, and rate limiting apply

Access Control​

  • ERPNext remains the system of record
  • external systems must not write directly to ledger tables
  • approvals must come through signed approval/callback paths
  • dispatch result ingestion must come through signed callback paths

Sensitive Data Types​

  • accounting and payroll records
  • supplier/customer master data
  • approval decisions and comments
  • callback tokens, shared secrets, and API keys
  • dispatch evidence and compliance exports

Secrets Model​

  • secrets live in environment/runtime configuration, not in git
  • critical examples:
    • OPENCLAW_SHARED_SECRET
    • N8N_SHARED_SECRET
    • N8N_JOB_RESULT_SHARED_SECRET
    • ZAMMAD_WEBHOOK_SECRET
    • ZAMMAD_API_TOKEN
    • provider webhook secrets
    • MCP API keys

Mode-Specific Secret Ownership​

  • standalone mode:
    • local operator controls secret provisioning and rotation
    • secrets are injected at runtime, never stored in repository files
  • integrated mode (planned read-first):
    • Fabric may read compatibility/policy metadata
    • Fabric must not write or rotate Helpifyr Spindle secrets directly
    • Helpifyr Spindle callback and MCP auth boundaries remain enforced locally

Credential Transition Guardrails​

  • no silent secret re-initialization when switching from standalone to integrated posture
  • callback signature verification must remain active during migrations
  • any secret-source change requires explicit operator checkpoint and rollback path

Cross-References​

  • authoritative exposed-surface inventory: docs/API.md
  • integration direction, auth, and trigger contracts: docs/INTEGRATIONS.md
  • machine-readable auth, capability, and Fabric access constraints: fabric-manifest.json

Interfaces That Must Be Protected​

  • /mcp
  • /api/method/jhf_spindle_core.api.callbacks.openclaw_approval
  • /api/method/jhf_spindle_core.api.callbacks.n8n_job_result
  • /api/method/jhf_spindle_core.api.callbacks.n8n_hil_decision
  • /api/method/jhf_spindle_core.api.support_cases.zammad_inbound
  • /api/method/jhf_spindle_core.api.support_cases.zammad_outbound
  • provider webhook endpoints

Interfaces That Must Never Be Open​

  • productive MCP write access without API-key auth
  • unsigned callback ingestion
  • direct DB or ledger-write interfaces exposed to external tooling

Non-Controlled Automation That Is Not Allowed​

  • Fabric or any external control plane must not directly:
    • create ledger postings
    • fake approval decisions
    • bypass approval matrix logic
    • run destructive migration or tenant repair operations
    • trigger payment, period-close, or dispatch write actions without the existing guarded product path

Risks​

  • callback spoofing
  • stale or missing dispatch evidence
  • runtime drift between repo and host
  • reverse-proxy misrouting after service recreate
  • contract drift across OpenClaw, n8n, or jhf-wire

OAuth​

OAuth is not the primary model today because this repository mainly exposes:

  • signed webhook/callback ingestion
  • ERP-authenticated surfaces
  • MCP API-key based operator/agent access

OAuth is required if:

  • external users interact directly with protected repo-owned surfaces
  • a real multi-tenant access model is introduced
  • authenticated access must come from outside the controlled platform network

OAuth is not required if:

  • communication remains internal service-to-service
  • communication is Fabric-governed without end-user identity delegation
  • there is no end-user context and the existing API-key or signed-callback model is sufficient

If OAuth is introduced later, it should be additive and documented as a new explicit contract, not assumed by current docs.

License notice: AGPLv3 (GNU Affero General Public License v3.0)
Website: https://helpifyr.com