@mhome/app-facade-protocol 1.47.0 → 1.49.1

package/README.md

@@ -49,6 +49,13 @@ timings and request reasons are in `manifest/pod-targets.v1.json`; snapshots use
 `schema/pod-discovery.v1.schema.json` and `schema/pod-commission.v1.schema.json`;
 User Pod enrollment uses a one-time login approval; activation is confirmed on the paired device.
 
+`/app/pod/list` reads registered Pod Clients in the active Space, including
+connections that are currently absent. `/app/host/list` reads historical Host
+registrations without granting management access; see the
+[Host directory contract](contract/host-directory-v1.md). Native commissioning
+uses the existing device protocols; the Agent resumes only after verifying the
+resulting registration. Host completion identifies both `hostId` and `env`.
+
 `host_provision` (1.34.0) defines BLE Wi-Fi provisioning of embedded Hosts
 (`/local/host/provision/*`) on the same BLE layer; discovery candidates carry
 `kind`. A completed session carries the one-time `claimToken` that the first

package/contract/pod-commissioning-v1.md

@@ -247,8 +247,15 @@ stores the resulting refresh token, and refresh uses the standard User login
 endpoint. A failed attempt is retried with a new approval; no old protocol is
 accepted.
 
-`podId` identifies the enrollment/device-list entry, not the authenticated User.
-`POST /api/v1/pod/list` and `/api/v1/pod/rename` use the ordinary User login.
+`podId` identifies a single approval attempt, not the durable device or authenticated
+User. The durable `registrationId` derives from the business User and the validated
+persistent device-key fingerprint. `POST /api/v1/pod/list` returns that ID;
+`/api/v1/pod/rename` accepts `{registrationId, name}` with ordinary User login.
+Successful authentication atomically creates the registration if absent and records
+completion on the consumed approval. Retries preserve the initial registration and
+current display name. Unauthenticated attempts create no device-list entry.
+The attempt receipt remains readable for one day after the approval's expiry;
+`expiresAt` still controls its ten-minute, single-use authentication window.
 There is no cloud credential-status polling or server-side Pod revocation flow.
 Factory reset clears device credentials and rotates the pairing identity.
 
@@ -359,7 +366,9 @@ scans for networks once on entering `awaiting_wifi`; a scan request while that
 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.
+`delivering` on, User approval uses `activateBefore` plus 30 seconds; Space delivery
+gets a separate two-minute confirmation deadline. An active Space credential has no
+first-use deadline and never causes immediate completion or an expired attempt.
 
 Only the device's durable `commissioned` response confirms successful setup.
 Lost LAN confirmation triggers at most three reconnections to this attempt's
@@ -398,8 +407,10 @@ The schemas are `schema/pod-discovery.v1.schema.json` and
 `Authorization` and `ScopeId`, with the same device identity request as personal
 issuance. Only the current Space owner may assist. The Space must be local and have one
 published Hub with business and Host TLS identities. Cloud Spaces must complete
-Hub setup first. The issuer creates a fresh `appClientId` (`a:<random id>`) and
-signs a local JWT using the existing Space signing key and local-client audience.
+Hub setup first. The issuer derives `appClientId` from tenant, Space and the validated
+persistent device-key fingerprint. The same device in the same Space retains this
+ID across retries; a factory reset rotates its key. Candidate local JWTs use the
+existing Space signing key and local-client audience.
 
 Claims are `token_type: local_space_client_access`, `sub: <scopeId>`,
 `tenant_id`, `scope_id`, `hub_id`, `app_client_id`, `jti`, `iat`, `exp`, `is_test`.
@@ -410,11 +421,17 @@ Personal Pod issuance no longer stores `issuedScopeId`.
 
 Lion sends `{jwtToken, clientSource:"pod"}` to the authenticated Hub Bridge
 `/hub/client/space/register`. Core verifies signature, audience, issuer, current
-Hub, environment, Space and canonical installation ID, and stores a pending
-credential. First authentication must occur within ten minutes of JWT issuance.
-The response is `{credentialId, status:"pending", activateBefore}`. Lion returns
-`{credentialId, appClientId, jwtToken, activateBefore, hubIdentity}` only after
-registration succeeds. The Hub identity includes its business P-256 key and
+Hub, environment, Space and canonical installation ID. It reuses a valid current
+pending or active credential, or atomically selects a replacement after fresh owner
+authorization. Concurrent issuers receive the selected credential; a stale replacement
+cannot overwrite activation or revocation. Pending reuse retains its original
+first-authentication deadline, ten minutes after JWT issuance. Invalid, revoked,
+expired or differently bound credentials are not reused. Signature/key infrastructure
+failures propagate instead of being interpreted as absence.
+The Bridge returns `{credentialId, appClientId, jwtToken, status, activateBefore}`.
+Lion returns `{credentialId, appClientId, jwtToken, credentialState, activateBefore,
+hubIdentity}`. State is `pending` with its epoch-millisecond first-use deadline, or
+`active` with `activateBefore:null`. Issuance alone does not publish a device-list entry. The Hub identity includes its business P-256 key and
 Host TLS public key, bound to `tenantId`, `scopeId`, `hubId` and `hostId`.
 
 The secured LAN `pod-credential` delivery is:
@@ -430,8 +447,10 @@ bounded to 8192 bytes; BLE credential delivery remains disabled.
 
 The Pod discovers the matching runtime environment and Space's Hub, pins TLS,
 verifies the signed Hub proof, and authenticates with the local JWT and signed
-`appClientId`. Core atomically activates the pending credential after all binding
-checks. The Pod requires a Space principal for the same Space, installation and
+`appClientId`. After authentication checks succeed, Core atomically activates the
+credential and publishes the durable AppClient registration. Repeated authentication
+preserves the first activation; later offline or revoked credentials do not erase the
+registration. The Pod requires a Space principal for the same Space, installation and
 credential in the authenticated response, then durably saves the profile. Only
 then does LAN setup report completion. The LAN status field named `podId` is an
 enrollment correlation ID: for Space mode it carries `credentialId`, never the
@@ -450,3 +469,26 @@ MANAGE, personal resources and Host user administration are rejected. It joins
 the canonical Space-client conversation group, never an initializer's threads.
 The billing owner fallback is not an acting identity. Host management tokens are
 independent and are never issued by this flow.
+
+## Registered Pod list
+
+`/app/pod/list` takes empty input and lists persisted Pod Clients in the current
+Space, including disconnected registrations. A personal caller sees their own
+User Pods and Space-owned Pods. Rows contain `appClientId`, `clientMode`,
+`scopeId`, `registered`, `connected` and `observationSource` (`hub` or `cloud`);
+the envelope includes `observedAtMs`. Connection status is observed from that
+execution endpoint, not a statement about physical power or LAN reachability.
+Native clients combine this result with their own discovery observations.
+Never merge a Bluetooth short ID with a registered identity without proof.
+This read does not issue credentials or change Pod identity.
+
+
+`appClientId` identifies a registered application client; it is not the enrollment
+`podId` used by native commissioning. The list does not invent that association.
+`/app/pod/enrollment/get` takes `{podId}` and returns `{podId, clientMode: "user",
+registered}` from the authenticated user's successful receipt for that exact attempt.
+An older registration for the same device cannot complete a different attempt.
+`/app/pod/space/enrollment/get` takes the same input and checks the current Space's
+active local credential, returning `clientMode: "space"`; this read requires Space
+MANAGE. A cloud Space has no such local enrollment and returns `registered:false`.
+Both checks are read-only completion hooks. They do not issue or renew credentials.

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.47.0",
+  "contractVersion": "1.49.1",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
@@ -27,7 +27,12 @@
     },
     "pod": {
       "targets": "manifest/pod-targets.v1.json",
-      "contract": "contract/pod-commissioning-v1.md"
+      "contract": "contract/pod-commissioning-v1.md",
+      "listTarget": "/app/pod/list",
+      "enrollmentTargets": [
+        "/app/pod/enrollment/get",
+        "/app/pod/space/enrollment/get"
+      ]
     },
     "hostProvision": {
       "targets": "manifest/host-provision-targets.v1.json",
@@ -150,7 +155,8 @@
       "issuer": "cloud",
       "firstClaimTransport": "directLanOnly",
       "authorizationTarget": "/app/host/authorization",
-      "authorizationSchema": "schema/host-authorization.v1.schema.json"
+      "authorizationSchema": "schema/host-authorization.v1.schema.json",
+      "listTarget": "/app/host/list"
     },
     "clientAppearance": {
       "schema": "schema/client-appearance.v1.schema.json",

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

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.47.0",
+  "contractVersion": "1.49.1",
   "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.47.0",
+  "contractVersion": "1.49.1",
   "appTargets": [
     "/app/hub/get",
     "/app/hub/remove",

package/manifest/pod-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.pod.targets.v1",
-  "contractVersion": "1.47.0",
+  "contractVersion": "1.49.1",
   "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.47.0",
+  "contractVersion": "1.49.1",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode"
@@ -31,7 +31,9 @@
       "/app/messaging/code/status",
       "/app/messaging/binding/list",
       "/app/messaging/bind/code/create",
-      "/app/messaging/unbind"
+      "/app/messaging/unbind",
+      "/app/host/list",
+      "/app/pod/enrollment/get"
     ],
     "scopeModeTargets": [
       "/app/artifact/resolve",
@@ -43,7 +45,9 @@
       "/app/artifact/upload/complete",
       "/app/artifact/upload/cancel",
       "/app/system/instances/get",
-      "/app/system/clients/get"
+      "/app/system/clients/get",
+      "/app/pod/list",
+      "/app/pod/space/enrollment/get"
     ],
     "hubPrefixes": [
       "/app/plugin/",

package/manifest/targets.v1.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/app-facade-protocol",
-  "version": "1.47.0",
+  "version": "1.49.1",
   "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.47.0",
+  "contractVersion": "1.49.1",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "hostAuthorization": "schema/host-authorization.v1.schema.json",