chameleon verify

Synopsis

chameleon verify

Run comprehensive integrity checks on the Schema Vault.

Description

The verify command performs cryptographic verification of the Schema Vault to detect:

Manifest tampering - Modified or corrupted manifest.json
Version file tampering - Modified version snapshots
Hash mismatches - Schema files that don’t match stored hashes
Missing files - Deleted vault files
Inconsistent state - Schema files out of sync with versions

This command is used to:

Audit vault integrity
Detect unauthorized changes
Verify schema authenticity
Troubleshoot migration issues

Examples

All Checks Passed

chameleon verify

Output:

🔍 Running Integrity Verification...

Vault:

  ✓ manifest.json is valid
  ✓ v001 integrity OK
  ✓ v002 integrity OK
  ✓ No tampering detected

Schema Files:
  ✓ schema *.cham exists
  ✓ Matches v002 hash

✅ All checks passed

Integrity Violation Detected

chameleon verify

Output:

🔍 Running Integrity Verification...

Vault:

  ✓ manifest.json is valid
  ✓ v001 integrity OK
  ❌ v002 integrity FAILED
     Hash mismatch: expected 7d4e1c2a..., got a1b2c3d4...

Schema Files:
  ✓ schema *.cham exists
  ⚠️  Modified (not matching v002)

❌ 1 integrity issues found

🔧 Recovery options:
   • Check integrity.log for audit trail
   • Review recent changes to vault files
   • Contact your DBA if tampering is suspected

No Vault Found

chameleon verify

Output:

❌ No vault found
   Run 'chameleon migrate' to initialize

What Gets Verified

1. Vault Manifest

Checks .chameleon/vault/manifest.json:

Valid JSON structure
Required fields present
Current version references exist

2. Version Files

For each version in .chameleon/vault/versions/:

Version file exists (e.g., v001.json)
Hash file exists (e.g., .chameleon/vault/hashes/v001.hash)
Computed hash matches stored hash

3. Schema Files

Verifies merged schema:

Schema file exists at configured path
Hash matches current vault version (if applicable)

4. Integrity Log

Checks .chameleon/vault/integrity.log:

File is append-only
No suspicious modifications

Vault Structure

.chameleon/vault/
├── manifest.json       # Current version + history
├── integrity.log       # Append-only audit trail
├── versions/           # Immutable snapshots
│   ├── v001.json
│   └── v002.json
└── hashes/             # SHA256 verification
    ├── v001.hash
    └── v002.hash

Verification Process

Step 1: Load Manifest

Vault:
  ✓ manifest.json is valid

Step 2: Verify Each Version

For each version:

Read version file (e.g., v001.json)
Compute SHA256 hash of contents
Compare with stored hash in v001.hash
Report OK or FAILED

  ✓ v001 integrity OK
  ✓ v002 integrity OK

Step 3: Check Tampering

  ✓ No tampering detected

Or if issues found:

  ❌ 2 integrity issues found

Step 4: Verify Schema Files

Checks if current schema matches vault:

Schema Files:
  ✓ schema *.cham exists
  ✓ Matches v002 hash

Or if modified:

Schema Files:
  ✓ schema *.cham exists
  ⚠️  Modified (not matching v002)

Common Scenarios

After Migration

chameleon migrate --apply
chameleon verify

Output:

✓ v001 integrity OK
✓ v002 integrity OK (newly created)
✅ All checks passed

After Manual Vault Edit

If someone manually edits .chameleon/vault/versions/v002.json:

chameleon verify

Output:

❌ v002 integrity FAILED
   Hash mismatch

❌ 1 integrity issues found

After Schema Edit (Not Yet Migrated)

Edit schemas/users.cham but don’t migrate:

chameleon verify

Output:

✓ v001 integrity OK
✓ v002 integrity OK
  
Schema Files:
  ✓ schema *.cham exists
  ⚠️  Modified (not matching v002)

✅ All checks passed

Modified schema files are expected during development. This is not an error until you run migrate --apply.

Integrity Log

View detailed audit trail:

cat .chameleon/vault/integrity.log

Example output:

[2026-03-03T10:30:00Z] INIT vault initialized
[2026-03-03T10:32:15Z] REGISTER v001 hash=3f2a8b9c...
[2026-03-03T14:25:30Z] REGISTER v002 hash=7d4e1c2a... parent=v001
[2026-03-03T14:25:31Z] MIGRATE v002 status=applied duration=23ms
[2026-03-03T15:10:00Z] VERIFY status=ok

Recovery Options

If Vault is Corrupted

Check integrity log:
cat .chameleon/vault/integrity.log
Review recent changes:
git log .chameleon/vault/

Restore from backup:

cp -r .chameleon/backups/vault-2026-03-03/ .chameleon/vault/

Contact DBA if tampering suspected

If Schema File is Missing

# Regenerate merged schema
chameleon migrate --check

This will recreate .chameleon/state/schema.merged.cham.

Integration with Migrate

The migrate command automatically runs integrity verification:

chameleon migrate --apply

Output includes:

ℹ Verifying schema integrity...
✓ Current version: v002 (7d4e1c2a...)
✓ No tampering detected

If verification fails, migration is aborted:

❌ INTEGRITY VIOLATION DETECTED
  • v002.json: hash mismatch

❌ Migration aborted for safety

Exit Codes

0 - All integrity checks passed
1 - Integrity violations found or vault not initialized

Automated Verification

Daily Cron Job

# /etc/cron.daily/chameleon-verify
#!/bin/bash
cd /var/app
chameleon verify || mail -s "Vault integrity failed" admin@example.com

CI/CD Pipeline

# .github/workflows/verify.yml
name: Verify Vault
on:
  schedule:
    - cron: '0 0 * * *'  # Daily
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify vault
        run: chameleon verify

Troubleshooting

Cannot Load Manifest

❌ Failed to load manifest: no such file or directory

Solution: Vault not initialized. Run:

chameleon migrate

Permission Denied

❌ Failed to read vault files: permission denied

Solution: Ensure read permissions:

chmod -R u+r .chameleon/vault/

Commands

Synopsis

Description

Examples

All Checks Passed

Integrity Violation Detected

No Vault Found

What Gets Verified

1. Vault Manifest

2. Version Files

3. Schema Files

4. Integrity Log

Vault Structure

Verification Process

Step 1: Load Manifest

Step 2: Verify Each Version

Step 3: Check Tampering

Step 4: Verify Schema Files

Common Scenarios

After Migration

After Manual Vault Edit

After Schema Edit (Not Yet Migrated)

Integrity Log

Recovery Options

If Vault is Corrupted

If Schema File is Missing

Integration with Migrate

Exit Codes

Automated Verification

Daily Cron Job

CI/CD Pipeline

Troubleshooting

Cannot Load Manifest

Permission Denied

See Also

​Synopsis

​Description

​Examples

​All Checks Passed

​Integrity Violation Detected

​No Vault Found

​What Gets Verified

​1. Vault Manifest

​2. Version Files

​3. Schema Files

​4. Integrity Log

​Vault Structure

​Verification Process

​Step 1: Load Manifest

​Step 2: Verify Each Version

​Step 3: Check Tampering

​Step 4: Verify Schema Files

​Common Scenarios

​After Migration

​After Manual Vault Edit

​After Schema Edit (Not Yet Migrated)

​Integrity Log

​Recovery Options

​If Vault is Corrupted

​If Schema File is Missing

​Integration with Migrate

​Exit Codes

​Automated Verification

​Daily Cron Job

​CI/CD Pipeline

​Troubleshooting

​Cannot Load Manifest

​Permission Denied

​See Also

Synopsis

Description

Examples

All Checks Passed

Integrity Violation Detected

No Vault Found

What Gets Verified

1. Vault Manifest

2. Version Files

3. Schema Files

4. Integrity Log

Vault Structure

Verification Process

Step 1: Load Manifest

Step 2: Verify Each Version

Step 3: Check Tampering

Step 4: Verify Schema Files

Common Scenarios

After Migration

After Manual Vault Edit

After Schema Edit (Not Yet Migrated)

Integrity Log

Recovery Options

If Vault is Corrupted

If Schema File is Missing

Integration with Migrate

Exit Codes

Automated Verification

Daily Cron Job

CI/CD Pipeline

Troubleshooting

Cannot Load Manifest

Permission Denied

See Also