Skip to main content

Security

Documentation Map​

Security

Auth Model​

jhf-warp requires a Bearer token for internal HTTP routes while keeping self-description endpoints open. Heddle remains auth truth, Fabric remains a projection/composition layer, Spine is the future governance brain, and Warp must not become a shadow IAM or governance authority. Security still depends on deployment-time protection such as:

  • reverse proxy or gateway auth
  • network segmentation
  • internal-only exposure of mutating endpoints
  • transport protection between internal components

Inbound auth accepts:

  • Authorization: Bearer <token>

Configuration:

  • JHF_WARP_FABRIC_CONTEXT_BASE_URL
    • points Warp at the current projection/composition endpoint
  • JHF_WARP_FABRIC_CONTEXT_AUTH_TOKEN
    • optional service-to-service token for Warp -> Fabric
  • the presented Bearer token is opaque to Warp
    • Heddle remains identity/auth truth
    • Warp consumes projected context instead of parsing claims into local authority

This remains a layered boundary, not a substitute for gateway/network policy.

Minimal recommended production-style deployment standard:

  • reverse proxy or gateway auth in front of the service
  • internal network exposure only
  • mutating endpoints denied by default unless an operator-trusted caller explicitly needs them
  • read-only self-description endpoints handled separately from control/mutation paths
  • projected authority context configured through JHF_WARP_FABRIC_CONTEXT_BASE_URL
  • optional Warp -> Fabric service auth through JHF_WARP_FABRIC_CONTEXT_AUTH_TOKEN

Endpoint Exposure Classes​

Read-only self-description surfaces that may be exposed through the internal operator/gateway boundary:

  • /health
  • /ready
  • /version
  • /openapi.json
  • /fabric-manifest.json

Read-only operator surfaces that should stay on authenticated internal/operator paths:

  • /api/v1/runtime/inventory
  • /api/v1/topology/current
  • /api/v1/topology/diff
  • /api/v1/drift/summary
  • /api/v1/audit/events
  • /api/v1/rollouts/audit
  • /api/v1/rollouts/history
  • /metrics
  • /api/v1/control-agent/status
  • /api/v1/control-agent/leases
  • /api/v1/control-agent/watchdog
  • /api/v1/control-agent/schedule
  • /api/v1/persistent-agents
  • /api/v1/persistent-agents/{agent_slug}
  • /api/v1/tool-profiles
  • /api/v1/workspaces/persistent

Mutating or control-oriented surfaces that must remain default-deny behind authenticated internal boundaries:

  • /api/v1/openclaw/patch/*
  • /api/v1/execution/*
  • /api/v1/control-agent/reconcile
  • /api/v1/control-agent/dispatch-preview
  • /api/v1/persistent-agents/{agent_slug}/learning-proposals write paths
  • /api/v1/persistent-agents/{agent_slug}/learning-proposals/{proposal_id}/review
  • outbound integration trigger endpoints such as Helpifyr Pattern, Helpifyr Spindle, and jhf-shuttle sync writes

At minimum, the deployment boundary should treat:

  • /api/v1/openclaw/patch/*
  • /api/v1/execution/*
  • /api/v1/control-agent/*
  • persistent learning review endpoints

as authenticated internal control surfaces, not general application endpoints.

Access Control Expectations​

Especially sensitive surfaces:

  • /api/v1/openclaw/patch/apply
  • /api/v1/openclaw/patch/plan
  • /api/v1/execution/team/apply
  • /api/v1/execution/subagents/apply
  • /api/v1/control-agent/reconcile
  • persistent-agent learning review endpoints

These endpoints must not be exposed openly on untrusted networks.

Sensitive Data Types​

  • downstream auth tokens:
    • Helpifyr Pattern
    • Helpifyr Spindle
    • jhf-shuttle
    • Gitea Packages token for OCI publishing
  • database DSNs
  • OpenClaw host/runtime connection details
  • operational state that may expose runtime topology or governance details

Secrets Model​

  • secrets are environment-driven
  • secrets must not be committed to the repository
  • CI uses runner-side variables/secrets
  • outbound integration calls are disabled/skipped when required credentials are absent

High-Risk Integration Areas​

  • OpenClaw mutation planning/apply
  • control-agent reconcile callback path
  • outbound setup/sync delivery
  • persistent workspace governance
  • OCI publish path

Monitoring Exposure​

The current monitoring baseline is read-first and endpoint-based:

  • /health
  • /ready
  • /version
  • /metrics
  • GET /api/v1/runtime/inventory
  • GET /api/v1/drift/summary
  • GET /api/v1/rollouts/audit
  • GET /api/v1/control-agent/status

GET /metrics exists as a minimal Prometheus-style text export. Do not claim a richer tracing or push-metrics contract where none exists.

Inputs That Must Never Be Open​

Never expose directly to the public internet without an explicit gateway/auth layer:

  • all mutating /api/v1/... surfaces
  • control-agent callback surfaces
  • persistent learning review surfaces
  • runtime patch/apply surfaces

Actions That Must Not Be Uncontrolled​

  • applying OpenClaw mutations against live runtime
  • approving or rejecting governed learnings without audit
  • changing workspace retention/deletion behavior without review
  • publishing internal OCI artifacts from an untrusted environment

OAuth Decision Boundary​

OAuth is required if any of the following becomes true:

  • external users interact directly with the service
  • the service becomes multi-tenant
  • requests are expected from outside the platform network

OAuth is not required today while all of the following remain true:

  • communication is internal service-to-service traffic
  • Fabric-triggered communication stays inside trusted platform boundaries
  • no end-user context is needed

The current repository uses Bearer token presentation plus projected authority context rather than local token validation or a built-in OAuth flow inside Warp.

Key Current Risks​

  • no webhook signature standard
  • metrics scraping still relies on the same internal token boundary and gateway policy as other internal read routes
  • Fabric registration/discovery is not implemented yet, so future control boundaries are still undefined

License​

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.