Project: Meow Decoder Version: 1.0.0 Last Updated: 2026-02-25

"A cat always lands on its feet — and always verifies its HMAC."

This release has been internally reviewed within the scope defined in the threat model. It is not a third‑party audit. No external audit has been performed. All claims are tied to tests, specs, or formal artifacts.

Authoritative threat model: docs/THREAT_MODEL.md Protocol specification: docs/PROTOCOL.md

We implement multiple layers of supply chain protection:

Verify a release:

# Verify signature (requires cosign)
cosign verify-blob --certificate meow_decoder-1.0.0.tar.gz.crt \
  --signature meow_decoder-1.0.0.tar.gz.sig \
  --certificate-identity-regexp "github.com/systemslibrarian/meow-decoder" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  meow_decoder-1.0.0.tar.gz

We use multiple formal methods with conservative claims:

All formal verification is symbolic (Dolev‑Yao attacker model). No computational (game‑based) reductions have been performed. Specifically:

1. AES‑256‑GCM security is assumed (IND‑CPA + INT‑CTXT) — not reduced from any hardness assumption in our models.
2. Argon2id memory‑hardness is assumed — no formal proof that the KDF resists ASIC/GPU attacks at the configured cost parameters.
3. X25519 CDH hardness is assumed in the Tamarin/ProVerif models.
4. ML‑KEM IND‑CCA2 security is assumed — both ML-KEM-768 (default) and ML-KEM-1024 (paranoid mode) are modeled symbolically with an equation‑based abstraction (kem_decap(sk, kem_encap_ct(pk(sk), r)) = kem_encap_ss(pk(sk), r)).
5. PQXDH hybrid combiner uses two-step HKDF: PRK = HMAC-SHA256(0x00*32, X25519_ss || ML-KEM_ss) → HKDF-Expand(PRK, "meow_pqxdh_v1" || transcript_hash, 32). Full transcript binding (ephemeral pub, receiver classical pub, receiver PQ pub, PQ ciphertext) provides dual‑PRF security if either component is secure — this follows from HKDF's PRF property under standard assumptions (Krawczyk 2010), but we have no formal proof of the reduction.
6. Side‑channel resistance is entirely out of scope of all models.

Bottom line: The symbolic proofs verify protocol logic (no auth bypass, no secret leakage, duress OE, PQ binding). They do not verify cryptographic primitive security or implementation correctness beyond what Verus checks.

Not proven: AES‑GCM primitive correctness, side‑channel resistance, compromised host resilience, steganography detection resistance.

Reproduce:

make formal-all      # All tools locally
make formal-ci       # CI-friendly (Docker for Tamarin/Verus)

Report: docs/formal_methods_report.md Coverage map: docs/formal_coverage.md

We take security seriously — the cat guards its secrets with nine lives. If you discover a security vulnerability, please follow responsible disclosure:

✅ Email security details to: systemslibrarian@gmail.com ✅ Include detailed steps to reproduce (show us the hairball) ✅ Include version information (python3 encode.py --version) ✅ Allow us 90 days to fix before public disclosure ✅ Include any relevant logs or repro steps

❌ Post vulnerabilities publicly on GitHub Issues ❌ Exploit vulnerabilities maliciously ❌ Test on systems you don't own ❌ Demand payment without disclosure (that's not how the Catnip Bounty works!)

• 24 hours: Initial acknowledgment
• 7 days: Preliminary assessment
• 30-90 days: Fix development and testing
• After fix: Public disclosure and credit

🐱 "Find a bug, earn your catnip! The best security researchers get the finest treats."

IMPORTANT: This software is designed to protect human rights activists, journalists, and dissidents in authoritarian regimes. Finding and reporting vulnerabilities can literally save lives. We take every report seriously.

We recognize security researchers who responsibly disclose vulnerabilities:

Rewards:

• 🏅 Catnip Bounty Hall of Fame recognition
• 🐱 Meow Decoder SWAG (stickers, when available)
• 📜 Letter of paws — err, thanks / recommendation
• 🤝 First-name credit in release notes
• 📋 CVE credit for Critical/High findings (if applicable)

Tier 1 — Core Crypto (Highest Priority):

• ✅ crypto.py, crypto_enhanced.py, crypto_core/ (Rust backend)
• ✅ Key derivation (Argon2id params, HKDF usage)
• ✅ Memory protection (secure_alloc.rs, memory_guard.py)
• ✅ Constant-time operations (constant_time.py, subtle crate)
• ✅ Forward secrecy (ratchet.py, master_ratchet.py)
• ✅ Post-quantum hybrid (pq_hybrid.py)

Tier 2 — Privacy & Deniability:

• ✅ Schrödinger mode (schrodinger_encode.py, quantum_mixer.py)
• ✅ Duress mode (duress wipe, decoy handling)
• ✅ Forensic cleanup (forensic_cleanup.py)
• ✅ Secure temporary files (secure_temp.py)
• ✅ Tamper detection (tamper_detection.py)

Tier 3 — Defense in Depth:

• ✅ Environment safety (env_safety.py)
• ✅ Air gap verification (air_gap.py)
• ✅ Size normalization (size_normalizer.py)
• ✅ Timing equalization (timing_equalizer.py)
• ✅ Secure input (secure_keyboard.py, secure_input.py)
• ✅ Shamir splitting (shamir_split.py)
• ✅ Adversarial carrier noise (adversarial_carrier.py)
• ✅ Meow Capture mobile app (mobile/) — zero-network capture companion; INTERNET permission absence, FLAG_SECURE, biometric gate, panic-wipe, memory wipe on background, and per-export SHA-256 verification

Tier 4 — Protocol & Data Handling:

• ✅ Protocol parsing, manifest handling, frame verification
• ✅ Fountain codes (erasure tolerance, not crypto)
• ⚠️ Steganography (known limitations documented)
• ✅ Content expiry (expiry.py)

Out of Scope:

• ❌ Social engineering, phishing
• ❌ Physical attacks (chip decapping, TEMPEST)
• ❌ Attacks requiring compromised OS kernel
• ❌ Third-party dependencies (report upstream)

1. Duress/Real Distinguisher: Any method to distinguish duress mode from real mode without both passwords (statistical, timing, file size, metadata)
2. Memory Recovery: Key material recoverable from RAM/swap/hibernation after secure wipe
3. Schrödinger Break: Proving existence of second secret without Password B
4. Side-Channel Oracle: Timing/power attacks that leak key bits
5. Tamper Detection Bypass: Silent modification of crypto code without detection
6. Cross-File Correlation: Statistical link between multiple GIFs from same source

Rules:

• No testing on systems you don't own (respect other cats' territory)
• No exploitation of users' data (that's a bad kitty move)
• Responsible disclosure (90 days — patience of a cat stalking prey)
• One report per issue (one hairball at a time)
• Include PoC code or detailed reproduction steps

We thank the following security researchers — our elite Catnip Hunters 🌿 — for responsible disclosure:

1. No Third‑Party Audit

   • This is an internal security review, not an external audit.
   • Mitigation: Use defense in depth and independent review.

2. Python Fallback Removed

   • Rust backend is mandatory for constant-time guarantees and guaranteed memory zeroing within Rust; Python-side zeroing remains best-effort due to GC/allocator limitations
   • Mitigation: Install Rust backend as required (see README)

3. Dependency Trust

   • Relies on PyPI packages (cryptography, Pillow, etc.)
   • Mitigation: Verify package hashes, pin versions, audit dependencies

4. No Secure Enclave

   • Keys stored in process memory
   • Mitigation: Use encrypted swap, mlock, secure boot

5. Side-Channel Attacks

   • Limited mitigation for timing, power, EM attacks
   • Mitigation: Physical security, controlled environment

6. Steganography Limitations

   • Legacy (Levels 0-4): LSB embedding detectable by chi-square analysis, RS analysis, etc.
   • Localized embedding (--stego-green) may make detection EASIER
   • Mitigation: Use legacy stego for cosmetic camouflage only, rely on AES-256-GCM for security
   • See: "Localized Embedding" section below

   Multi-Layer Steganography (--multilayer-stego, v2.0):

   • Three independent channels: keyed LSB walk + STC, GIF timing, palette permutation
   • Per-frame, per-channel seed derivation (HKDF-SHA256 domain separation)
   • Syndrome-Trellis Codes minimize embedding changes (~50% vs naive LSB)
   • Adaptive texture-aware cost function penalizes smooth regions
   • Targets PSNR >55 dB, passes RS/chi-square/SPA at moderate embedding rates
   • Coercion resistance: decoy key → shallow primary only; real key → all 3 channels
   • Limitation: Not formally proven undetectable; assume well-resourced adversary with custom ML classifiers may detect. Timing/palette channels are GIF-format-specific.
   • New dep: pip install imageio[ffmpeg] required for timing/palette channels

   Adversarial Security Review (2026-02-20):

   • 8 bugs fixed: AES-GCM nonce reuse (zero-nonce→os.urandom(12)), encryption fail-open→fail-closed, Python↔Rust seed derivation mismatch, STC algorithm rewrite (GF(2) Gaussian elimination), palette encode/decode NO-OPs, payload capacity fail-open, Fisher-Yates modulo bias
   • 80 adversarial tests (tests/test_stego_adversarial.py) + 17 Hypothesis fuzz tests (tests/test_stego_fuzz.py)
   • Static analysis clean: clippy 0 warnings, Bandit clean, flake8 0 errors
   • 3,435+ total tests passing (2,462 Python + 973 Rust)
   • Strength evaluation: docs/STEGO_STRENGTH_EVALUATION.md — rated strongest vs OpenStego, Steghide, OpenPuff
   • Full audit (2026-02-20): 43/43 artifacts PASS, 252 unit tests, 11 total bugs fixed (Sessions 1-4). See docs/STEGO_AUDIT_REPORT.md.

7. Memory Forensics

   • Key zeroing helps but not perfect
   • Mitigation: Disable swap, use encrypted RAM disk, power off after use

8. Endpoint Security

   • Cannot protect against compromised OS/malware
   • Mitigation: Clean, hardened endpoints (Qubes OS, Tails)

The WASM browser demo provides identical cryptographic primitives to the CLI, but with browser-specific considerations:

The web demo provides 4 Argon2id security levels:

⚠️ CRITICAL: For life-critical data, always select "Paranoid" security level to match CLI protection.

• ❌ Hardware key support (WebAuthn planned)
• ❌ Guaranteed memory zeroing (best-effort via zeroize crate)
• ❌ Protection from malicious browser extensions
• ❌ Full steganography (canvas limitations)
• ✅ Fountain code decode for multi-frame QR (IMPLEMENTED — tolerates 33% frame loss!)

For maximum security:

1. Use private/incognito mode
2. Disable all browser extensions
3. Clear localStorage after use (or use Duress mode)
4. Close all other tabs
5. Use a hardened browser (Firefox with strict settings, Tor Browser)

1. File Size ✅

   • Length padding rounds to power-of-2 size classes
   • Attacker sees only the class (e.g., 1-2 MB), not exact size
   • Implementation: metadata_obfuscation.py:add_length_padding()

2. Manifest Contents ✅

   • All fields authenticated via HMAC-SHA256
   • block_size, k_blocks, sha256 bound to HMAC
   • AAD prevents tampering with orig_len, comp_len

3. Frame Content ✅

   • Per-frame MAC authentication (8-byte truncated HMAC)
   • Key separation: Frame MAC master key is derived via HKDF from the encryption key (binds keyfile + forward secrecy)
   • Legacy password-only frame MAC derivation remains accepted for backward compatibility during decode
   • Prevents frame injection/substitution attacks
   • Implementation: frame_mac.py

1. Approximate File Size ⚠️

   • Frame count reveals size class (~33% granularity)
   • Mitigation: Chaff frames (--chaff-frames option, not default)

2. Transfer Duration ⚠️

   • Total playback time reveals data volume
   • Mitigation: Constant-rate streaming (use --constant-rate)

3. Software Fingerprint ⚠️

   • "MEOW" magic bytes identify format
   • Mitigation: Steganography mode hides in images

4. Encoding Parameters ⚠️

   • QR size/error correction visible in images
   • Mitigation: Use standard QR parameters

5. Session Timing ⚠️

   • Bidirectional mode ACK timing reveals RTT
   • Mitigation: Random delay padding (not implemented)

For maximum metadata protection, use:

meow-encode -i secret.pdf -o secret.gif \
    --stego-mode ninja    # Hide in cat images
    --chaff-frames 20     # Add decoy frames
    --constant-rate       # Fixed timing
    --paranoid            # All obfuscation enabled

The --stego-green flag restricts LSB embedding to green-dominant pixels only (e.g., logo eyes, wave patterns). This is available via:

meow-encode -i secret.pdf -o logo.gif \
    --stego-level 3 \
    --carrier logo.png \
    --stego-green

1. Chi-square analysis still detects LSB modifications in green regions
2. Histogram analysis shows non-uniform distribution in embeddable areas
3. Concentration effect - embedding in fewer pixels means higher modification density
4. Signature pattern - consistent green-only modifications are themselves a signature

• ✅ Use for cosmetic camouflage only (reduce visible QR artifacts)
• ✅ Combine with --stego-level 3 or 4 for best visual results
• ❌ Do NOT rely on localized embedding for security
• ❌ Do NOT assume forensic undetectability

The encryption (AES-256-GCM) protects your data, not the steganography.

This project favors conservative, audited primitives and explicit key separation. Design choices are documented inline in code, and summarized here for auditors.

• AES-256-GCM: Standard AEAD with strong confidentiality + integrity. We do not implement custom modes. All metadata integrity is bound via AAD.
• Argon2id: Memory-hard KDF with high parameters to resist GPU/ASIC attacks.
• HKDF domain separation: Independent subkeys are derived for encryption, manifest HMAC, frame MACs, and ratcheting to prevent cross-protocol key reuse.
• Fail-closed behavior: Any authentication failure aborts decoding with no plaintext output. This prevents oracle behavior and partial disclosure.
• Forward secrecy (X25519): Ephemeral keys prevent future key compromise from decrypting historical data.
• PQ hybrid mode: PQ is used only for key encapsulation. If PQ is requested but unavailable, the operation fails closed to prevent silent downgrade.

When using bidirectional mode (--bidirectional), the control channel uses cryptographic authentication to prevent spoofing and replay attacks.

Key Derivation (HKDF-SHA256):

# Session key derived from shared password
# Exact parameters from bidirectional.py:194-203
auth_key = HKDF(
    algorithm=SHA256,
    length=32,                              # 256-bit key
    salt=session_salt,                      # 16-byte random (secrets.token_bytes(16))
    info=b"meow_bidirectional_auth_v1"      # Domain separation
).derive(password.encode('utf-8'))

Message Format:

┌──────────────┬────────────┬─────────────┬────────────────────┐
│ Type (1B)    │ HMAC (32B) │ Counter (8B)│ Payload (variable) │
└──────────────┴────────────┴─────────────┴────────────────────┘

Message Authentication (HMAC-SHA256):

• All control messages include HMAC: ACK, COMPLETION, STATUS_UPDATE, PAUSE, RESUME, RESEND_REQUEST
• HMAC computed over: message_type || payload (counter is in payload for replay-protected types)
• Full 32-byte HMAC (no truncation)
• Constant-time verification using secrets.compare_digest()
• Invalid HMAC → Message silently dropped (no oracle)

Replay Protection (Monotonic Counter):

# Counter window logic from bidirectional.py:280-290
replay_protected_types = [STATUS_UPDATE, COMPLETION, PAUSE, RESUME, RESEND_REQUEST]

if msg_type in replay_protected_types:
   counter = struct.unpack('>Q', payload[:8])[0]  # 8-byte big-endian
    if counter <= last_rx_counter:
        return None  # REJECT: Replay detected (silent drop)
    last_rx_counter = counter  # Accept and advance

Idempotent Message Types (No Counter):

• SESSION_ACK, FRAME_ACK are safe to replay (no state change)
• These skip counter validation

Failure Modes (Fail-Silent):

Security Properties:

• Authentication: Only parties with shared password can send valid control messages
• Integrity: Any modification to message invalidates HMAC
• Replay Prevention: Monotonic counter ensures each message unique
• Timing Safety: secrets.compare_digest() prevents timing oracle
• Fail-Silent: Invalid messages reveal no information

Meow Decoder implements fail-closed behavior for manifest integrity. Any modification to the manifest causes complete decryption failure with zero information leakage.

Cryptographic Mechanisms:

1. AES-256-GCM Authenticated Encryption

   • GCM tag binds all metadata fields
   • AAD (Additional Authenticated Data) includes:
     • Original length, compressed length, cipher length
     • Salt, nonce, SHA-256 hash
     • Magic bytes (version identifier)
     • Ephemeral public key (if forward secrecy enabled)
   • Any bit flip in AAD or ciphertext → GCM decryption fails

2. HMAC-SHA256 Manifest Authentication

   • Separate HMAC over entire manifest (excluding HMAC field itself)
   • Derived from: HKDF(password, salt, "meow_manifest_auth_v2")
   • Verified in constant-time before any decryption attempt
   • HMAC mismatch → Immediate abort, no partial output

3. Per-Frame MAC

   • 8-byte truncated HMAC per QR frame
   • Current derivation: HKDF(encryption_key, salt, "meow_frame_mac_master_v2") then per-frame HKDF with frame_index
   • Legacy compatibility: password-only derivation accepted for previously encoded files
   • Invalid frames silently dropped during decoding
   • DoS protection: Malicious frames rejected before fountain decode

Tested Attack Vectors (see tests/test_security.py::TestTamperDetection):

• ✅ Flip 1 bit in salt → Decryption fails
• ✅ Flip 1 bit in nonce → Decryption fails
• ✅ Flip 1 bit in lengths → Decryption fails
• ✅ Flip 1 bit in SHA-256 hash → Integrity check fails
• ✅ Flip 1 bit in HMAC → Authentication fails
• ✅ Swap manifest between files → HMAC mismatch, fails
• ✅ Modify ciphertext → GCM tag verification fails

Failure Behavior:

• No partial plaintext output
• No error messages revealing plaintext structure
• Generic error: "Decryption failed (wrong password/keyfile or tampered manifest)"
• Logs do NOT contain sensitive data

Proof:

# From tests/test_security.py (TestTamperDetection class)
def test_single_bit_flip_in_all_fields():
    """Flip 1 bit in every manifest field → all fail."""
    for field in ['salt', 'nonce', 'orig_len', 'comp_len', 'cipher_len', 'sha256', 'hmac']:
        modified_manifest = flip_bit_in_field(manifest, field, bit=0)
        with pytest.raises((RuntimeError, ValueError)):
            decrypt_to_raw(cipher, password, modified_manifest.salt, ...)

1. Strong Passwords

   • Use 20+ character random passwords
   • Use password managers (KeePassXC, Bitwarden)
   • Enable keyfile for 2FA

2. Secure Endpoints

   • Clean, updated, malware-free systems
   • Disable unnecessary services
   • Use full disk encryption

3. Version Selection

   • Use MEOW5 (ML-KEM-768 + X25519) as default post-quantum mode (experimental)
   • Use MEOW4 with --paranoid (ML-KEM-1024 + X25519) for maximum post-quantum protection (experimental)
   • Use MEOW3 (forward secrecy) when PQ is not needed
   • Avoid MEOW2 (legacy, no forward secrecy)

4. Operational Security

   • Verify SHA-256 after decoding
   • Securely delete source files (--wipe-source)
   • Use steganography for plausible deniability
   • Control physical access during transfer

5. Dependency Hygiene

   • Verify requirements.txt hashes
   • Use virtual environments
   • Keep dependencies updated

1. Code Review

   • All PRs require review
   • Focus on crypto-sensitive code
   • Use static analysis tools (bandit, mypy)

2. Testing

   • Maintain >80% test coverage
   • Include crypto roundtrip tests
   • Test error conditions

3. Dependency Updates

   • Monitor security advisories
   • Update dependencies promptly
   • Test after updates

4. Changelog

   • Document all security-relevant changes
   • Tag security releases clearly

We're particularly interested in reports for:

• Remote code execution
• Authentication bypass
• Key extraction vulnerabilities
• Cryptographic implementation flaws

• Denial of service
• Information disclosure
• Privilege escalation
• Side-channel attacks

• Input validation issues
• Dependency vulnerabilities
• Memory leaks

• Documentation errors
• Non-security bugs
• UI/UX issues

• ✅ Extended replay protection to all control message types
• ✅ Added pip-audit to CI for Python dependency scanning
• ✅ Empty password now triggers UserWarning in bidirectional mode
• ✅ Comprehensive control channel security tests
• ✅ Updated security documentation with metadata leakage controls

• ✅ Argon2id parameters increased to 512 MiB, 20 iterations
• ✅ Post-quantum signatures (Dilithium/FIPS 204)

• ✅ Duress mode for coercion resistance
• ✅ Enhanced entropy collection
• ✅ Multi-secret Schrödinger mode
• ✅ Hardware security integration (TPM/YubiKey)

• ✅ Schrödinger's Yarn Ball (quantum plausible deniability)
• ✅ Decoy generation

• ✅ Forward secrecy with X25519 ephemeral keys
• ✅ Frame-level MACs for DoS protection
• ✅ Constant-time operations
• ✅ Metadata obfuscation (length padding)

• ✅ Forward secrecy enabled by default (MEOW3)
• ✅ Post-quantum support added (MEOW4/MEOW5 — ML-KEM-768 default, ML-KEM-1024 paranoid)
• ✅ Enhanced steganography (Ninja Cat ULTRA)
• ✅ Streaming decode for low-memory devices
• ✅ Constant-time HMAC comparison

Read docs/THREAT_MODEL.md for:

• What we protect against (7 categories)
• What we don't protect against (7 categories)
• Adversary model analysis
• Security configuration guide

Read docs/PROTOCOL.md for:

• Manifest format specifications
• Version compatibility matrix
• Security considerations per version

Read docs/ARCHITECTURE.md for:

• System architecture diagram
• Data flow analysis
• Security boundaries
• Trust model

Subject: [SECURITY] Buffer overflow in fountain decoder

Version: 4.0
Component: fountain.py
Impact: Denial of service (crash)

Description:
When decoding with block_size=0, the decoder crashes due to
division by zero on line 123.

Steps to Reproduce:
1. Create manifest with block_size=0
2. Run decode_gif.py
3. Observe crash

Expected: Graceful error handling
Actual: Unhandled exception

Suggested Fix:
Add validation: if block_size <= 0: raise ValueError()

Contact: systemslibrarian@gmail.com

Subject: Your code sucks

Found a bug, give me $1000 or I'll publish it on Twitter.

We credit security researchers (Catnip Hunters) who:

• ✅ Follow responsible disclosure (good kitty behavior)
• ✅ Provide actionable reports (not just hissing)
• ✅ Don't exploit vulnerabilities maliciously (no claws out)

Credit options:

• 🏆 Name in the Catnip Bounty Hall of Fame
• 📝 Name in release notes ("Sniffed out by...")
• 🚨 Name in security advisory
• 🐾 Anonymous (stealth cat, if preferred)

Security Reports: systemslibrarian@gmail.com General Questions: GitHub Discussions Bug Reports: GitHub Issues (non-security only)

After a fix is released:

1. We publish a security advisory
2. We update CHANGELOG.md
3. We credit the reporter (if desired)
4. Reporter may publish their findings

Coordinated Disclosure: We prefer 90-day disclosure window.

"Be like a cat: Always land on your feet, even when vulnerabilities are found!" 😺🔐

Remember: This is experimental software. Use responsibly, report issues ethically, and always assume bugs exist. Security is a journey, not a destination — and the cat walks it on silent paws! 🐾

Last Updated: 2026-02-14 Version: 1.0.0 Status: Internal Review — No External Audit — Catnip Bounty Open