Security Model

How WindowsHelper protects your PC + your phone, what cryptography we use, and what we explicitly don't defend against. Last updated: 2026-04-25.

Pairing-code lifecycle

The pairing code is the shared secret every other crypto operation derives from. The full lifecycle:

[ Phone GENERATES random 8-char code ]
   ↓
[ Phone WRITES code + sessionId to Firestore in pc_connections doc ]
   ↓
[ Phone DISPLAYS code to user on screen ]
   ↓
[ User READS code, types it into companion's input field ]
   ↓
[ Companion QUERIES Firestore for waiting session matching the code ]
   ↓
[ Both sides DERIVE crypto keys from SHA-256(code, sessionId) ]
   ↓
[ Code STAYS in memory on both sides; never written to Firestore by either ]
   ↓
[ Disconnect / re-pair WIPES the code from both sides ]

• Random: codes generated via cryptographically secure RNGs.
• 32-char alphabet × 8 positions ≈ 1.1 trillion combinations. Excludes I/O/0/1 to avoid visual ambiguity, not security significance — the codespace is dense enough that a 5-minute brute-force window with Firestore rate limits is infeasible.
• Never written to Firestore by either side. Only the WAITING session doc carries pairingCode; once paired, the code stays in memory exclusively.
• In-memory wipe on disconnect, re-pair, or app close.

Cryptography

AES-256-GCM (command confidentiality + integrity)

Every command sent over the wire is encrypted with AES-256-GCM, an authenticated-encryption mode.

• Key: 256 bits, derived as SHA-256("WH_SECURE_{code}_{sessionId}_CMD_KEY").
• Nonce: 96 bits (12 bytes), generated freshly per-message via Random.secure() on phone or RandomNumberGenerator on companion.
• Auth tag: 128 bits (16 bytes), appended to the ciphertext.
• Wire format: AESGCM:<nonce_b64>:<ciphertext_b64>:<tag_b64>
• Nonce-reuse safety: 96-bit nonces from a CSPRNG give a birthday-paradox collision probability of ~2⁻³² after 2⁴⁸ messages — astronomically out of reach for any plausible command volume.

HMAC-SHA256 (command authenticity)

Every command also carries an HMAC signature so a phone that doesn't know the pairing code cannot inject commands even if it can write to Firestore.

• Key: 256 bits, derived as SHA-256("WH_SECURE_{code}_{sessionId}_HMAC_KEY"). Separate from the encryption key.
• Field scope: HMAC-SHA256(hmacKey, commandId | ciphertext | sentAtMillis). The pipes are literal pipe characters, not delimiters — three concatenated strings.
• Verification order: HMAC verified before decryption. Forged messages waste zero CPU cycles on cryptographic primitives.

Threat model

Threat	Status	Notes
Eavesdropper on the local network	Mitigated	AES-GCM ciphertext is opaque to MITM observers.
Eavesdropper on Firestore servers	Mitigated	Google sees AESGCM:... blobs, not commands.
Attacker who can write to Firestore but doesn't know the code	Mitigated	HMAC verification fails; companion logs the rejection + refuses execution.
Attacker who cracked / phished the pairing code	Residual	They can issue commands as if they were the user. Mitigation: rotate the code from the tray menu.
Replay of a recorded command	Residual	sentAtMillis is HMAC-bound; companion doesn't yet enforce a freshness window. Future fix adds a TTL.
LAN-mode unauthenticated attacker	Mitigated	WebSocket pair handshake validates the code; HMAC + AES gate every subsequent command.
Compromised phone with stolen pairing key	Residual	Indistinguishable from "the user themselves." Mitigation: rate limit (10 cmd/min) + destructive-command confirmation requires PC-side click.
Mistyped command from phone app	Mitigated	Phone-side allowlist blocks unrecognized prefixes; companion-side pre-flight blocks commands targeting nonexistent services.
Destructive command run accidentally	Mitigated	Companion-side modal requires user click to approve Remove-Item, Format-Volume, reg delete, shutdown /r, etc.
Hung / runaway PowerShell process	Mitigated	Hard 5-minute timeout kills the entire process tree.
Companion .exe tampering between download and run	Mitigated	SHA-256 published in companion-version.json; users can verify. Authenticode signing landing soon.
Companion crash leaking sensitive state	Mitigated	Crash reports + Firestore error writebacks sanitize %USERPROFILE% / %MACHINE% / %USER%.
Stolen device, persisted Registry pairing key	Residual	An attacker with disk + login access could read the persisted code. Future fix wraps it with Windows DPAPI.

Out of scope

Things WindowsHelper explicitly does not defend against:

• Compromised Windows account running the companion. We assume the user's PC is theirs. An attacker with admin on the user's PC has already won.
• Compromised phone app binary. We don't sign Android/iOS builds against tampering beyond what the platform's app store provides.
• State-level adversaries with the resources to subvert Google's Firestore or DigiCert's PKI. This product targets consumer-grade threats — script kiddies, casual snoopers, disgruntled household members — not governments.
• Side-channel attacks on AES-GCM via power / EM analysis. The companion isn't a smartcard.

Disclosure

• Email windowshelperprogram@gmail.com with subject [security].
• Please include version numbers, repro steps, impact, and ideal fix.
• First response within 48 hours. Triaged severity within one week. High-severity issues get an out-of-cycle release.
• Disclosure window: 90 days from initial report, or earlier by mutual agreement.
• No paid bug bounty currently — we credit reporters in release notes (with permission).