ADR-016: Sidecar daemon option 

Table of contents

Status 

Accepted

Date 

2026-01-12

Context 

FFI does not provide true isolation. If the threat model includes "PHP process compromise", a separate process (sidecar/daemon) running under different OS permissions can provide stronger separation:

  • Master key not readable by PHP process user
  • Narrower filesystem and network capabilities
  • Independent hardening and observability

We don't want to block MVP with sidecar complexity, but we must not paint ourselves into a corner.

Decision 

  • The transport abstraction (ADR-012: SecureHttpClient API and transports) remains compatible with a future SidecarTransport
  • Request/response specs are designed to be serializable (e.g., JSON or binary framing) so that FFI and sidecar can share the same protocol shape
  • Sidecar mode is explicitly a Phase 3 candidate, not MVP scope

Consequences 

Positive 

  • Preserves an upgrade path to stronger isolation without breaking consumers
  • Allows security-conscious customers to adopt a more robust deployment model later

Negative 

  • Some design choices (spec framing, error taxonomy) must be slightly more disciplined early on

Alternatives considered 

Commit only to FFI and ignore sidecar 

Do not support a sidecar mode at all.

Rejected: too limiting for serious security requirements.

Start with sidecar immediately 

Build sidecar mode from the start.

Rejected: slows down MVP and increases operational burden prematurely.