@mhome/app-facade-protocol 1.33.0 → 1.34.1

package/fixtures/host-provision.completed.json

@@ -0,0 +1,26 @@
+{
+  "sessionId": "hps-41c2",
+  "revision": 9,
+  "state": "completed",
+  "candidate": {
+    "candidateId": "ble:5E6F7A8B",
+    "kind": "host",
+    "name": "Kitchen Host",
+    "shortId": "5E6F7A8B",
+    "rssi": -61,
+    "commissionable": true,
+    "wifiConfigured": false,
+    "lastSeenMs": 1791300000000
+  },
+  "expiresAtMs": 1791300600000,
+  "host": {
+    "hostId": "host-0f3c9a",
+    "name": "Kitchen Host",
+    "productId": "camera",
+    "firmwareVersion": "0.9.0",
+    "fingerprint": "5e6f7a8b0c1d2e3f405162738495a6b7c8d9eaf0123456789abcdef012345678",
+    "wifiConfigured": false
+  },
+  "addresses": ["192.168.1.42"],
+  "claimToken": "q3hX0v2c1mJb9yQe7tL4nK8sP5wR6uA0zD1fG2hI3jM"
+}

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

@@ -0,0 +1,29 @@
+{
+  "sessionId": "pcs-7f3a",
+  "revision": 9,
+  "state": "awaiting_authorization",
+  "candidate": {
+    "candidateId": "ble:1A2B3C4D",
+    "kind": "pod",
+    "name": "MeowPod S1",
+    "model": "S1",
+    "shortId": "1A2B3C4D",
+    "rssi": -55,
+    "commissionable": true,
+    "wifiConfigured": false,
+    "lastSeenMs": 1791300000000
+  },
+  "expiresAtMs": 1791300600000,
+  "device": {
+    "deviceId": "a0b1c2d3e4f5",
+    "model": "S1",
+    "firmwareVersion": "0.3.0",
+    "wifiConfigured": false
+  },
+  "authorization": {
+    "userId": "user-1",
+    "userName": "Ada",
+    "scopes": [{ "scopeId": "scope-1", "name": "Home" }],
+    "defaultScopeId": "scope-1"
+  }
+}

package/fixtures/pod-commission.failed.json

@@ -0,0 +1,22 @@
+{
+  "sessionId": "pcs-7f3a",
+  "revision": 12,
+  "state": "failed",
+  "candidate": {
+    "candidateId": "ble:1A2B3C4D",
+    "kind": "pod",
+    "name": "MeowPod S1",
+    "model": "S1",
+    "shortId": "1A2B3C4D",
+    "rssi": -55,
+    "commissionable": true,
+    "wifiConfigured": false,
+    "lastSeenMs": 1791300000000
+  },
+  "expiresAtMs": 1791300600000,
+  "error": {
+    "code": "activation_failed",
+    "message": "The device could not reach the cloud",
+    "detail": "cloud_unreachable"
+  }
+}

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

@@ -0,0 +1,24 @@
+{
+  "sessionId": "pcs-81d0",
+  "revision": 10,
+  "state": "completed",
+  "candidate": {
+    "candidateId": "ble:1A2B3C4D",
+    "kind": "pod",
+    "name": "MeowPod S1",
+    "model": "S1",
+    "shortId": "1A2B3C4D",
+    "rssi": -55,
+    "commissionable": true,
+    "wifiConfigured": false,
+    "lastSeenMs": 1791300000000
+  },
+  "expiresAtMs": 1791300600000,
+  "device": {
+    "deviceId": "a0b1c2d3e4f5",
+    "model": "S1",
+    "firmwareVersion": "0.3.0",
+    "wifiConfigured": false
+  },
+  "mode": "reprovision"
+}

package/fixtures/pod-discovery.snapshot.json

@@ -0,0 +1,18 @@
+{
+  "revision": 4,
+  "scanning": true,
+  "adapter": { "state": "ready" },
+  "candidates": [
+    {
+      "candidateId": "ble:1A2B3C4D",
+      "kind": "pod",
+      "name": "MeowPod S1",
+      "model": "S1",
+      "shortId": "1A2B3C4D",
+      "rssi": -58,
+      "commissionable": true,
+      "wifiConfigured": false,
+      "lastSeenMs": 1791300000000
+    }
+  ]
+}

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.33.0",
+  "contractVersion": "1.34.1",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
@@ -21,6 +21,14 @@
     "messaging": {
       "targets": "manifest/targets.v1.json"
     },
+    "pod": {
+      "targets": "manifest/pod-targets.v1.json",
+      "contract": "contract/pod-commissioning-v1.md"
+    },
+    "hostProvision": {
+      "targets": "manifest/host-provision-targets.v1.json",
+      "contract": "contract/host-provisioning-v1.md"
+    },
     "plugin": {
       "extensionVersion": "v1",
       "targetPrefix": "/app/plugin",

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

@@ -0,0 +1,39 @@
+{
+  "manifest": "mhome.host-provision.targets.v1",
+  "contractVersion": "1.34.1",
+  "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": [
+    "/local/host/provision/changed"
+  ],
+  "localPayload": "domainInput",
+  "localForwardable": false,
+  "ble": {
+    "kind": 2,
+    "appInfoLabel": "meow",
+    "appCapability": "host",
+    "appInfoLocked": "locked",
+    "appInfoLockedForMs": "lockedForMs",
+    "maxAttributeBytes": 512,
+    "scanTimeoutMs": 12000,
+    "customEndpoints": [
+      "host-info"
+    ],
+    "customEndpointUuids": {
+      "host-info": 65364
+    }
+  },
+  "codeLockout": {
+    "initialMs": 30000,
+    "maxMs": 600000
+  },
+  "claimTokenLength": 43
+}

package/manifest/hub-targets.v1.json

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

package/manifest/pod-targets.v1.json

@@ -0,0 +1,102 @@
+{
+  "manifest": "mhome.pod.targets.v1",
+  "contractVersion": "1.34.1",
+  "contract": "contract/pod-commissioning-v1.md",
+  "localTargets": [
+    "/local/pod/discovery/start",
+    "/local/pod/discovery/renew",
+    "/local/pod/discovery/stop",
+    "/local/pod/discovery/list",
+    "/local/pod/commission/start",
+    "/local/pod/commission/code",
+    "/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"
+  ],
+  "eventTargets": [
+    "/local/pod/discovery/changed",
+    "/local/pod/commission/changed"
+  ],
+  "localPayload": "domainInput",
+  "localForwardable": false,
+  "ble": {
+    "serviceUuid": "a17a7ad5-9b2f-4010-9cf0-aa15ac54c40e",
+    "companyId": 65535,
+    "manufacturerMagic": "MW",
+    "advertisingVersion": 1,
+    "kinds": {
+      "pod": 1,
+      "host": 2
+    },
+    "srpUsername": "meow",
+    "securityVersion": 2,
+    "appInfoLabel": "meow",
+    "appCapability": "pod",
+    "appInfoLocked": "locked",
+    "appInfoLockedForMs": "lockedForMs",
+    "codeAttempts": 5,
+    "customEndpoints": [
+      "pod-info",
+      "pod-credential"
+    ],
+    "standardEndpointUuids": {
+      "prov-ctrl": 65359,
+      "prov-scan": 65360,
+      "prov-session": 65361,
+      "prov-config": 65362,
+      "proto-ver": 65363
+    },
+    "customEndpointUuids": {
+      "pod-info": 65364,
+      "pod-credential": 65365
+    },
+    "customEndpointMaxBytes": 480
+  },
+  "discovery": {
+    "leaseMs": 30000,
+    "candidateTtlMs": 10000,
+    "eventIntervalMs": 1000
+  },
+  "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": [
+    "time_sync_failed",
+    "cloud_unreachable",
+    "refresh_rejected",
+    "auth_rejected",
+    "storage_failed"
+  ],
+  "notActivatedDetail": "not_activated",
+  "credentialRefusalReasons": ["invalid_payload", "wrong_state"],
+  "reprovisionMode": "reprovision",
+  "requestErrorReasons": [
+    "session_active",
+    "device_gone",
+    "not_commissionable",
+    "wrong_kind",
+    "unknown_session",
+    "wrong_state",
+    "invalid_code",
+    "invalid_wifi",
+    "bluetooth_unavailable",
+    "not_signed_in",
+    "scope_not_offered",
+    "cloud_unreachable_for_device",
+    "busy"
+  ]
+}

package/manifest/routing.v1.json

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

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.33.0",
+  "contractVersion": "1.34.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.33.0",
+  "version": "1.34.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.33.0",
+  "contractVersion": "1.34.1",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "capabilityDescriptor": "schema/capability-descriptor.v1.schema.json",
@@ -10,6 +10,10 @@
     "routing": "schema/routing.v1.schema.json",
     "hubState": "schema/hub-state.v1.schema.json",
     "localHubState": "schema/local-hub-state.v1.schema.json",
+    "podDiscovery": "schema/pod-discovery.v1.schema.json",
+    "podCommission": "schema/pod-commission.v1.schema.json",
+    "podCredentialStatus": "schema/pod-credential-status.v1.schema.json",
+    "hostProvision": "schema/host-provision.v1.schema.json",
     "systemClients": "schema/system-clients.v1.schema.json",
     "systemHosts": "schema/system-hosts.v1.schema.json",
     "systemHostsRuntime": "schema/system-hosts-runtime.v1.schema.json",

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

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/host-provision.v1.schema.json",
+  "title": "Native-client Host provisioning session snapshot",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sessionId", "revision", "state", "candidate", "expiresAtMs"],
+  "properties": {
+    "sessionId": { "type": "string", "minLength": 1 },
+    "revision": { "type": "integer", "minimum": 0 },
+    "state": {
+      "enum": [
+        "connecting",
+        "awaiting_code",
+        "securing",
+        "reading_info",
+        "awaiting_wifi",
+        "joining_wifi",
+        "completed",
+        "failed",
+        "cancelled",
+        "timed_out"
+      ]
+    },
+    "candidate": { "$ref": "pod-discovery.v1.schema.json#/$defs/candidate" },
+    "expiresAtMs": { "type": "integer", "minimum": 0 },
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hostId", "name", "firmwareVersion", "fingerprint", "wifiConfigured"],
+      "properties": {
+        "hostId": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "productId": { "type": "string" },
+        "firmwareVersion": { "type": "string", "minLength": 1 },
+        "fingerprint": { "type": "string", "minLength": 1 },
+        "wifiConfigured": { "type": "boolean" }
+      }
+    },
+    "networks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ssid", "rssi", "secured"],
+        "properties": {
+          "ssid": { "type": "string", "minLength": 1 },
+          "rssi": { "type": "integer" },
+          "secured": { "type": "boolean" }
+        }
+      }
+    },
+    "addresses": {
+      "description": "IPv4 LAN addresses reported by the Host; may be empty",
+      "type": "array",
+      "items": { "type": "string", "format": "ipv4" }
+    },
+    "claimToken": {
+      "description": "One-time token for the first claim of this Host",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{43}$"
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "bluetooth_unavailable",
+            "device_busy",
+            "disconnected",
+            "code_rejected",
+            "code_locked",
+            "wifi_auth_failed",
+            "wifi_not_found",
+            "wifi_failed",
+            "session_timeout"
+          ]
+        },
+        "message": { "type": "string" },
+        "detail": { "type": "string" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "enum": ["failed", "timed_out"] } } },
+      "then": { "required": ["error"] }
+    },
+    {
+      "if": {
+        "properties": {
+          "state": { "not": { "enum": ["failed", "timed_out", "awaiting_code", "awaiting_wifi"] } }
+        }
+      },
+      "then": { "not": { "required": ["error"] } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "awaiting_code" } }, "required": ["error"] },
+      "then": { "properties": { "error": { "properties": { "code": { "const": "code_rejected" } } } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "awaiting_wifi" } }, "required": ["error"] },
+      "then": {
+        "properties": {
+          "error": {
+            "properties": {
+              "code": { "enum": ["wifi_auth_failed", "wifi_not_found", "wifi_failed"] }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "state": { "const": "completed" } } },
+      "then": { "required": ["host"] },
+      "else": { "not": { "required": ["claimToken"] } }
+    }
+  ]
+}

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

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/pod-commission.v1.schema.json",
+  "title": "Native-client pod commissioning session snapshot",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sessionId", "revision", "state", "candidate", "expiresAtMs"],
+  "properties": {
+    "sessionId": { "type": "string", "minLength": 1 },
+    "revision": { "type": "integer", "minimum": 0 },
+    "state": {
+      "enum": [
+        "connecting",
+        "awaiting_code",
+        "securing",
+        "reading_info",
+        "awaiting_wifi",
+        "joining_wifi",
+        "awaiting_authorization",
+        "issuing",
+        "delivering",
+        "activating",
+        "completed",
+        "failed",
+        "cancelled",
+        "timed_out"
+      ]
+    },
+    "candidate": { "$ref": "pod-discovery.v1.schema.json#/$defs/candidate" },
+    "expiresAtMs": { "type": "integer", "minimum": 0 },
+    "device": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["deviceId", "model", "firmwareVersion", "wifiConfigured"],
+      "properties": {
+        "deviceId": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "firmwareVersion": { "type": "string", "minLength": 1 },
+        "wifiConfigured": { "type": "boolean" }
+      }
+    },
+    "networks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ssid", "rssi", "secured"],
+        "properties": {
+          "ssid": { "type": "string", "minLength": 1 },
+          "rssi": { "type": "integer" },
+          "secured": { "type": "boolean" }
+        }
+      }
+    },
+    "authorization": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["userId", "userName", "scopes", "defaultScopeId"],
+      "properties": {
+        "userId": { "type": "string", "minLength": 1 },
+        "userName": { "type": "string" },
+        "scopes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["scopeId", "name"],
+            "properties": {
+              "scopeId": { "type": "string", "minLength": 1 },
+              "name": { "type": "string" }
+            }
+          }
+        },
+        "defaultScopeId": { "type": "string", "minLength": 1 }
+      }
+    },
+    "podId": { "type": "string", "minLength": 1 },
+    "mode": { "enum": ["reprovision"] },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "bluetooth_unavailable",
+            "device_busy",
+            "disconnected",
+            "code_rejected",
+            "code_locked",
+            "wifi_auth_failed",
+            "wifi_not_found",
+            "wifi_failed",
+            "issue_failed",
+            "delivery_failed",
+            "activation_failed",
+            "session_timeout"
+          ]
+        },
+        "message": { "type": "string" },
+        "detail": { "type": "string" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "enum": ["failed", "timed_out"] } } },
+      "then": { "required": ["error"] }
+    },
+    {
+      "if": {
+        "properties": {
+          "state": { "not": { "enum": ["failed", "timed_out", "awaiting_code", "awaiting_wifi"] } }
+        }
+      },
+      "then": { "not": { "required": ["error"] } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "awaiting_code" } }, "required": ["error"] },
+      "then": { "properties": { "error": { "properties": { "code": { "const": "code_rejected" } } } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "awaiting_wifi" } }, "required": ["error"] },
+      "then": {
+        "properties": {
+          "error": { "properties": { "code": { "enum": ["wifi_auth_failed", "wifi_not_found", "wifi_failed"] } } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "state": { "const": "awaiting_authorization" } } },
+      "then": { "required": ["authorization"] }
+    },
+    {
+      "if": { "properties": { "state": { "const": "completed" } }, "not": { "required": ["mode"] } },
+      "then": { "required": ["podId"] }
+    },
+    {
+      "if": { "required": ["mode"] },
+      "then": { "not": { "anyOf": [{ "required": ["podId"] }, { "required": ["authorization"] }] } }
+    }
+  ]
+}

package/schema/pod-credential-status.v1.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/pod-credential-status.v1.schema.json",
+  "title": "Lion pod credential status, as seen by the owning user",
+  "type": "object",
+  "required": ["podId", "status"],
+  "properties": {
+    "podId": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["pending", "active", "absent"] },
+    "activatedAt": { "type": "integer", "minimum": 0 }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "active" } } },
+      "then": { "required": ["activatedAt"] }
+    }
+  ]
+}