@mhome/app-facade-protocol 1.40.1 → 1.41.0

package/contract/pod-commissioning-v1.md

@@ -6,10 +6,11 @@ first implementation, not a requirement. Commissioners are the native Clients:
 desktop/CLI Clientd, Android and iOS. The shared UI and CLI never talk BLE; they
 call the `/local/pod/*` targets of their native Client.
 
-Commissioning order is fixed: secure BLE session, Wi-Fi joined, user
-authorization, credential issue, delivery, activation. A credential is issued only
-after the pod reports a joined network. Failed setup releases the connection;
-pending cloud credentials expire, and a fresh successful claim cleans up old credentials.
+Network provisioning and activation are separate transactions. BLE provisions
+Wi-Fi; Ethernet and already-connected Wi-Fi skip it. Every initialization then
+uses a direct native Client ↔ Pod LAN security-2 session. No Core relay is used.
+The current credential API below is the existing personal Pod credential; this
+transport change does not implement the separately planned Space Client issuer.
 
 ## 1. Device identity
 
@@ -47,7 +48,7 @@ credential invalidation, or inside a re-provision window. A commissioned pod doe
 
 ## 3. Secure session
 
-Transport is ESP protocomm over BLE GATT. Endpoints are GATT characteristics
+Wi-Fi provisioning uses ESP protocomm over BLE GATT. Endpoints are GATT characteristics
 named by their Characteristic User Description descriptor (`0x2901`). A
 commissioner that cannot read descriptors falls back to fixed UUIDs: the service
 UUID with bytes 2–3 replaced by `prov-ctrl` `0xFF4F`, `prov-scan` `0xFF50`,
@@ -58,7 +59,7 @@ custom endpoints in table order from `0xFF54` (`pod-info` `0xFF54`,
 - Security: protocomm security 2 (SRP6a 3072-bit with SHA-512, then AES-256-GCM).
   Username `meow`. Password: a 6-digit decimal code.
 - Pods with a display generate a uniformly random code, precompute salt and
-  verifier at boot, and show the code only while a central is connected. A new
+  verifier at boot, and show it while connected over BLE or available for LAN initialization. A new
   code is generated after a successful commissioning, after 5 failed handshakes,
   or 10 minutes after it was first shown. Pods without a display are out of scope
   for v1.
@@ -70,8 +71,8 @@ custom endpoints in table order from `0xFF54` (`pod-info` `0xFF54`,
   `M` uses it as sent; `u` pads both to 384 bytes.
 - The record nonce is 8 random bytes followed by a 32-bit big-endian counter
   starting at 1, advanced after every encrypt and decrypt on both sides
-  (security 2 patch version 1; patch 0 keeps it fixed). Commissioners accept
-  patch versions 0 and 1 only. A lost or failed exchange leaves the two counters
+  (security 2 patch version 1; patch 0 keeps it fixed). Commissioners require
+  patch version 1; fixed-nonce patch 0 is rejected. A lost or failed exchange leaves the two counters
   unknown, so the commissioner abandons the secure session after any transport or
   decryption failure. A new `SessionCmd0` restarts the handshake on the same link.
 - While a device refuses handshakes after repeated wrong codes it clears the
@@ -81,8 +82,8 @@ custom endpoints in table order from `0xFF54` (`pod-info` `0xFF54`,
   such as Insufficient Authorization), so after every rejected handshake the
   commissioner reads `proto-ver` again and fails the session with `code_locked`
   when either field is present. A pod session also fails with `code_locked` after
-  the fifth rejected code. ESP pods restart with a new code after 5 failed
-  handshakes instead of reporting a lockout.
+  the fifth rejected code. Pods generate a fresh code after five rejected handshakes. Once network
+  configuration is saved, code rotation preserves that network.
 - One BLE connection at a time; a second central receives a disconnect.
 - Session deadline: 10 minutes from connect, or 2 minutes waiting for a
   handshake. On expiry the pod discards all unpersisted state.
@@ -95,15 +96,17 @@ custom endpoints in table order from `0xFF54` (`pod-info` `0xFF54`,
 | `prov-config` | yes | standard Wi-Fi set/apply/status |
 | `prov-ctrl` | yes | standard reset after a failed join, before a retry |
 | `pod-info` | yes | device information |
-| `pod-credential` | yes | credential delivery and activation status |
+| `pod-credential` | yes | LAN credential delivery/status/finish; BLE accepts only reprovision status/finish |
 
-Custom endpoint bodies are UTF-8 JSON, at most 480 bytes in each direction.
+Custom endpoint bodies are UTF-8 JSON, at most 480 bytes over BLE. LAN requests
+and responses are bounded to 64 KiB including encryption overhead.
 
 `pod-info` request `{}`, response:
 
 ```json
 {
   "protocol": 1,
+  "env": "prod",
   "deviceId": "a0b1c2d3e4f5",
   "model": "S1",
   "platform": "esp32c5",
@@ -114,6 +117,9 @@ Custom endpoint bodies are UTF-8 JSON, at most 480 bytes in each direction.
 }
 ```
 
+`env` must match the native Client runtime (`prod`, `dev`, `e2e`).
+`podId` is included when activation is in flight or durably completed, so a
+new session can observe completion without issuing another credential.
 `platform` is diagnostic only. `wifiConfigured` is true when the pod kept a
 working network across logout; the commissioner then skips the Wi-Fi steps after
 confirming connectivity with `prov-config` status. Inside a Wi-Fi change window
@@ -146,21 +152,52 @@ Activation error codes: `time_sync_failed`, `cloud_unreachable`,
 `refresh_rejected`, `auth_rejected`, `storage_failed` (the final commit, or in a
 Wi-Fi change window saving the new network, failed).
 
-The pod persists Wi-Fi, credential, endpoints and Space in one commit after a
-successful activation. Nothing from an abandoned attempt survives it; an
-implementation whose Wi-Fi driver caches the network on its own (ESP-IDF
-provisioning does) erases that cache when the attempt ends.
+The Pod commits Wi-Fi immediately after a successful join, before any credential
+issuance. Activation commits only identity/binding data. Failed activation,
+disconnection, code expiry and reboot preserve the successfully saved network.
+A failed join rolls back only the incomplete network change.
+
+### LAN discovery and channel
+
+- Service: `_meow-pod-init._tcp.local.` while network-ready and uninitialized.
+  TXT: full `deviceId`, `v=1`, `env`, optional `model`; SRV/A/AAAA locate the
+  endpoint. A failed or expired pairing attempt does not remove this service.
+- The same service works on Ethernet and Wi-Fi. BLE supplies the full device ID
+  and identity over its secure session; the short display ID is never the match
+  key. Discovery data is untrusted and is checked against encrypted `pod-info`.
+- HTTP POST `/{endpoint}` with `Content-Type: application/octet-stream` and a
+  fresh UUID `X-Meow-Session`. Allowed endpoints: `proto-ver`, `prov-session`,
+  `pod-info`, `pod-credential`. Wi-Fi endpoints are unavailable over LAN.
+  Clients connect to the resolved socket directly, with proxies/redirects off.
+- Run a fresh Security 2 patch-1 handshake on LAN. After BLE, reuse only the
+  temporarily held code, never the BLE session key or nonce. Ethernet setup
+  requests the code in the App UI. Business messages are AES-GCM protected.
+- Each IP session has separate crypto state. Devices cap simultaneous sessions
+  at four; pending handshakes expire after two minutes, sessions after ten.
+  An encrypted `pod-credential {"op":"close"}` releases that temporary session.
+- Stop init advertisement on durable completion. The existing session has a
+  short finish window for confirmation; normal business disconnection never
+  returns a completed device to initialization.
 
 ## 4. Pod state machine
 
 ```text
-unprovisioned ──connect──▶ session_open ──handshake──▶ secured
-secured ──prov-config apply──▶ wifi_joining ──▶ wifi_connected | wifi_failed
-wifi_failed ──retry──▶ wifi_joining
-wifi_connected ──deliver──▶ activating ──time sync, refresh, commit──▶ commissioned | failed
-any pre-commit state ──timeout/disconnect──▶ unprovisioned
+no network -> BLE secure -> join -> save Wi-Fi -> network ready
+Ethernet / saved Wi-Fi ------------------------> network ready
+network ready -> advertise init -> LAN secure -> authorize -> activate -> save identity
+join failure -> end attempt; start Wi-Fi setup again
+activation failure -> end attempt; keep network and init advertisement
+pairing expiry -> discard temporary sessions/code; keep network; accept a new code
 ```
 
+The App reports `discovering_lan` and `connecting_lan` during BLE handoff.
+Discovery snapshots distinguish `scanning` (BLE), `lanBrowsing`, optional
+`lanError`, and candidate `transport` (`ble` or `lan`). LAN candidates carry the
+full `deviceId`; Bluetooth denial never blocks them. The App retries initialization
+by selecting the LAN candidate, possibly re-entering the current code. It first
+reads actual device state: `commissioned` completes immediately, `activating`
+waits for the existing attempt, and a failed attempt may issue afresh.
+
 Runtime states after commit:
 
 - `commissioned`: normal operation.
@@ -316,7 +353,7 @@ and unexpired pending pods, each
 
 All targets are handled by the native Client and never forwarded. Payloads are
 domain input JSON. Clients without a usable Bluetooth adapter report
-`adapter.state` and reject commissioning with `bluetooth_unavailable`.
+`adapter.state` and reject BLE commissioning with `bluetooth_unavailable`; LAN candidates remain usable.
 
 A rejected request uses the facade error envelope
 `{"error","message","details":{"reason"}}`: `error` is `BAD_REQUEST` for an
@@ -394,9 +431,10 @@ example `storage_failed`) in `detail`. UIs show such a session as changing the
 pod's Wi-Fi rather than adding a pod.
 
 Session states, in order: `connecting`, `awaiting_code`, `securing`,
-`reading_info`, `awaiting_wifi`, `joining_wifi`, `awaiting_authorization`,
+`reading_info`, `awaiting_wifi`, `joining_wifi`, `discovering_lan`,
+`connecting_lan`, `awaiting_authorization`,
 `issuing`, `delivering`, `activating`, `completed`; terminal `failed`,
-`timed_out`. Wi-Fi states are skipped when the pod reports a
+`timed_out`. LAN candidates skip all Wi-Fi states. Wi-Fi states are also skipped when the pod reports a
 configured network and `prov-config` status reports it connected; while that
 status is `connecting` the commissioner keeps polling, and only after a failure
 does it reset Wi-Fi (`prov-ctrl`) and offer new credentials. The commissioner
@@ -407,10 +445,11 @@ scan runs waits for it. `revision` increases on every observable change.
 `delivering` on it is `activateBefore` plus 30 seconds.
 
 Only the device's durable `commissioned` response confirms successful setup.
-Lost BLE delivery confirmation or activation status fails the attempt, even
+Lost LAN delivery confirmation or activation status fails the attempt, even
 when Lion has already activated its credential. Expiry fails or times out the
 attempt. The commissioner does not recover interrupted setup through Lion's
-credential status. The user resets the device and starts a fresh attempt.
+credential status. The user selects the network-ready device again, establishes
+a fresh LAN session and reads its actual activation status.
 
 A refused `deliver` fails with `delivery_failed` carrying the pod's `reason`
 (`invalid_payload` or `wrong_state`) in `detail`. When the pod
@@ -423,14 +462,13 @@ app is in the background (Android foreground service of type
 
 Session error codes: `bluetooth_unavailable`, `device_busy`, `disconnected`,
 `code_rejected` (retry allowed), `code_locked`, `wifi_auth_failed`,
-`wifi_not_found`, `wifi_failed`, `issue_failed`, `delivery_failed`,
+`wifi_not_found`, `wifi_failed`, `lan_unavailable`, `device_mismatch`, `issue_failed`, `delivery_failed`,
 `activation_failed` (with the pod's activation code, or `not_activated`, in
 `detail`), `session_timeout`. `code_locked` is terminal: the device shows a new
 code once it accepts handshakes again. `failed` and `timed_out` always carry `error`. A rejected
-code returns to `awaiting_code` with `code_rejected`; a failed join returns to
-`awaiting_wifi` with the `wifi_*` code. No other state carries `error`. Terminal states release the link and radio
-without revoking credentials. Reset the Pod and start over after an uncertain
-activation outcome; unused pending cloud credentials expire automatically.
+code returns to `awaiting_code` with `code_rejected`; a failed Pod join ends in
+`failed` with the `wifi_*` code. No other state carries `error`. Terminal states release the link and radio
+without revoking credentials. Retry over LAN after an uncertain activation outcome; unused pending cloud credentials expire automatically.
 
 The schemas are `schema/pod-discovery.v1.schema.json` and
 `schema/pod-commission.v1.schema.json`.

package/fixtures/host-provision.completed.json

@@ -5,6 +5,7 @@
   "candidate": {
     "candidateId": "ble:5E6F7A8B",
     "kind": "host",
+    "transport": "ble",
     "name": "Kitchen Host",
     "shortId": "5E6F7A8B",
     "rssi": -61,

package/fixtures/pod-commission.awaiting-authorization.json

@@ -5,6 +5,7 @@
   "candidate": {
     "candidateId": "ble:1A2B3C4D",
     "kind": "pod",
+    "transport": "ble",
     "name": "MeowPod S1",
     "model": "S1",
     "shortId": "1A2B3C4D",

package/fixtures/pod-commission.failed.json

@@ -5,6 +5,7 @@
   "candidate": {
     "candidateId": "ble:1A2B3C4D",
     "kind": "pod",
+    "transport": "ble",
     "name": "MeowPod S1",
     "model": "S1",
     "shortId": "1A2B3C4D",

package/fixtures/pod-commission.reprovision-completed.json

@@ -5,6 +5,7 @@
   "candidate": {
     "candidateId": "ble:1A2B3C4D",
     "kind": "pod",
+    "transport": "ble",
     "name": "MeowPod S1",
     "model": "S1",
     "shortId": "1A2B3C4D",

package/fixtures/pod-discovery.snapshot.json

@@ -1,11 +1,13 @@
 {
   "revision": 4,
+  "lanBrowsing": false,
   "scanning": true,
   "adapter": { "state": "ready" },
   "candidates": [
     {
       "candidateId": "ble:1A2B3C4D",
       "kind": "pod",
+      "transport": "ble",
       "name": "MeowPod S1",
       "model": "S1",
       "shortId": "1A2B3C4D",

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",

package/manifest/host-provision-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "appTargets": [
     "/app/hub/get",
     "/app/hub/remove",

package/manifest/pod-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.pod.targets.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "contract": "contract/pod-commissioning-v1.md",
   "localTargets": [
     "/local/pod/discovery/start",

package/manifest/routing.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.routing.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode",

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "requestTargets": [
     "/app/messaging/provider/list",
     "/app/messaging/provider-account/list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/app-facade-protocol",
-  "version": "1.40.1",
+  "version": "1.41.0",
   "description": "Build-time protocol artifacts for mhome.app-facade",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,6 +1,6 @@
 {
   "protocol": "mhome.app-facade",
-  "contractVersion": "1.40.1",
+  "contractVersion": "1.41.0",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "capabilityDescriptor": "schema/capability-descriptor.v1.schema.json",

package/schema/person.v1.schema.json

@@ -204,7 +204,7 @@
           "type": "array",
           "items": {
             "type": "string",
-            "pattern": "^(person|cluster):.+$"
+            "pattern": "^h:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
           }
         }
       },

package/schema/pod-commission.v1.schema.json

@@ -16,6 +16,8 @@
         "reading_info",
         "awaiting_wifi",
         "joining_wifi",
+        "discovering_lan",
+        "connecting_lan",
         "awaiting_authorization",
         "issuing",
         "delivering",
@@ -86,6 +88,8 @@
             "bluetooth_unavailable",
             "device_busy",
             "disconnected",
+            "lan_unavailable",
+            "device_mismatch",
             "code_rejected",
             "code_locked",
             "wifi_auth_failed",

package/schema/pod-discovery.v1.schema.json

@@ -1,13 +1,15 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schemas.mhome.ai/app-facade/pod-discovery.v1.schema.json",
-  "title": "Native-client BLE discovery snapshot (pods and Hosts)",
+  "title": "Native-client BLE and LAN discovery snapshot (pods and Hosts)",
   "type": "object",
   "additionalProperties": false,
-  "required": ["revision", "scanning", "adapter", "candidates"],
+  "required": ["revision", "scanning", "lanBrowsing", "adapter", "candidates"],
   "properties": {
     "revision": { "type": "integer", "minimum": 0 },
     "scanning": { "type": "boolean" },
+    "lanBrowsing": { "type": "boolean" },
+    "lanError": { "type": "string" },
     "adapter": { "$ref": "#/$defs/adapter" },
     "candidates": { "type": "array", "items": { "$ref": "#/$defs/candidate" } }
   },
@@ -27,6 +29,7 @@
       "required": [
         "candidateId",
         "kind",
+        "transport",
         "name",
         "shortId",
         "rssi",
@@ -37,9 +40,11 @@
       "properties": {
         "candidateId": { "type": "string", "minLength": 1 },
         "kind": { "enum": ["pod", "host"] },
+        "transport": { "enum": ["ble", "lan"] },
+        "deviceId": { "type": "string", "minLength": 1, "maxLength": 64 },
         "name": { "type": "string", "minLength": 1 },
         "model": { "type": "string" },
-        "shortId": { "type": "string", "pattern": "^[0-9A-F]{8}$" },
+        "shortId": { "type": "string", "minLength": 1, "maxLength": 64 },
         "rssi": { "type": "integer" },
         "commissionable": { "type": "boolean" },
         "wifiConfigured": { "type": "boolean" },