@mhome/app-facade-protocol 1.3.0 → 1.4.0

package/README.md

@@ -3,6 +3,13 @@
 Canonical public protocol shared by MeowLink clients, MeowCore, the CLI,
 Agents, and cloud adapters.
 
+The package also carries the explicitly private `/local/*` native-daemon
+extension. `/app/*` is portable and may be routed according to the public
+routing manifest. `/local/*` is an exact allowlist for the current MeowLink
+native client process and must never be forwarded to cloud, Hub, or Host
+connections. Hub `/app/*` calls are direct-only `FacadeCall`s; Hub `/local/*`
+calls carry the domain input directly and never use the public envelope.
+
 Every `/app/*` request uses the strict `FacadeCall` envelope. Invocation
 metadata lives in `control`; the domain request lives in `input`. The crate
 owns public targets, request/response/event schemas, and stable operation

package/fixtures/hub-state.configured.json

@@ -0,0 +1,17 @@
+{
+  "scopeId": "scope-1",
+  "configured": true,
+  "hub": {
+    "id": "hub-1",
+    "name": "Home Hub",
+    "type": "local",
+    "hostId": "host-1",
+    "isTest": false,
+    "status": "ready",
+    "cloud": {
+      "connectionStatus": "connected",
+      "lastConnectedAt": 1700000000000,
+      "firmwareVersion": "1.0.0"
+    }
+  }
+}

package/fixtures/hub-state.revoked.json

@@ -0,0 +1,15 @@
+{
+  "scopeId": "scope-1",
+  "configured": false,
+  "operation": {
+    "kind": "REMOVE",
+    "state": "RUNNING",
+    "phase": "CLEARING_LOCAL_DATA",
+    "startedAt": 1700000000000,
+    "hubId": "hub-old"
+  },
+  "revocation": {
+    "hubId": "hub-old",
+    "revocationId": "revoke-1"
+  }
+}

package/fixtures/local-hub-state.configured.json

@@ -0,0 +1,22 @@
+{
+  "scopeId": "scope-1",
+  "configured": true,
+  "hub": {
+    "id": "hub-1",
+    "name": "Home Hub",
+    "type": "local",
+    "hostId": "host-1",
+    "isTest": false,
+    "status": "ready",
+    "cloud": {
+      "connectionStatus": "connected"
+    },
+    "local": {
+      "discovered": true,
+      "connected": true,
+      "connectionStatus": "connected",
+      "hostName": "Living Room Mac",
+      "version": "1.0.0"
+    }
+  }
+}

package/manifest/app-facade.v1.json

@@ -1,10 +1,15 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
   "domains": {
+    "hub": {
+      "targets": "manifest/hub-targets.v1.json",
+      "cloudStateTarget": "/app/hub/get",
+      "nativeCompositeTarget": "/local/hub/get"
+    },
     "messaging": {
       "targets": "manifest/targets.v1.json"
     },

package/manifest/hub-targets.v1.json

@@ -0,0 +1,20 @@
+{
+  "manifest": "mhome.hub.targets.v1",
+  "contractVersion": "1.0.0",
+  "appTargets": [
+    "/app/hub/get",
+    "/app/hub/remove",
+    "/app/hub/cache/clear"
+  ],
+  "localTargets": [
+    "/local/hub/get",
+    "/local/hub/candidates",
+    "/local/hub/add/start",
+    "/local/hub/add/confirm",
+    "/local/hub/add/status",
+    "/local/hub/add/cancel"
+  ],
+  "appInvocationModes": ["direct"],
+  "localPayload": "domainInput",
+  "localForwardable": false
+}

package/manifest/routing.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.routing.v1",
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode",
@@ -16,6 +16,9 @@
     "cloudTargets": [
       "/app/agent/context/get",
       "/app/credit/record",
+      "/app/hub/cache/clear",
+      "/app/hub/get",
+      "/app/hub/remove",
       "/app/system/feedback/submit",
       "/app/timeline/entity/latest/list"
     ],

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.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.3.0",
+  "version": "1.4.0",
   "description": "Build-time protocol artifacts for mhome.app-facade",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,12 +1,14 @@
 {
   "protocol": "mhome.app-facade",
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "call": "schema/facade-call.v1.schema.json",
     "frame": "schema/messaging-frame.v3.schema.json",
     "interactionFlow": "schema/interaction-flow-app.v1.schema.json",
-    "routing": "schema/routing.v1.schema.json"
+    "routing": "schema/routing.v1.schema.json",
+    "hubState": "schema/hub-state.v1.schema.json",
+    "localHubState": "schema/local-hub-state.v1.schema.json"
   },
   "fixtures": {
     "valid": "fixtures",

package/schema/hub-state.v1.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/hub-state.v1.schema.json",
+  "title": "Authoritative cloud Hub lifecycle state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scopeId", "configured"],
+  "properties": {
+    "scopeId": { "type": "string", "minLength": 1 },
+    "configured": { "type": "boolean" },
+    "hub": { "$ref": "#/$defs/hub" },
+    "operation": { "$ref": "#/$defs/operation" },
+    "revocation": { "$ref": "#/$defs/revocation" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "configured": { "const": true } }, "required": ["configured"] },
+      "then": { "required": ["hub"] },
+      "else": { "not": { "required": ["hub"] } }
+    }
+  ],
+  "$defs": {
+    "hub": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "hostId", "isTest", "status", "cloud"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "type": { "type": "string", "minLength": 1 },
+        "hostId": { "type": "string", "minLength": 1 },
+        "isTest": { "type": "boolean" },
+        "status": { "type": "string", "minLength": 1 },
+        "cloud": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "connectionStatus": { "type": "string" },
+            "lastConnectedAt": { "type": "integer" },
+            "firmwareVersion": { "type": "string" }
+          }
+        }
+      }
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "state", "phase", "startedAt"],
+      "properties": {
+        "kind": { "enum": ["SETUP", "REMOVE"] },
+        "state": { "enum": ["RUNNING", "FAILED"] },
+        "phase": {
+          "enum": [
+            "WAITING_FOR_HUB",
+            "PREPARING_DATA",
+            "SYNCING_DATA",
+            "BACKING_UP_DATA",
+            "FENCING_CLOUD",
+            "CLEARING_LOCAL_DATA",
+            "FINALIZING",
+            "CLEANING_UP"
+          ]
+        },
+        "startedAt": { "type": "integer" },
+        "expiresAt": { "type": "integer" },
+        "hostId": { "type": "string" },
+        "hubId": { "type": "string" },
+        "failure": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["reason"],
+          "properties": {
+            "reason": { "type": "string", "minLength": 1 },
+            "at": { "type": "integer" }
+          }
+        }
+      }
+    },
+    "revocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hubId", "revocationId"],
+      "properties": {
+        "hubId": { "type": "string", "minLength": 1 },
+        "revocationId": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schema/local-hub-state.v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/local-hub-state.v1.schema.json",
+  "title": "Native-client composite Hub state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scopeId", "configured"],
+  "properties": {
+    "scopeId": { "type": "string", "minLength": 1 },
+    "configured": { "type": "boolean" },
+    "hub": { "$ref": "#/$defs/localHub" },
+    "operation": { "$ref": "hub-state.v1.schema.json#/$defs/operation" },
+    "revocation": { "$ref": "hub-state.v1.schema.json#/$defs/revocation" },
+    "pairing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionId", "state", "phase", "startedAt", "expiresAt"],
+      "properties": {
+        "sessionId": { "type": "string", "minLength": 1 },
+        "state": { "type": "string", "minLength": 1 },
+        "phase": { "type": "string", "minLength": 1 },
+        "startedAt": { "type": "integer" },
+        "expiresAt": { "type": "integer" },
+        "hostId": { "type": "string" },
+        "hubId": { "type": "string" },
+        "failure": { "$ref": "hub-state.v1.schema.json#/$defs/operation/properties/failure" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "configured": { "const": true } }, "required": ["configured"] },
+      "then": { "required": ["hub"] },
+      "else": { "not": { "required": ["hub"] } }
+    }
+  ],
+  "$defs": {
+    "localHub": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "hostId", "isTest", "status", "cloud", "local"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "type": { "type": "string", "minLength": 1 },
+        "hostId": { "type": "string", "minLength": 1 },
+        "isTest": { "type": "boolean" },
+        "status": { "type": "string", "minLength": 1 },
+        "cloud": { "$ref": "hub-state.v1.schema.json#/$defs/hub/properties/cloud" },
+        "local": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["discovered", "connected"],
+          "properties": {
+            "discovered": { "type": "boolean" },
+            "connected": { "type": "boolean" },
+            "connectionStatus": { "type": "string" },
+            "hostName": { "type": "string" },
+            "version": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}