Skip to content

ADR-0006 – Secrets Management and Credential Handling

Status

Accepted

Context

The HomeOps Platform consists of multiple components operating across different trust boundaries, including client applications, backend services, infrastructure components, and external integrations. These components require the use of sensitive information such as credentials, API keys, tokens, and secrets to authenticate, authorize, and communicate securely.

Without a clearly defined approach to secrets management, sensitive data risks being:

  • hard-coded into source code,
  • stored insecurely in configuration files,
  • reused across components or environments, or
  • handled inconsistently over time.

Given that the platform is self-hosted and developed incrementally, it is important to define a baseline model for how secrets are handled, even if concrete tooling choices are deferred to later phases.

Decision

The HomeOps Platform adopts a principle-based approach to secrets management, where sensitive data is treated as a distinct concern separate from application logic and source code.

Secrets and credentials are managed according to the following principles:

  • Secrets are never stored directly in source code or committed to version control.
  • Secrets are provided to applications at runtime through environment variables, configuration injection, or dedicated secret storage mechanisms.
  • Each component uses only the minimum set of credentials required for its function (principle of least privilege).
  • Secrets are scoped to a specific environment and trust boundary, and are not shared across unrelated components.
  • Long-lived credentials are avoided when feasible; rotatable or short-lived credentials are preferred where supported.

At the umbrella-project level, the platform does not mandate a specific secrets management tool. Instead, it defines clear expectations and constraints that guide later implementation decisions within individual subprojects.

Rationale

This approach balances security, flexibility, and project maturity:

  • It avoids premature optimization or tool lock-in while the platform architecture is still evolving.
  • It ensures that sensitive data handling is considered early, before interfaces and deployment pipelines are finalized.
  • It aligns with best practices for self-hosted systems, where operational responsibility and trust boundaries must be explicit.
  • It supports future automation (CI/CD, containerization) without requiring fundamental changes to how secrets are handled.

By separating the policy of secrets management from the mechanism, the platform remains adaptable to future requirements and constraints.

Consequences

Positive

  • Reduced risk of accidental credential leakage through version control.
  • Clear guidance for future component development and deployment.
  • Easier migration to more advanced secrets management solutions as the platform matures.
  • Improved alignment between security, deployment, and interface design.

Negative

  • Additional operational complexity compared to hard-coded or ad-hoc credential handling.
  • Requires discipline in development and deployment workflows.
  • Some secrets management decisions are deferred, requiring future ADRs or refinements.
  • ADR-0001: Decision to Introduce a Self-Hosted Server Environment
  • ADR-0003: Baseline Security Hardening for Self-Hosted Server
  • ADR-0004: Network Segmentation and Trust Boundaries
  • ADR-0005: Authentication and Access Management Model
  • Future decisions regarding CI/CD secret injection and runtime secret storage mechanisms