We value transparency. All source code for the Initiat CLI, including encryption and transportation implementations, is open source and available at github.com/InitiatDev/initiat-cli . You can review, audit, and verify every aspect of our security implementation.
Zero-Knowledge Architecture
Initiat uses a zero-knowledge security model where secrets are encrypted on your device before being sent to the server. The server only stores encrypted ciphertext and never has access to your plaintext secrets. This means even if the server is compromised, your secrets remain protected.
Technical Details
All secrets are encrypted client-side using the project key (PSK - Project Secret Key) before transmission. The encryption process uses authenticated encryption with a unique nonce for each secret version, ensuring that identical secrets produce different ciphertexts.
The server stores only three pieces of data for each secret:
-
encrypted_value- The encrypted secret value (binary) -
nonce- The unique nonce used for encryption (binary) -
key- The secret identifier/name (string)
The server cannot decrypt secrets because it never receives the project key in plaintext. Each device has its own wrapped copy of the project key, encrypted with that device's X25519 public key.
Project Key Management
Each project has a unique project key (PSK) that encrypts all secrets within that project. This key is never stored in plaintext on the server. Instead, each authorized device has its own encrypted copy of the project key, wrapped with that device's encryption key.
Key Wrapping Details
When a project key is initialized, it is encrypted (wrapped) using each authorized device's X25519 public key. The wrapped key is stored in the
project_keys
table as wrapped_project_key
(binary).
Key wrapping ensures that:
- Each device can only unwrap its own copy of the project key using its private X25519 key
- The server never sees the plaintext project key
- When a device is removed, only that device's wrapped key needs to be deleted
- Project keys can be versioned to support rotation without re-encrypting all secrets
The project key version is tracked separately, allowing for key rotation while maintaining access to secrets encrypted with previous key versions during the transition period.
Device-Based Authentication
Initiat uses cryptographic device keys instead of passwords or bearer tokens. Each device generates a unique Ed25519 key pair for signing requests and an X25519 key pair for encryption. Private keys are stored securely in your operating system's keychain and never leave your device.
Cryptographic Details
Each device uses two key pairs:
- Ed25519 - Used for signing HTTP requests to authenticate the device. The public key is stored on the server for signature verification.
- X25519 - Used for encrypting/wrapping project keys. The public key is stored on the server to enable key wrapping for that device.
Private keys are generated locally and stored in the OS keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux). The server only stores public keys, which cannot be used to decrypt data or forge signatures.
When a device makes a request, it signs the request body, headers, and timestamp with its Ed25519 private key. The server verifies the signature using the stored public key, ensuring the request came from an authorized device.
Secret Versioning & Audit Trails
Every secret update creates a new version, preserving a complete history of changes. This allows you to track when secrets were modified and by which device, providing an audit trail for compliance and security reviews.
Versioning Implementation
Each secret has a version
field that increments with each update. The database enforces uniqueness on the combination of project_id, key, and version, ensuring all versions are preserved.
When retrieving secrets, the system returns the latest version (highest version number) for each secret key. Historical versions remain accessible for audit purposes and can be queried separately.
Each secret version records:
-
The device that created it (
created_by_device_id) - Timestamp of creation
- The encrypted value and nonce for that specific version
Secrets can be soft-deleted by setting a
deleted_at
timestamp, which removes them from active queries while preserving the encrypted data for recovery if needed.
Access Control
Access to secrets is controlled at multiple levels: project membership, device authorization, and project key access. Only devices that have been approved and have received a wrapped copy of the project key can decrypt secrets for that project.
Access Control Layers
Access control operates at three layers:
- Project Membership - Users must be members of a project with appropriate roles (owner, admin, or member). Membership is managed through project invitations and role assignments.
- Device Authorization - Each device must be explicitly approved for access. Device approval workflows ensure that only trusted devices can access project secrets.
- Project Key Access - Even with membership and device approval, a device must have a wrapped copy of the project key to decrypt secrets. Without the wrapped key, the device cannot unwrap the project key and therefore cannot decrypt any secrets.
This multi-layer approach ensures that compromising one layer (e.g., a user account) does not automatically grant access to secrets. The device must still be authorized and have the wrapped project key.
Security Best Practices
While Initiat's architecture provides strong security by default, following these practices will help maintain the security of your secrets and access controls.
Recommended Practices
- Device Management - Regularly review and remove unused or compromised devices. When a device is lost or compromised, revoke its access immediately.
- Project Membership - Follow the principle of least privilege. Only grant project access to users who need it, and use appropriate roles (member vs admin vs owner).
- Secret Naming - Use clear, descriptive names for secrets to avoid confusion and accidental exposure. Avoid including sensitive information in secret keys/names.
- Key Rotation - Plan for project key rotation as part of your security strategy. While not yet automated, the versioning system supports key rotation workflows.
- Audit Reviews - Periodically review secret versions and access logs to identify unusual patterns or unauthorized access attempts.
- OS Keychain Security - Ensure your operating system keychain is properly secured with a strong password or biometric authentication, as it stores your device's private keys.