crypto

Documentation

Overview

Package crypto handles all cryptographic operations for AgentSecrets.

This mirrors the Python SecretsCLI's encryption.py but uses:

• AES-256-GCM instead of Fernet for symmetric encryption
• X25519 + NaCl SealedBox for asymmetric encryption (same as Python)
• Argon2id instead of PBKDF2-SHA256 for key derivation

Key hierarchy:

Password → (Argon2id) → Password-Derived Key → decrypts Private Key
Private Key → (NaCl SealedBox) → decrypts Workspace Key
Workspace Key → (AES-256-GCM) → encrypts/decrypts Secrets

Index

• Constants
• func DecryptFromUser(privateKey, publicKey, encrypted []byte) ([]byte, error)
• func DecryptPrivateKey(encryptedB64, password, saltHex string) ([]byte, error)
• func DecryptSecret(encryptedB64 string, workspaceKey []byte) (string, error)
• func DeriveKeyFromPassword(password, saltHex string) ([]byte, error)
• func EncryptForUser(recipientPublicKey, data []byte) ([]byte, error)
• func EncryptPrivateKey(privateKey []byte, password string) (ciphertextB64, saltHex string, err error)
• func EncryptSecret(plaintext string, workspaceKey []byte) (string, error)
• func GenerateKeypair() (privateKey, publicKey []byte, err error)
• func GenerateWorkspaceKey() ([]byte, error)
• type UserKeys
  • func SetupUser(password string) (*UserKeys, error)

Constants

const KeySize = 32

const NonceSize = 12

const SaltSize = 32

Functions

func DecryptFromUser

func DecryptFromUser(privateKey, publicKey, encrypted []byte) ([]byte, error)

DecryptFromUser decrypts data that was encrypted with our public key (NaCl SealedBox). Used for decrypting workspace keys received from team invites.

func DecryptPrivateKey

func DecryptPrivateKey(encryptedB64, password, saltHex string) ([]byte, error)

DecryptPrivateKey decrypts a private key using the user's password. This is called during login to recover the private key from the server's encrypted copy.

func DecryptSecret

func DecryptSecret(encryptedB64 string, workspaceKey []byte) (string, error)

DecryptSecret decrypts a base64-encoded ciphertext (with prepended nonce) using AES-256-GCM.

func DeriveKeyFromPassword

func DeriveKeyFromPassword(password, saltHex string) ([]byte, error)

DeriveKeyFromPassword derives a 32-byte encryption key from a password using Argon2id.

func EncryptForUser

func EncryptForUser(recipientPublicKey, data []byte) ([]byte, error)

EncryptForUser encrypts data using the recipient's X25519 public key (NaCl SealedBox). Used for encrypting workspace keys when inviting team members.

func EncryptPrivateKey

func EncryptPrivateKey(privateKey []byte, password string) (ciphertextB64, saltHex string, err error)

EncryptPrivateKey encrypts a private key with a password-derived key. Returns (base64 ciphertext, hex salt).

func EncryptSecret

func EncryptSecret(plaintext string, workspaceKey []byte) (string, error)

EncryptSecret encrypts a plaintext secret with a workspace key using AES-256-GCM. The nonce is prepended to the ciphertext and returned as a single base64-encoded string.

func GenerateKeypair

func GenerateKeypair() (privateKey, publicKey []byte, err error)

GenerateKeypair creates a new X25519 keypair for asymmetric encryption. Returns (privateKey, publicKey) — both are 32 bytes.

func GenerateWorkspaceKey

func GenerateWorkspaceKey() ([]byte, error)

GenerateWorkspaceKey creates a random 32-byte key for AES-256-GCM encryption.

Types

type UserKeys

type UserKeys struct {
	PrivateKey          []byte // Raw 32-byte private key (stored in keyring)
	PublicKey           []byte // Raw 32-byte public key
	EncryptedPrivateKey string // Base64-encoded AES-256-GCM ciphertext of private key
	Salt                string // Hex-encoded Argon2id salt
}

UserKeys holds the output of SetupUser — everything needed to register a new account.

func SetupUser

func SetupUser(password string) (*UserKeys, error)

SetupUser generates a new keypair and encrypts the private key with the user's password. This is called during account creation (init command).

Flow:

1. Generate X25519 keypair
2. Generate random salt
3. Derive encryption key from password using Argon2id
4. Encrypt private key with AES-256-GCM using derived key