Secrets and Keychain

Hostwright supports a narrow manifest secret-reference model. The manifest stores a reference label, never a secret value:

services:
  api:
    image: ghcr.io/example/api@sha256:...
    secretEnv:
      API_TOKEN: keychain://hostwright.api/api-token

Rules enforced by validation:

• Plaintext sensitive keys under env fail validation.
• secretEnv values must use keychain://<service>/<account>.
• The same key cannot appear in both env and secretEnv.

When references resolve

Planning, status, state persistence, diagnostics, events, and errors see only redacted secret-reference metadata. A confirmed create action resolves references immediately before calling the runtime mutation hook. If no approved backend resolves the reference, apply fails before mutation.

Hostwright also redacts the keychain reference labels themselves — a service/account name can reveal local context, so it never appears in plans, state rows, diagnostics bundles, or error messages.

The macOS Keychain backend

MacOSKeychainSecretStore is a read-only production backend for local generic-password items. It:

• queries an exact service/account pair only;
• excludes synchronizable (iCloud-synced) items;
• disables authentication UI — a CLI process never presents a Keychain prompt.

Its live integration gate creates a unique real Keychain item, resolves it, deletes it, and verifies the second lookup fails — with no conditional skip path. A malformed-data case proves non-UTF-8 item data fails without exposing the service, account, or bytes.

Opt-in by design

The default CLI backend is intentionally unavailable. Live macOS Keychain access is not enabled by default; an embedding caller must inject the backend explicitly. Production code never creates, updates, or deletes Keychain items.

Out of scope

Rejected The following are rejected, not pending:

• plaintext secret persistence in state, events, or diagnostics;
• Keychain writes/deletes, prompts, access groups, or synchronizable items;
• provider credentials, cloud secret managers, registry credential storage, credential sync, or credential upload;
• mounted secret files, multiline secret payloads, binary secret blobs;
• Compose/Kubernetes secrets: compatibility.

See State store for the persistence boundary and Security and safety for the wider posture.