conductor/docs/SECRETS.md

Secrets and Authentication Security Model

Approved MVP policy

Conductor stores credential values server-side in SQLite encrypted with AES-256-GCM. A persistent 32-byte master key is supplied to the backend as CONDUCTOR_SECRET_KEY, encoded as base64 or 64 hexadecimal characters. The key is never stored in SQLite, project JSON, frontend state, exports, logs, or source control.

Canonical actions will identify credentials by an opaque secret-reference ID. Credential values are never embedded in the canonical project document. Anonymous actions require no secret.

Stored credential shapes

• basicAuth: username and password
• bearerToken: token
• apiKeyHeader: header name and API-key value
• apiKeyQueryParameter: query-parameter name and API-key value

Secret names and authentication types are non-secret metadata. List and lookup APIs return only ID, name, authentication type, and timestamps. There is no API that returns a stored credential value. Creation and replacement accept credential values but return metadata only.

Threat assumptions and boundaries

• Conductor v0.1.0 is a single-user deployment; accounts, tenant isolation, and RBAC are out of scope.
• TLS termination and host access controls are deployment responsibilities. Credential submission must use HTTPS outside trusted local development.
• SQLite disclosure alone must not reveal plaintext. An attacker holding both the database and master key can decrypt credentials.
• Process or browser compromise, memory inspection, hostile administrators, and compromised destinations are not prevented by encryption at rest.
• Authentication injection and error/log/URL redaction occur server-side. Query API keys require URL sanitization before logging.

Key and lifecycle contract

• Generate the key outside Conductor and inject it through a Docker secret or environment variable.
• Retain the same key across restarts and back it up separately from SQLite.
• Losing the key makes stored credentials unrecoverable.
• Key rotation requires a deliberate future procedure and is not part of this increment.
• If the key is absent or malformed, anonymous behavior remains available while secret creation, replacement, and resolution fail closed.
• Secret deletion is permanent. Reference-aware deletion safeguards will accompany canonical action references.

Generate a development key with openssl rand -base64 32, then set CONDUCTOR_SECRET_KEY before starting Docker Compose. Never commit the value.