feat(cloud): FTW Cloud C2: signed uplink, grant routes and wire format

[frahlg]

FTW Cloud step C2 on the box: the wire format in go/protocol, the signed uplink, and the grant routes. The box streams a signed, readable copy of its state to ftwcloudd, which keeps it in memory. FTW Cloud reads and never controls. Decision and normative wire format: ADR 0008 and docs/protocol-cloud.md (draft). Builds on #1588.

Contract-pair: srcfl/ftw-webapp@claude/cloud-c2-registry

Paired pull requests

• srcfl/ftw-webapp: srcfl/ftw-webapp#81 (the registry names, source of the contract copy)
• srcfl/ftw-app: srcfl/ftw-app#15 (the registry copy and Swift names ContractTests needs)
• srcfl/ftw-cloud: not opened yet: creating the public repository srcfl/ftw-cloud needs the owner's go-ahead in this session; the code is ready on a local branch (ftwcloudd, first version)

What changes

go/protocol/cloudwire (Apache-2.0, imports nothing from the box):

• The unpadded lane 1 frame, the {t, b, sig} envelope and its ES256 rule over ftw.cloud.v1\0 ‖ CBOR([home, t, b]), home ids, opaque source and loadpoint ids, the message bodies and the scope of each class.
• Fields is the allowlist: one table per class and per nested shape. TestEveryFieldHasARow fails when a body grows a field without a row, and TestFieldsMatchTheProtocolDocument compares the tables with docs/protocol-cloud.md once docs: propose FTW Cloud (ADR 0008) and its protocol #1589 lands (it skips until then; it passes against docs: propose FTW Cloud (ADR 0008) and its protocol #1589's text today).
• Golden vectors in testdata/cloud-vectors.json, which srcfl/ftw-cloud and the phone replay.
• View: the phone's freshness rules as a reference, with 13 of the protocol's 16 cases as tests (10, 11 and 15 are the same rules seen from lp, the budget and the notification extension).

go/internal/cloudlink (the uplink):

• Off until an owner grants it. A grant whose key fingerprint does not match cloud.key reads as off, with a notice.
• One WebSocket, TLS 1.3, no proxy from the environment. The box sends only hello until the service has signed a hello_ok bound to this TLS session's exporter value and the box's nonce.
• Every message signed with cloud.key, with seq, boot, uptimeMs, and wallMs while NTP has set the clock (adjtimex on Linux).
• Change-driven live, lp and prices at most every 5 s (1 s while watched, lp at least 2 s); a source-table change goes at once with a new srcRev; hb after H and never while a changed live or lp waits; full state every 15 minutes and after resync.
• One writer per socket: a slow socket gets the newest values, nothing queues, a write blocked for 10 s closes. Past 20 MB in 24 hours of uptime only roster and bye go.
• Driver and loadpoint names become opaque ids; capability fields have no place in the shapes. The downlink is a closed set of five types, under a fuzz test.
• Revoke sends bye{purge} and keeps the key until the service's signed receipt arrives.
• Import ban: .github/scripts/check-cloudlink-imports.sh (in CI and make verify) fails if the package's build graph, tests included, reaches anything of the box but go/protocol.

Core wiring:

• GET /api/cloud, GET /api/cloud/preview (owner), POST /api/cloud/grant (owner over a session; on the LAN only from the box itself or with the house password), DELETE /api/cloud/grant (any door).
• Enrolment lists whole keys for the signed roster and says when pairing, roles or revokes change.
• Owners hear cloud.granted and cloud.revoked. These two rules are on by default, unlike the rest; two existing tests now allow that.
• Backups skip cloud.key.
• Release builds name no service (cloudlink.ServiceKeys is empty), so a box refuses a grant and never dials. A local build sets the endpoint, the service key and a dev root with -ldflags -X.

End-to-end, on this laptop

Core built from this branch (a87386a8, and 06989083 for the last revoke run; the master merge in between touches no cloud file) with the endpoint, a local service key and a dev root set by -ldflags -X, against a local ftwcloudd from srcfl/ftw-cloud built with -tags ftwclouddev. The house is simulated: sim-ferroamp as site meter with battery and PV (1 Hz), sim-sungrow with battery and PV, and sim-ocpp as an Easee charger with a car plugged in, drawing about 11 kW, adopted by a loadpoint. Prices from elprisetjustnu.se, SE3. App link and fleet ping off.

Off until granted. Before the grant, /api/cloud said "state":"off" and nothing dialled. /api/cloud/preview showed an unsigned sample (live 732 B, lp 972 B, prices 1 312 B) with opaque ids and no driver names. The grant came from the box itself (curl on loopback): cloud.key was made, the home id is xgsch4rq….

The box refuses a bad certificate. The first local certificate was signed with SHA-1. The box refused it (insecure algorithm ECDSA-SHA1) and kept backing off until the certificate was replaced.

What the cloud holds is what the preview shows. With the uplink up, the last frame of each class in /api/cloud/preview, less its 6-byte header, was compared with the envelope the service holds:

class   seq   frame   held by the service     identical
hello     1   429 B   (service only)          -
roster    2   324 B   registry, 318 B          yes (SQLite row = frame less header)
live     35   260 B   seq 35                  yes
lp       15   811 B   seq 15                  yes
prices    5  1064 B   seq 5                   yes

Every envelope the service holds verifies with the box's key, and the home id is the hash of the key in hello.

A replayed snapshot goes stale. The held live (with its table), lp, prices and hb were fed to cloudwire.View, the reference for the phone's rules:

read now:                sources live, fields live, loadpoint live
same bytes, an hour on:  sources down, fields 2–6 and 10 down, field 1 (mode) stale, loadpoint down

Restarts. A restart of ftwcloudd (empty memory, same registry): the box reconnected after its backoff and the service was full again within a second of it. A restart of Core kept the grant and the home id.

A frozen service leaves the box alone. kill -STOP on ftwcloudd kept its sockets open and answered nothing. /api/status answered in 1–3 ms every 5 s throughout, and the control log has no slow-tick line. The box dropped the uplink after 36 s (i/o timeout, inside the 45 s read deadline) and was connected again 1.6 s after kill -CONT.

A revoked grant closes the stream and erases the copy. DELETE /api/cloud/grant from the box: the box sent bye{purge}, the service deleted the home and returned a signed purged, and /api/cloud read "state":"off" with purgedAtMs 0.07 s after the request. cloud.key is gone, /dev/held answers 404 for the home, the registry has no row and one tombstone, and the box makes no further connection. A second grant made a new key and a new home id, and its revoke finished in 1 ms.

Bytes per day. 30 minutes on the final sender (a87386a8), uplink connected throughout:

	Measured	Per day
Frames sent (the box's own count, WebSocket payload)	95 404 B in 1 804 s	4.57 MB
Messages	331	15 853
TLS records out, from nettop for this socket	89 546 B in 1 494 s	5.18 MB
TLS records in (pings, service messages)	2 400 B	0.14 MB

Sizes: live 263 B, lp 815 B, prices 1 064 B, roster 324 B, hello 429 B. The design estimated about 5.0 MB a day on the wire for the home box (19 372 messages), so this is about 1.2× once TCP and IP headers are added, inside the 2× the milestone allows. The simulated house is the harder case: a 1 Hz meter and a car charging at 11 kW the whole time.

Before the lp deadband the same house sent 12.7 MB a day: lp (814 B) went at every period because measured power moves every reading. With the deadband lp goes about every 35 s while the car charges, as session energy passes each 100 Wh. Composer cost on a Pi 4 is not measured here.

Where this differs from docs/protocol-cloud.md (#1589)

1. fieldSources travels with sources (every full live and every table change), not in every live. It changes only with the table, and in every message it would add about 1.5 MB a day.
2. A roster goes at every connect, not only when the numbers differ. An equal number renews ttlS; without it a box back after 20 hours offline would have 4 hours left.
3. lp compares measured values with a deadband: power and actual watts past max(100 W, 5 %), session energy past 100 Wh, charge level past 1 %. The document ignores only the ages. Without the deadband the simulated house sent 12.7 MB a day.
4. Nil lists are [] and unknown numbers null on the wire.
5. session is a count of the plug-ins this boot has seen; Core has no session id yet (K6). socAgeS is set only when the level came from the car.
6. manual.reason is the hold's limit reason; manual.commandedW is null at zero.
7. hello.caps lists the classes this box sends.
8. prices.t0Ms is the start of today on the box's clock, so the price hash moves only when new prices land.
9. A grant names a policy, and purposes is serve only until the statistics route exists.
10. Restore in place loses the key. Restore moves the whole data directory aside, so cloud.key does not come back and the grant reads as off (key_missing). The document says a box restored in place keeps its key; that needs a change to the restore flow.
11. The service signs hello_ok and purged over the box's home id.
12. POST /api/cloud/grant asks no step-up. The box cannot verify one, and the document has the consent screen claim no more than an owner's session.

Not in this pull request

• C3: the phone's half, including K11 (the box key, home id, boot and the opaque id table in the Noise session info). The cloud.link capability is in the registry but not advertised until the service exists.
• C4 and later: event, plan, health, tiles and stats, the statistics consent route, APNs.
• Composer cost on a Pi 4: not benched here.

Checks

• make verify: green (Go suites, go/protocol, vet, build, protocol and cloudlink boundaries).
• After merging master: make verify green again; targeted go test for api, cloudlink, appenroll, notifications, backup, appproto and the cloud tests in cmd/ftw.
• go test -race -count=3 ./internal/cloudlink: green.
• Fuzz: FuzzDecodeFrameAndEnvelope 20 s (4.9 M runs), FuzzDownlink 60 s (3.1 M runs).
• TestFieldsMatchTheProtocolDocument against docs: propose FTW Cloud (ADR 0008) and its protocol #1589's docs/protocol-cloud.md: passes.

A changeset (patch) is included. Release files, #1584 and the version are untouched.

🤖 Generated with Claude Code

[frahlg]

Included in #1607 (FTW Cloud C2, C3 and C4 joined), squash-merged to master.