The Schema Vault uses SHA256 cryptographic hashing to ensure schema versions remain immutable and detect any tampering.
Vault Structure The vault stores versioned schemas with cryptographic integrity:
.chameleon/vault/ ├── manifest.json # Current version + history ├── integrity.log # Append-only audit trail ├── versions/ # Immutable snapshots │ ├── v001.json │ ├── v002.json │ └── v003.json └── hashes/ # SHA256 verification ├── v001.hash ├── v002.hash └── v003.hash
The vault is automatically created when you run chameleon init for the first time.
How Hash Integrity Works 1. Schema Registration When you apply a migration, ChameleonDB registers the schema version:
# Apply a migration chameleon migrate --apply 📦 Registering new schema version... ✓ Registered as v002 (hash: 7d4e1c2a... ) ✓ Parent: v001 ✅ Migration applied successfully ✅ Schema v002 locked in vault
What happens internally:
Schema content saved to versions/v002.json
SHA256 hash computed from the JSON content
Hash saved to hashes/v002.hash
Manifest updated with new version metadata
Event logged to integrity.log
2. Automatic Verification Before every operation , ChameleonDB verifies integrity:
chameleon migrate 🔍 Verifying schema integrity... ✓ Current: v001 (3f2a8b9c...) ✓ No tampering detected
Verification process: for each version in vault { stored_hash := read ( "hashes/v{version}.hash" ) content := read ( "versions/v{version}.json" ) computed_hash := SHA256 ( content ) if stored_hash != computed_hash { return INTEGRITY_VIOLATION } }
3. Tamper Detection If someone modifies a vault file, the hash check fails:
chameleon migrate ❌ INTEGRITY VIOLATION DETECTED • v001.json: hash mismatch 🚨 Schema vault has been modified! ❌ Migration aborted for safety
When an integrity violation is detected, all schema operations are immediately blocked until the issue is resolved.
manifest.json Structure The manifest tracks all registered versions:
{ "current_version" : "v002" , "versions" : [ { "id" : "v001" , "hash" : "3f2a8b9c1d4e5f6a7b8c9d0e1f2a3b4c" , "timestamp" : "2026-02-20T10:30:00Z" , "author" : "dperalta" , "parent" : null , "changes" : "Initial schema" }, { "id" : "v002" , "hash" : "7d4e1c2a3b4c5d6e7f8a9b0c1d2e3f4a" , "timestamp" : "2026-02-20T15:45:00Z" , "author" : "dperalta" , "parent" : "v001" , "changes" : "Added age field to User" } ] }
Version Snapshots Each version file contains a complete schema snapshot:
versions/v001.json: { "version" : "v001" , "entities" : [ { "name" : "User" , "fields" : [ { "name" : "id" , "type" : "uuid" , "constraints" : [ "primary" ] }, { "name" : "email" , "type" : "string" , "constraints" : [ "unique" ] }, { "name" : "name" , "type" : "string" } ] } ] }
Version files are immutable . Once written, they should never be modified. Any modification is detected as tampering.
integrity.log (Audit Trail) All vault operations are logged:
2026-02-23T10:30:00Z [INIT] vault_created version=v001 2026-02-23T10:30:00Z [REGISTER] schema_registered version=v001 hash=3f2a8b9c... 2026-02-23T10:35:00Z [MIGRATE] migration_applied version=v001 tables_created=3 2026-02-23T15:45:00Z [REGISTER] schema_registered version=v002 hash=7d4e1c2a... parent=v001 2026-02-23T15:45:00Z [MIGRATE] migration_applied version=v002 columns_added=1 2026-02-24T09:00:00Z [VERIFY] integrity_check status=ok versions_checked=2
Log format: <timestamp> [<event_type>] <event_details>
Event types:
INIT - Vault creationREGISTER - New version registeredMIGRATE - Migration appliedVERIFY - Integrity verificationMODE_CHANGE - Integrity mode changedVIOLATION - Integrity violation detected
The integrity.log file is append-only . It should never be modified or deleted. Monitor this file for unexpected entries.
Verifying Vault Integrity Manual Verification # Verify all vault files chameleon verify 🔍 Verifying vault integrity... ✓ Checking v001... OK (3f2a8b9c...) ✓ Checking v002... OK (7d4e1c2a...) ✓ Checking v003... OK (9a1b2c3d...) ✅ All versions verified ✅ No tampering detected
View Version History # View all registered versions chameleon journal schema 📖 Schema Version History v002 (current) ✓ ├─ Hash: 7d4e1c2a... ├─ Date: 2026-02-20 15:45:00 ├─ Author: dperalta ├─ Changes: Added age field to User └─ Parent: v001 v001 ├─ Hash: 3f2a8b9c... ├─ Date: 2026-02-20 10:30:00 ├─ Author: dperalta ├─ Changes: Initial schema └─ Parent: none
View Specific Version # View details for v002 chameleon journal schema v002 📦 Version v002 Hash: 7d4e1c2a3b4c5d6e7f8a9b0c1d2e3f4a Date: 2026-02-20 15:45:00 Author: dperalta Parent: v001 Changes: Added age field to User Entities: - User (4 fields ) - Post (5 fields )
Integrity Violation Recovery If tampering is detected:
Step 1: Identify the Issue chameleon verify ❌ INTEGRITY VIOLATION v001.json: hash mismatch Expected: 3f2a8b9c1d4e5f6a7b8c9d0e1f2a3b4c Got: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d
Step 2: Review Integrity Log cat .chameleon/vault/integrity.log | tail -20 # Look for unexpected entries
Step 3: Restore from Backup Always maintain backups of .chameleon/vault/ in version control or secure storage.
# Restore from Git git checkout .chameleon/vault/ # Or restore from backup cp -r backup/.chameleon/vault/ .chameleon/vault/ # Verify chameleon verify
Step 4: Investigate Access Check who modified the files:
# On Linux/macOS ls -la .chameleon/vault/versions/ ls -la .chameleon/vault/hashes/ # Review system logs sudo grep "v001.json" /var/log/audit/audit.log
Step 5: Rotate Passwords # Change mode password immediately chameleon config auth set-password Enter new password: ******** ✅ Mode password updated
Best Practices Never manually edit vault files - Use CLI commands only
Commit vault to version control - Except auth/ directory
Monitor integrity.log - Set up alerts for violations
Run verify before deployments - Ensure vault integrity
Backup vault regularly - Automated backups recommended
Next Steps
Mode Enforcement Learn about ring-based access control
Best Practices Security recommendations for production