Engineering Case Studies & Technical Deep Dives
Production-grade architectural blueprints, threat mitigation models, protocol handshakes, and algorithmic implementations for published developer tooling and enterprise systems.
@damisile_ayoola/envvault
Zero-Dependency AES-256-GCM Secret Management with In-Memory Process Injection
Threat Vector & Problem
Plaintext .env files are notoriously vulnerable to accidental staging (git add .), TOCTOU (Time-of-Check to Time-of-Use) filesystem tampering, and cold storage swap extraction. Most secrets tooling requires heavy cloud runtime daemons or leaves temporary decrypted artifacts on disk.
Architectural Solution
A zero-dependency CLI written strictly atop Node's native crypto module. Uses PBKDF2 (SHA-512, 100,000 iterations) for key stretching, authenticated AES-256-GCM for ciphertext and tag generation, and child process in-memory IPC injection (process.env) so plaintext passwords never touch the filesystem.
┌────────────────────────┐ ┌───────────────────────────────┐ ┌─────────────────────────────┐
│ Master Passphrase (CLI) │ ───> │ crypto.pbkdf2Sync (SHA-512) │ ───> │ 256-bit Symmetric Key (KDK) │
└────────────────────────┘ │ Iterations: 100,000 │ └──────────────┬──────────────┘
│ Salt: crypto.randomBytes(32) │ │
└───────────────────────────────┘ ▼
┌────────────────────────┐ ┌───────────────────────────────┐ ┌─────────────────────────────┐
│ Plaintext Environment │ ───> │ AES-256-GCM Cipher Instance │ <─── │ 96-bit Random IV (GCM Nonce)│
│ Key=Value Stream │ │ + 128-bit Auth Tag (MAC) │ └─────────────────────────────┘
└────────────────────────┘ └──────────────┬────────────────┘
│
▼
┌───────────────────────────────────┐
│ .env.vault Encrypted File Payload│
│ [salt: 32B][iv: 12B][tag: 16B] │
│ [ciphertext: Variable Length] │
└────────────────┬──────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ envvault run -- <cmd> (In-Memory Subprocess Pipeline): │
│ 1. Read .env.vault -> Decrypt into volatile Buffer -> Parse Key-Value pairs │
│ 2. child_process.spawn(cmd, { env: { ...process.env, ...decryptedSecrets }, stdio: 'inherit' }) │
│ 3. Buffer zeroization / GC -> Subprocess terminates -> ZERO PLAINTEXT TOUCHED DISK │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
| Component | Specification & Implementation | Security Rationale |
|---|---|---|
| Symmetric Cipher | AES-256-GCM (Authenticated Encryption with Associated Data) | Prevents bit-flipping attacks via mandatory 128-bit GHASH authentication tag validation before decryption. |
| Key Derivation (KDF) | PBKDF2-HMAC-SHA512 (100,000 iterations, 32-byte cryptographically secure random salt) | Resistant to high-speed GPU/ASIC rainbow table dictionary attacks. Compliant with NIST SP 800-132 recommendations. |
| Process Injection | child_process.spawn with ephemeral in-memory environment dictionary |
Eliminates disk I/O vulnerabilities (tempfiles, swap file dumping, inode retention). Passwords exist exclusively in child process virtual memory. |
| Pre-Commit Security Linter | envvault audit + automated Git hook injection into .git/hooks/pre-commit |
Inspects git staged index via entropy heuristics and regex patterns to proactively block raw API tokens before git push. |
fixmcp
Autonomous JSON-RPC 2.0 Stdio Diagnostic Doctor & Configuration Repair Utility
Protocol Failure Mode
Model Context Protocol (MCP) clients (Claude Code, Cursor, Windsurf, VS Code) spawn server subprocesses via stdio. Configurations are fractured across OS-specific JSON files. When a server crashes or times out (error -32001) due to npx @latest registry round-trips or invalid JSON schemas, AI clients fail silently at boot without informative stack traces.
Diagnostic Engine
Discovers configs across 6 major AI agent environments, validates JSON syntax, and spawns real stdio sub-processes to execute active JSON-RPC 2.0 handshakes (initialize & tools/list). Times latency, counts registered capabilities, and provides an idempotent --fix runner that creates automated backups and normalizes paths.
[fixmcp Discovery Engine]
├── Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
├── Claude Code: ~/.claude.json
├── Cursor: %APPDATA%/Cursor/User/globalStorage/saoudrizwan.claude-dev/.../mcp.json
├── Windsurf: ~/.codeium/windsurf/mcp_config.json
└── VS Code: ~/.config/Code/User/globalStorage/.../mcp.json
│
▼
[JSON Syntax & Path Verification] ──(Syntax Error)──> [Automated Backup & AST Normalizer]
│
▼
[Subprocess Spawner via stdio IPC]
│
├──> Outgoing: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
│
├──< Incoming: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{}}}}
│
├──> Outgoing: {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
│
└──< Incoming: {"jsonrpc":"2.0","id":2,"result":{"tools":[...14 tools]}}
│
▼
[Diagnostic Health Matrix]
├── ✔ Handshake latency: 124ms
├── ✔ Active Tool Schemas Verified: 14 tools
└── ✖ High Latency Warning: server using 'npx -y pkg@latest' -> Suggest pinned local binary
| Capability | Implementation Details | Diagnostic Impact |
|---|---|---|
| Multi-Agent Discovery | Cross-platform path resolver mapping Windows (%APPDATA%), macOS (~/Library), and Linux (~/.config) |
Locates configurations across Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code without user input. |
| Live stdio Handshake | Node child_process.spawn with custom line-buffered stream parser over stdin/stdout |
Differentiates between binary crashes, missing PATH binaries, missing environment variables, and protocol-level schema violations. |
| Timeout & Deadlock Protection | Promise-race timer with configurable 5000ms threshold per server | Pinpoints servers failing the Model Context Protocol initialization timeout (standard error -32001). |
| Automated Remediation Engine | npx fixmcp --fix with timestamped atomic file backups (.backup-YYYYMMDD.json) |
Replaces unpinned @latest commands with local binaries, strips trailing commas, and repairs broken Windows path backslashes. |
checkIn — Biometric & Geofenced Attendance System
Production Platform for the School of Logistics and Innovation Technology (FUTA SLIT)
Real-World Constraints
University lecture halls with 200+ students encounter major failure points: hardware fingerprint queues take 45+ minutes, buddy-punching (proxy attendance) undermines trust, and unstable cellular/Wi-Fi connectivity causes high network dropped-packet rates when submitting data to cloud backends.
Multi-Tier Verification Architecture
Decentralizes verification to student smartphones. Extracts 468 3D facial landmarks directly on the client using WebAssembly MediaPipe (zero video streaming over network, preserving bandwidth and privacy), enforces a 50m Haversine GPS fence around the lecturer, and stores check-ins inside an offline IndexedDB queue with automatic background sync.
Calculates great-circle distance between student GPS coordinate $(lat_1, lon_1)$ and lecturer coordinate $(lat_2, lon_2)$:
a = sin²(Δlat/2) + cos(lat₁) · cos(lat₂) · sin²(Δlon/2)
c = 2 · atan2(√a, √(1−a))
d = R · c (where R = 6,371,000 meters)
Threshold Assertion:
d <= 50.0m ──> GPS Boundary Verified
d > 50.0m ──> Location Spoofing Rejected
Cosine similarity across 3D normalized landmark vectors $\mathbf{u}$ and $\mathbf{v}$:
Similarity = (u · v) / (||u|| ||v||)
3-Tier Decision Matrix:
• Similarity >= 0.50 ──> Verified Present (Instant Success)
• 0.40 <= Sim < 0.50 ──> Flagged for Manual Admin Review
• Similarity < 0.40 ──> Fraud Rejection (Identity Mismatch)
[Student Camera & GPS Check-In Triggered]
│
▼
[Edge Verification: MediaPipe Mesh & Haversine Distance Calculated Locally]
│
▼
[Network Check: navigator.onLine]
├── ONLINE ──> [Direct HTTPS POST to PostgreSQL API Endpoint] ──> [Attendance Confirmed]
│
└── OFFLINE (Campus Network Drop)
│
▼
[IndexedDB 'idb' ObjectStore Transaction]
Store payload: { studentId, sessionId, timestamp, biometricScore, gpsDelta, nonce, syncStatus: 'pending' }
│
▼
[Service Worker / Window 'online' Event Listener Triggered]
│
▼
[Idempotent Drain Queue Worker]
Sequentially reads pending records -> Sends batch POST with unique idempotency nonces ->
Server acknowledges write -> Record updated to syncStatus: 'synced' -> UI reflects verified state.
Looking for Deep Engineering & Systems Design?
I am actively interested in software engineering roles, distributed systems, open-source tooling, and security architecture. Let's discuss engineering challenges.