Security overview

Ethen handles API keys, provider credentials, and request metadata across several surfaces. This page summarises the security boundaries you should be aware of before integrating.

Release honesty (M9)

• Platform security controls (auth fail-closed, tenancy matrix, vault patterns) are documented and partially certification-proven in SOL-43.
• The Security (Sentinel) workspace is deferred / private-alpha enrollment, not a public-beta launch product.
• Launch Gate K (independent security review) is BLOCKED until an external reviewer attests — see Certification status and known limits.
• Payment collection is implemented in code but is not live-certified or production-ready in this release.

API key storage and verification

Ethen Gateway API keys are never stored in plain text. When a key is created:

1. A random 16-byte salt is generated.
2. The raw key is combined with the salt and hashed with SHA-256.
3. Only the algorithm:salt:digest triplet is stored.

When a key is used for authentication, the raw submitted key is hashed with the stored salt and compared using constant-time comparison (crypto.timingSafeEqual). A key that was never created or has been revoked cannot be verified.

Keys are scoped per project and per environment (live or test). The key prefix and suffix are stored in plain text for identification in dashboards and logs; the full key is never persisted after creation.

See the Gateway authentication guide for key creation and usage.

Credential management

Provider credentials (third-party API keys for OpenAI, Anthropic, DeepSeek, etc.) are managed through a credential store abstraction that keeps raw secrets off the renderer process and out of plain-text configuration files:

• Desktop (Electron) mode — uses safeStorage.encryptString/decryptString via IPC. Encrypted blobs are stored in a scoped file. Only credential references (provider ID + label) are exposed to the renderer.
• Web mode — delegates to existing process.env resolution (getProviderApiKey). Setting and deleting are no-ops; environment variables are read-only at runtime.
• Gateway BYOK — provider keys stored for a project are encrypted at rest with AES-256-GCM and stored in the gateway_provider_credentials table.

Managed vault and approvals

Connected Apps credentials live in the managed vault, the only interface that may hold secret values:

• Production adapters are backed by a managed KMS/vault. Database rows hold an opaque externalRef — never the secret value.
• Flow grant secrets resolve to a sealed credential handle reachable only through reveal(); every implicit serialization path (logs, errors, caches, telemetry) is redacted.
• Every vault touch emits an audit event — created, read, rotated, revoked — with actor, purpose, reference, and version.
• Secret lifecycle is explicit: staged → active → superseded or revoked.

Sensitive actions on connected accounts pause for approval at /api/platform/approvals before running. Approvals name the exact action, account, and scopes; they expire; changed actions need fresh approvals. See Connected Apps overview and the approval governance guide.

Secrets redaction

Before content is stored, displayed, or exported, a centralised redaction layer scans for common secret patterns and masks them:

• OpenAI-style keys (sk-...)
• Anthropic-style keys (sk-ant-...)
• AWS access keys (AKIA...)
• SendGrid keys, Firebase tokens, and generic sk_/pk_ prefixed keys
• Sensitive metadata fields (secrets, tokens, keys, passwords, credentials, cookies, headers, bodies) are stripped from audit exports.

Safe error handling

API error responses are constructed through a centralised jsonError utility that:

• Clamps HTTP status codes to the 400–599 range.
• Redacts error messages to a maximum length (default 500 characters).
• Returns structured { ok: false, code, error } objects without leaking secrets.

Gateway-specific errors produce codes like SETUP_REQUIRED, PROVIDER_UNAVAILABLE, INVALID_REQUEST, and INTERNAL_ERROR that are safe to surface in client responses.

Audit export

All audit entries pass through a stripSensitiveMetadata filter before export. Fields matching secret, token, key, credential, authorization, cookie, body, header, or session patterns are removed from the exported record. Metadata that survives the filter includes event type, timestamp, actor ID, and high-level outcome.

Data handling

Gateway request logs contain metadata only — model, provider, tokens, cost, and timestamps. Request and response content is never stored in the Gateway logging pipeline unless separately configured. See the data handling guide for configuration options.

Review-required statements

The following claims in this guide have not been independently verified by a security review and should be reviewed before publication:

• Credential store patterns on Desktop rely on Electron safeStorage availability and have not undergone external penetration testing.
• Data retention commitments depend on the project's configured contentRetentionDays and loggingMode settings — no default retention SLA is guaranteed.