coda-security-primitives

Production-ready security primitives for Python applications: AES-256-GCM encryption, Argon2/bcrypt/PBKDF2 password hashing, constant-time comparison, tamper-evident audit chains, rate limiting, and identity vault.

Features

• AES-256-GCM — Authenticated encryption with associated data (AAD). Key generation, encrypt/decrypt, serialization.
• Password hashing — Argon2id, bcrypt, PBKDF2-SHA256 with automatic algorithm upgrade (needs_rehash + upgrade_hash).
• Pepper layer — HMAC-SHA256 pre-hash with rotation support via SECURITY_PEPPER env var.
• Identity vault — Passphrase-protected master key vault with AES-256-GCM payload protection.
• API key manager — Salted/hashed key issuance, verification, revocation, and usage tracking.
• Iris auth — Signed assertion verification (HMAC-based, no biometric storage).
• Tamper-evident audit chain — Append-only JSONL with chained HMAC hashes. Detects insertion, deletion, reordering.
• Three-factor MFA gate — VPN CIDR, trusted device IP match, device HMAC proof, optional iris assertion.
• Rate limiting — Exponential backoff, configurable thresholds, per-identifier lockout.
• Constant-time comparison — HMAC-based to prevent timing attacks.

Quick start

from coda_security.aes_gcm import generate_aes256_key, encrypt_aes256_gcm, decrypt_aes256_gcm
from coda_security.hashing import hash_secret, verify_secret
from coda_security.rate_limit import RateLimiter
from coda_security.audit_chain import AuditChain

# Encrypt
key = generate_aes256_key()
record = encrypt_aes256_gcm(key, b"sensitive data", aad="context")
plaintext = decrypt_aes256_gcm(key, record)

# Hash
record = hash_secret("correct horse battery", preferred_algorithm="pbkdf2-sha256")
assert verify_secret("correct horse battery", record)

# Rate limit
limiter = RateLimiter(max_failures=3, cooldown_seconds=30)
if limiter.is_allowed("user:alice"):
    limiter.record_failure("user:alice")

# Audit chain
chain = AuditChain("path/to/chain.jsonl")
chain.append("user_login", subject_id="alice")
assert chain.verify().valid

Install

pip install coda-security-primitives

Optional extras:

pip install coda-security-primitives[argon2]    # Argon2id
pip install coda-security-primitives[bcrypt]     # bcrypt
pip install coda-security-primitives[all]        # everything

Architecture

coda_security/
├── aes_gcm.py              AES-256-GCM encrypt/decrypt
├── hashing.py              Argon2id / bcrypt / PBKDF2
├── pepper_manager.py       HMAC pepper with rotation
├── secure_compare.py       Constant-time comparison
├── identity_vault.py       Master key vault
├── api_key_manager.py      API key lifecycle
├── iris_auth.py            HMAC assertion verification
├── windows_hello.py        Biometric capability probe
├── audit_chain.py          Tamper-evident JSONL chain
├── network_mfa.py          Three-factor MFA gate
├── rate_limit.py           Exponential backoff limiter
├── local_secret_store.py   Windows DPAPI storage
├── password_policy.py      Configurable rules
├── security_policy.py      Central policy engine
└── exceptions.py           Typed exceptions

Security notes

• Pepper: Set SECURITY_PEPPER in production (APP_ENV=production). Rotate via SECURITY_PREVIOUS_PEPPERS (comma-separated).
• Audit chain: Does not encrypt payloads — sanitize data before appending.
• Windows DPAPI (local_secret_store): Windows-only. Provide a custom LocalSecretStore on other platforms.
• Iris auth: No biometric storage — verifies short-lived HMAC assertions from a trusted provider.

Development

git clone https://github.com/Sachitt-AV-08/coda-security-primitives.git
cd coda-security-primitives
pip install -e ".[all]"
python -m pytest tests/

License

GPL-3.0