@mhome/app-facade-protocol 1.34.0 → 1.36.0

package/contract/host-provisioning-v1.md

@@ -119,20 +119,18 @@ Candidates come from the shared discovery (`/local/pod/discovery/*`) with
 | `/local/host/provision/code` | `{"sessionId","code"}` | session snapshot |
 | `/local/host/provision/wifi` | `{"sessionId","ssid","password"?}` | session snapshot |
 | `/local/host/provision/wifi/scan` | `{"sessionId"}` | session snapshot |
-| `/local/host/provision/cancel` | `{"sessionId"}` | session snapshot |
-| `/local/host/provision/renew` | `{"sessionId"}` | session snapshot |
 | `/local/host/provision/status` | `{}` | `{"session": snapshot or null}` |
 
 Event `/local/host/provision/changed` carries a session snapshot. One session
 per native Client, and none while a pod session is active; discovery scanning
 pauses during either. Rejected requests use the error envelope and the stable
 `details.reason` values of `pod-commissioning-v1.md` section 7. The session is
-owned through the same 30-second lease, renewed with
-`/local/host/provision/renew` every 10 seconds; an expired lease cancels it.
+owned by the native core until success, failure or the session deadline.
+There is no cancellation or renewal endpoint; leaving the UI does not end it.
 
 Session states, in order: `connecting`, `awaiting_code`, `securing`,
 `reading_info`, `awaiting_wifi`, `joining_wifi`, `completed`; terminal `failed`,
-`cancelled`, `timed_out`. `completed` carries `host`, the reported `addresses`
+`timed_out`. `completed` carries `host`, the reported `addresses`
 (IPv4 only, possibly empty) and `claimToken` from the `finish` response; the
 commissioner sends `finish` (up to 3 times while the secure session lasts)
 before reporting it. `claimToken` is absent when `finish` could not be

package/contract/pod-commissioning-v1.md

@@ -8,7 +8,8 @@ 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. Any failure after issue revokes it.
+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.
 
 ## 1. Device identity
 
@@ -24,7 +25,7 @@ after the pod reports a joined network. Any failure after issue revokes it.
 ## 2. BLE advertising
 
 Pods advertise only while unprovisioned, while re-commissioning after logout or
-revocation, or inside a re-provision window. A commissioned pod does not advertise.
+credential invalidation, or inside a re-provision window. A commissioned pod does not advertise.
 
 - Service UUID (128-bit, shared by every MeowLink commissionable device):
   `a17a7ad5-9b2f-4010-9cf0-aa15ac54c40e`.
@@ -157,7 +158,7 @@ unprovisioned ──connect──▶ session_open ──handshake──▶ secur
 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/cancel──▶ unprovisioned
+any pre-commit state ──timeout/disconnect──▶ unprovisioned
 ```
 
 Runtime states after commit:
@@ -176,8 +177,9 @@ Runtime states after commit:
 - `needs_recommission`: logout, or refresh rejected because the credential was
   revoked or the user no longer exists. Credential and local JWTs are erased,
   Wi-Fi is kept, advertising resumes with the Wi-Fi-configured flag.
-- `factory_resetting`: best-effort self-revoke, erase all persisted data
-  including the identity key, reboot to `unprovisioned`.
+- `factory_resetting`: purely offline, erase all persisted data including the
+  identity key and cached Hub tokens, reboot to `unprovisioned`. No cloud
+  request is needed. Logout also clears local credentials without cloud revocation.
 
 Time sync uses SNTP; if NTP is unreachable the pod may use the `Date` header of a
 Lion HTTPS response. Activation proofs require a synced clock.
@@ -227,7 +229,7 @@ claims `iss` and `sub` = `podId`, a single-valued `aud` = `pod-token-refresh`,
 proof can be accepted; a reused `jti` in that window fails with
 `pod_proof_replayed`.
 
-The first successful refresh moves `pending` to `active` and revokes every other
+Before the first successful refresh moves `pending` to `active`, Lion deletes every other
 credential with the same `identity.keyId` (whichever user holds it) and the same
 user's other credentials with the same `deviceId`. A `pending` credential past
 `activateBefore` is rejected and deleted. Revoked credentials are deleted, so a
@@ -241,17 +243,16 @@ later refresh fails with `pod_credential_invalid`. Response
 `absent` (schema `schema/pod-credential-status.v1.schema.json`). `absent`
 covers no such credential, revoked, pending past `activateBefore`, and a
 credential owned by another user, so the answer never reveals other users'
-pods. `activatedAt` (epoch ms) is present when `active`. Commissioners use it to
-decide the outcome of an activation they could not observe (section 7).
+pods. `activatedAt` (epoch ms) is present when `active`. It is informational;
+commissioning success requires the device confirmation described in section 7.
 
-### Revoke
+### Reset and cleanup
 
-`POST /api/v1/pod/credential/revoke`, body `{"podId"}` with the owning user's
-`Authorization`, or `{"podId","refreshToken","proof"}` where the proof uses
-`aud` = `pod-credential-revoke` (pod logout and factory reset). Idempotent:
-revoking a pod that does not exist or that the caller does not own is a no-op
-that also answers `{"ok":true}`, so the answer never reveals other users' pods.
-Response `{"ok":true}`.
+There is no public Pod credential revocation endpoint and no App action that
+withdraws a Pod's access without contacting the device. Factory reset executes
+on the Pod itself. Remote reset, when provided, must reach an online Pod; a
+cloud-side deletion is not a successful reset. This contract currently exposes
+no remote reset target. Each setup creates a new Pod credential.
 
 ### List and rename
 
@@ -282,8 +283,11 @@ and unexpired pending pods, each
   channel. Either close only ends that connection; whether the pod is revoked
   is decided by its next refresh.
 - `/api/v1/hub/token/exchange` with a pod access token returns a Hub JWT with
-  `clientKind` = `pod` and `podId` claims and a 24-hour lifetime. Hub JWTs for
-  user tokens are unchanged.
+  `clientKind` = `pod` and `podId` claims and the same lifetime as a Hub JWT
+  for a user token.
+- Pod and ordinary Client local Hub JWTs have the same 100-year lifetime
+  (100 * 365 days). There is no per-Pod Hub revocation list or cloud-to-Hub
+  revocation sync. Local tokens are cleared on the Pod by reset/logout.
 
 ## 6. Pod runtime authentication
 
@@ -299,11 +303,14 @@ and unexpired pending pods, each
   re-sends `/focus`; it keeps one Hub JWT and Hub key per Hub and Space.
 - Local Hub: the Hub identity endpoint `POST /api/v1/hub/identity/get`
   (`{"hubId","tenantId","scopeId"}`) is public and needs no token. The pod
-  proves the Hub identity, obtains a Hub JWT from `/api/v1/hub/token/exchange`
-  over HTTPS with its pod access token and `ScopeId`, and authenticates to the
-  local Hub only with that Hub JWT (`source=local`, `clientSource=pod`). The
-  cloud access token is never sent over the local link. The pod exchanges a new
-  Hub JWT before the current one expires and after a local rejection.
+  proves the Hub identity, then authenticates to the local Hub the way a Client
+  does: the first local `/auth` carries its pod access token with
+  `source=cloud` (`clientSource=pod`, `deviceId`, `tenantId`, `scopeId`,
+  `hubId`). The Hub exchanges that token with the cloud and returns a
+  long-lived local Hub JWT in `jwtToken`, which the pod stores per Hub. Later
+  local `/auth` requests use only that JWT with `source=local`. When the stored
+  JWT is about to expire or the Hub rejects it, the pod discards it and
+  authenticates with `source=cloud` again.
 
 ## 7. Native Client targets
 
@@ -346,8 +353,6 @@ never show these values or `message` verbatim.
 | `/local/pod/commission/wifi` | `{"sessionId","ssid","password"?}` | session snapshot |
 | `/local/pod/commission/wifi/scan` | `{"sessionId"}` | session snapshot |
 | `/local/pod/commission/authorize` | `{"sessionId","scopeId"}` | session snapshot |
-| `/local/pod/commission/cancel` | `{"sessionId"}` | session snapshot |
-| `/local/pod/commission/renew` | `{"sessionId"}` | session snapshot |
 | `/local/pod/commission/status` | `{}` | `{"session": snapshot or null}` |
 | `/local/pod/bluetooth/settings` | `{}` | `{"opened"}` |
 
@@ -369,10 +374,10 @@ UIs reconcile with `status` and discovery `list` on start, resume, reconnect and
 when they become visible, and a snapshot with a lower `revision` than one
 already seen for the same session is stale.
 
-The session that `start` creates is owned through a 30-second lease. The
-caller renews it with `/local/pod/commission/renew` every 10 seconds while it
-shows the session. An expired lease cancels the session, except in `delivering`
-and `activating`, which run to their conclusion.
+The native core owns the session until success or failure, bounded by
+`expiresAtMs`. There is no user cancellation or session renewal. Leaving the
+page does not end setup; returning to it reads `status`. Waiting for user input
+also counts toward the deadline. Discovery leases still control scanning.
 
 Sign-in and Spaces are checked at `start` (`not_signed_in`,
 `scope_not_offered`) and again when the authorization prompt is built.
@@ -391,7 +396,7 @@ 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`,
 `issuing`, `delivering`, `activating`, `completed`; terminal `failed`,
-`cancelled`, `timed_out`. Wi-Fi states are skipped when the pod reports a
+`timed_out`. Wi-Fi states are 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
@@ -401,18 +406,15 @@ scan runs waits for it. `revision` increases on every observable change.
 `expiresAtMs` is 10 minutes after `start` until delivery starts; from
 `delivering` on it is `activateBefore` plus 30 seconds.
 
-Lion decides the outcome of activation. In `delivering` and `activating`, a
-lost BLE link, a failed status exchange or the deadline does not revoke by
-itself; the commissioner asks `/api/v1/pod/credential/status`:
-
-- `active`: `completed` with `podId`.
-- `pending`: ask again every 5 seconds until `activateBefore` plus 30 seconds,
-  then revoke and fail with `activation_failed`.
-- `absent`: fail with `activation_failed`.
+Only the device's durable `commissioned` response confirms successful setup.
+Lost BLE 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.
 
 A refused `deliver` fails with `delivery_failed` carrying the pod's `reason`
-(`invalid_payload` or `wrong_state`) in `detail`, and revokes. When the pod
-itself reports `failed`, the commissioner revokes and fails with
+(`invalid_payload` or `wrong_state`) in `detail`. When the pod
+itself reports `failed`, the commissioner fails with
 `activation_failed` carrying the pod's code. `activation_failed` without a pod
 code carries `not_activated`. The commissioner records `completed` before
 sending `finish`. Native Clients keep a non-terminal session running while the
@@ -426,10 +428,9 @@ Session error codes: `bluetooth_unavailable`, `device_busy`, `disconnected`,
 `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`. After
-issue, every terminal state other than `completed` revokes the credential unless
-Lion already reported it `absent`; the revoke uses the account that issued the
-credential.
+`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.
 
 The schemas are `schema/pod-discovery.v1.schema.json` and
 `schema/pod-commission.v1.schema.json`.

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.34.0",
+  "contractVersion": "1.36.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,14 +1,12 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.34.0",
+  "contractVersion": "1.36.0",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",
     "/local/host/provision/code",
     "/local/host/provision/wifi",
     "/local/host/provision/wifi/scan",
-    "/local/host/provision/cancel",
-    "/local/host/provision/renew",
     "/local/host/provision/status"
   ],
   "eventTargets": [

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.34.0",
+  "contractVersion": "1.36.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.34.0",
+  "contractVersion": "1.36.0",
   "contract": "contract/pod-commissioning-v1.md",
   "localTargets": [
     "/local/pod/discovery/start",
@@ -12,8 +12,6 @@
     "/local/pod/commission/wifi",
     "/local/pod/commission/wifi/scan",
     "/local/pod/commission/authorize",
-    "/local/pod/commission/cancel",
-    "/local/pod/commission/renew",
     "/local/pod/commission/status",
     "/local/pod/bluetooth/settings"
   ],
@@ -63,15 +61,12 @@
   },
   "session": {
     "lifetimeMs": 600000,
-    "leaseMs": 30000,
-    "renewIntervalMs": 10000,
     "activationGraceMs": 30000,
     "credentialStatusPollMs": 5000
   },
   "cloud": {
     "issue": "pod/credential/issue",
     "status": "pod/credential/status",
-    "revoke": "pod/credential/revoke",
     "statusSchema": "schema/pod-credential-status.v1.schema.json"
   },
   "activationErrorCodes": [

package/manifest/routing.v1.json

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

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.34.0",
+  "contractVersion": "1.36.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.34.0",
+  "version": "1.36.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.34.0",
+  "contractVersion": "1.36.0",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "capabilityDescriptor": "schema/capability-descriptor.v1.schema.json",

package/schema/host-provision.v1.schema.json

@@ -18,7 +18,6 @@
         "joining_wifi",
         "completed",
         "failed",
-        "cancelled",
         "timed_out"
       ]
     },

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

@@ -22,7 +22,6 @@
         "activating",
         "completed",
         "failed",
-        "cancelled",
         "timed_out"
       ]
     },