clavitor/clavis/clavis-vault/SECURITY.md

Security Principles — Clavitor Vault

The Cardinal Rule

NEVER hide security failures. Always expose them.

If decryption fails, show "[decryption failed]". Never fall back to plaintext. Never silently continue. A visible failure is a thousand times better than a hidden breach.

Non-Negotiable Rules

1. Encryption Failures Are Visible

// WRONG — silently showing plaintext
} catch (err) {
    notesDisplay = e.data.notes;  // NEVER DO THIS
}

// CORRECT — expose the failure
} catch (err) {
    notesDisplay = '[decryption failed]';
}

Same in Go:

// WRONG — returning partial data
if err != nil {
    return entry, nil  // NEVER DO THIS
}

// CORRECT — fail closed
if err != nil {
    return nil, fmt.Errorf("decryption failed: %w", err)
}

2. Fail Closed, Never Fail Open

• Encryption error? Block the operation.
• Decryption error? Return error, not plaintext.
• Authentication failure? Deny access completely.
• Invalid signature? Reject the data entirely.

3. No Silent Degradation

Never "gracefully degrade" security:

• No plaintext fallbacks
• No "optional" encryption
• No bypass modes for "convenience"
• No debug flags that disable crypto

4. Code Review Red Flags

Reject any PR that:

• Catches crypto errors and returns raw data
• Has if (err) return originalValue
• Comments say "temporary workaround" or "for debugging"
• Adds // TODO: remove this near crypto code

5. Testing Security Failures

Every security failure path must be tested:

• Corrupted ciphertext → should fail
• Wrong key → should fail
• Missing IV → should fail
• Tampered MAC → should fail

Test that failures are visible to the user, not swallowed.

Violation Log

2026-04-03 — Notes Decryption Fallback

Issue: Added plaintext fallback for failed note decryption [decryption failed] → showed raw notes. Risk: Users would see unencrypted data without knowing it was a security failure. Fix: Reverted. Now shows [decryption failed]. Lesson: Even "helpful" fallbacks can be catastrophic. Fail visibly or not at all.

The Rule In One Sentence

Security failures must be noisy, visible, and blocking — never silent, hidden, or permissive.

Violating this rule is a fireable offense in any security-critical code.