wursor/spikes/pairing-threat-model.md

Spike: pairing threat model (R9)

Status: done

Question

What stops a leaked URL from owning the site?

Done when

Written threat model that becomes the Sprint 2 / Layer 2 auth tests:

• 8+ character pairing code
• 5-minute TTL
• 5-attempt lockout
• HMAC request signing
• hashed + scoped tokens (read vs deploy)

Result

The plugin is a privileged backdoor: files, DB, WP-CLI. A leaked URL, a guessed pairing code, or a stolen bearer token is site ownership. Isolation of the sandbox does not help — this boundary is the live site.

Locked flow

Wursor generates the pairing code (bound to the signed-in account). The user pastes it into the plugin. The plugin redeems it with the site URL. Tokens are issued once.

This matches PRD §7.1.4. The Wursor_Auth::generate_pairing_code() sketch in IMPLEMENTATION.md is the wrong direction — plugin-local generate/redeem cannot bind the code to an account before the site is known. Sprint 2 tests follow this note, not that sketch.

User (signed in) → POST /sites/pair → Wursor stores pending pairing
User pastes code in plugin admin
Plugin → POST https://api.wursor…/sites/redeem { code, site_url }
Wursor binds site_url, returns read_token + deploy_token + hmac_secret (once)
Plugin stores hashes + encrypted hmac_secret
Wursor stores tokens encrypted (it must send them later)

Wursor is the HTTPS client. The plugin is the server. Tokens never appear in query strings or logs.

Protocol

Pairing code

• Alphabet: [A-Z0-9], length ≥ 8. Generate 8. 36^8 ≈ 2.8e12.
• Bound to account_id at creation. Not reusable after success.
• expires_at = created_at + 300s. Clock for tests is injectable (advance_clock).
• After 5 failed redeems on that code, locked = true. Further redeems fail even if the code is correct.
• Redeem also fails if site_url is not https or does not parse as a URL.
• One successful redeem. Second redeem of the same code fails.

Tokens

Token	Scope	Plugin endpoints
read	site-info, file read, DB read, preflight	GET only
deploy	file write, DB write, WP-CLI, prepare/commit, rollback	mutating

• 256-bit random, encoded unpadded base64url, shown once.
• Plugin stores SHA-256(token) only. Compare with hash_equals.
• Wursor stores ciphertext (envelope key, not plaintext in Postgres).
• A read token on a deploy route returns 403. A deploy token may call read routes.
• Rotation: Wursor issues a new pair; plugin replaces hashes; old hashes stop working.
• Disconnect: both hashes deleted; Wursor ciphertext deleted.

HMAC (every plugin request)

canonical = timestamp + "\n" + METHOD + "\n" + path + "\n" + hex(sha256(body))
X-Wursor-Timestamp: unix seconds
X-Wursor-Signature: hex(HMAC-SHA256(hmac_secret, canonical))
Authorization: Bearer <read_token|deploy_token>

• Reject if |now - timestamp| > 60.
• Reject if signature missing or hash_equals fails.
• hmac_secret is 256-bit, issued at redeem, stored on the plugin encrypted with the site salt (AUTH_KEY + AUTH_SALT). Not the same bytes as either token.
• Body hash is over the raw bytes. Empty body is SHA-256 of "".

Transport

• Plugin REST namespace: /wp-json/wursor/v1/.
• Plugin refuses non-HTTPS callbacks except WP_ENVIRONMENT_TYPE === 'local'.
• Wursor never puts tokens in URLs, logs, or SSE payloads.

Threats

ID	Threat	Mitigation	Residual
T1	Attacker guesses pairing codes	8+ charset, 5-try lockout, 5-min TTL	Online brute force is ~5 guesses / 5 min / code
T2	Pairing code leaked (screenshot, chat)	TTL + single use + requires wp-admin to paste	Anyone with the code and wp-admin wins until expiry
T3	Attacker redeems victim's code onto attacker site	After redeem, Wursor shows the bound site_url and requires an explicit “this is my site” confirm before the site is usable	User who confirms a foreign URL is connected to it
T4	Bearer token in a URL / access log / Referer	Tokens only in Authorization. Tests fail if any helper puts them in a query	Operator error in a future client
T5	Stolen request replayed	HMAC over timestamp+method+path+body; 60s skew window	Replay inside the window if the request was captured
T6	Stolen read token used to deploy	Scoped tokens; deploy routes require deploy	Read token still exfiltrates site-info
T7	Plugin DB dump / filesystem copy	Plugin stores hashes + encrypted hmac_secret, not raw tokens	Wursor-side ciphertext leak still lets us call the plugin until rotation
T8	MITM on HTTP	HTTPS required except local	Mis-set WP_ENVIRONMENT_TYPE on a public HTTP site
T9	CSRF in the browser against plugin REST	Bearer + HMAC. No cookie auth for /wursor/v1/	None if those headers stay required
T10	Timing leak on token compare	hash_equals only	—

Out of scope for this spike (handled elsewhere): stolen wp-admin session, compromised host, malicious plugin already on the site.

Sprint 2 tests (this note is the spec)

plugin/__tests__/test-auth.php

1. test_pairing_code_is_at_least_eight_alnum — ^[A-Z0-9]{8,}$
2. test_pairing_code_expires_after_five_minutes — advance_clock(301) → redeem false
3. test_pairing_code_valid_at_four_minutes_fifty_nine — advance_clock(299) → redeem true
4. test_locks_out_after_five_failed_attempts — five bad redeems → is_locked_out()
5. test_lockout_rejects_even_the_correct_code
6. test_successful_redeem_cannot_be_replayed
7. test_read_token_hash_is_stored_not_plaintext
8. test_read_token_forbidden_on_deploy_route → 403
9. test_deploy_token_allowed_on_site_info
10. test_hmac_rejects_stale_timestamp — timestamp older than 60s
11. test_hmac_rejects_tampered_body
12. test_hmac_rejects_missing_signature
13. test_verify_uses_hash_equals
14. test_rotated_tokens_invalidate_old_hashes

api/__tests__/services/plugin-client.test.ts

1. signs every request with timestamp + HMAC
2. sends token in Authorization, never in the URL
3. maps 401 to Authentication failed
4. refuses to construct a client with an http:// site URL outside local

api/__tests__/routes/sites-pair.test.ts

1. pair requires a session
2. redeem binds site_url and returns tokens once
3. second redeem of the same code fails
4. site is not connected until the user confirms the shown URL (T3)

Decision

• Context: plugin can own the live site; old 6-char sketch had no TTL, lockout, HMAC, or scopes.
• Options: plugin-generated code (TV pairing) vs Wursor-generated code (PRD).
• Chosen: Wursor-generated, pasted into the plugin, HMAC + scoped tokens as above.
• Rejected: plugin-local generate/redeem (cannot bind to account first; IMPLEMENTATION sketch). Tokens in query strings. Single unscope token.
• Reverted later?