Apple TV handoff
Implementation contracts and behavior for apple tv handoff.
internal/appletv owns live session checks, encrypted Companion credentials,
per-TV adult grants, bounded PIN sessions, and title handoffs. /api/config
advertises apple_tv_remote when these routes are wired; the TV list reports
whether the runtime helper is installed. Older apps ignore the optional field,
and newer apps hide the controls when talking to older servers.
The pinned Python worker under tools/apple_tv discovers the TV again for each
operation and checks its stable identity before using credentials. Address
queries that find no TV retry multicast discovery, restricted to that address,
so an mDNS relay works for pairing and reconnects across subnets. It connects
and checks Infuse, then waits on a private pipe while Go rechecks the current
session, adult status, TV grant/revision, and canonical title access through
mediaaccess.AuthorizeAppleTVTitle. Only then does Go authorize the command.
Per-TV actions reject concurrent attempts instead of queuing them. Confirm Open
is bound to that launch, caller session, and revision, with a 30-second lifetime
checked again before Select. Neither launch nor confirmation is retried.
Credentials and PINs use private stdio, never arguments, environment variables, logs, or helper storage files. Pairing credentials use the existing encrypted DB storage; pending pairings and confirmations are memory-only. The worker opens no listener and all its network traffic uses direct internal LAN sockets. Both Dockerfiles bundle the locked helper and dependency notices. See Apple TV setup for pairing, networking, and manual installs.