Define the read-only Site Companion access contract #624

Context

Draft PR #592 predates the current gateway identity, remote access, central API security, and energy ledger contracts. Replace it from current master instead of rebasing its implementation.

This issue defines the smallest safe contract before any new endpoint or relay code lands.

Required contract

• Use the canonical gateway/site-machine identity. Do not create a second key file or identity.
• Keep local user/passkey identity separate from gateway identity. Passkey checks terminate on the local FTW instance; private passkey keys never enter FTW or a relay.
• Make remote access optional and outbound-only. FTW must keep full local operation when the service is absent.
• Define a short-lived, revocable, site- and scope-bound read-only grant. FTW must verify it locally before it exposes snapshot or history data.
• Route all remote reads through the current remote API and local access boundary. Do not add a parallel policy path.
• Reuse energy ledger schema v1 and its bounded assets/history reads. Keep its asset and point fields, distinct flow directions, and source, quality, and provenance data. Do not add a table, counter, or second history model.
• Bind requests to the local site state. Do not sign a caller-supplied site identifier.
• Keep Core safety authoritative. Future state-changing intents need semantic scope, issue and expiry times, replay protection, local checks, and the normal Core command path.

First implementation slice

Document the grant state, issue, refresh, revocation, expiry, and local verification rules. Add tests for identity separation, expiry, revocation, site/scope binding, offline operation, bounded ledger reads, and failure closed behavior.

Do not expose a Site Companion HTTP route until this auth contract and the canonical identity source can be wired through the current API boundary.

Out of scope

• Relay or hosted service implementation
• Write intents or device control
• A new gateway key or user account service
• A new energy history store
• Changes to bundled drivers, the device repository format, or its defaults

Supersedes draft PR #592.