feat(plugin): aircraft — optional OpenSky OAuth2 credentials

[Kohei-Wada]

Second half of OpenSky API-key support, built on #392 (ttymap.http POST/headers). Pure Lua — no aircraft-specific Rust.

What

OpenSky moved to OAuth2 client-credentials in 2025; anonymous access is capped at 400 credits/day (a ~10°×10° /states/all call costs ~2). Authenticate to lift the cap to 4000/day (8000 if you feed the network).

Set credentials in ~/.config/ttymap/init.lua:

local aircraft = require("ttymap.aircraft")
aircraft.client_id     = "your-client-id"
aircraft.client_secret = "your-client-secret"

Leave unset for anonymous access (unchanged default).

How

• runtime/lua/ttymap/aircraft.lua — new config-holder lib (same nvim-style pattern as ttymap.here); the plugin reads the fields lazily at fetch time.
• opensky.lua — token state machine (poll_auth, driven once per tick): drains an async token POST (via the new http:fetch(url, {method="POST", form=...})), caches the Bearer token, refreshes ~1 min before its expires_in (~30 min) lapses, and backs off ~60 s on failure so bad credentials don't hammer the token endpoint every frame. fetch_states adds Authorization: Bearer once a token is in hand, else anonymous GET.
• init.lua — on_tick calls opensky.poll_auth() and fetches via opensky.fetch_states(...).

Verification

• luac -p on all three Lua files.
• Booted the real subsystem via build_subsystem (throwaway test) to confirm plugin.aircraft (now requiring ttymap.aircraft) loads and registers — "Toggle aircraft" lands in the registry.
• cargo test (full workspace), clippy --all-targets, fmt --check pass.
• Not exercised live: an actual authenticated OpenSky round-trip (needs real credentials + network). The token-flow logic is Lua; the HTTP transport it rides was tested in feat(lua): ttymap.http:fetch opts — POST, headers, form body #392.

[amazon-q-developer]

Summary

This PR successfully implements OAuth2 client-credentials authentication for the OpenSky Network API in pure Lua, enabling users to lift rate limits from 400 to 4000+ credits/day. The implementation includes a config holder module, token state machine with automatic refresh, and graceful fallback to anonymous access.

Critical Changes Requested

Security (1 issue):

• The configured() function must validate that credentials are non-empty strings, not just non-nil, to prevent authentication failures that trigger unnecessary token endpoint requests every 60 seconds

Architecture

The implementation follows sound patterns:

• Lazy credential reading allows init.lua configuration
• Token refresh logic with 60-second backoff on failure prevents endpoint hammering
• Proper separation of concerns across three modules
• Graceful degradation to anonymous access when unconfigured

Testing Notes

Per PR description, the OAuth flow itself hasn't been exercised with live credentials. Recommend manual testing with actual OpenSky OAuth2 credentials before merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[amazon-q-developer]

🛑 Security Vulnerability: Validate OAuth2 credentials before sending to prevent potential injection or malformed request issues. The configured() function only checks for nil but accepts empty strings, which will cause authentication failures that hammer the token endpoint every 60 seconds (backoff timer at line 83). Additionally, credentials aren't sanitized before being sent in the POST form body.¹

Add validation to ensure credentials are non-empty strings and potentially sanitize them to prevent injection attacks.

Suggested change

	local function configured()
	return cfg.client_id ~= nil and cfg.client_secret ~= nil
	end
	local function configured()
	return cfg.client_id ~= nil and cfg.client_secret ~= nil
	and type(cfg.client_id) == "string" and type(cfg.client_secret) == "string"
	and cfg.client_id ~= "" and cfg.client_secret ~= ""
	end

Footnotes

1. CWE-20: Improper Input Validation - https://cwe.mitre.org/data/definitions/20.html ↩