@mhome/core-protocol 1.15.11 → 1.17.0

package/contract/host-permissions.md

@@ -0,0 +1,113 @@
+# Host permissions contract
+
+Host coordinates permissions for this computer and the services it manages. It
+never performs a service's protected business operations on that service's behalf.
+Client/Desktop application permissions remain outside this report. No permission
+request depends on a Space or enables a plugin in a Space.
+
+This is a direct development cutover. There is one report model and no legacy
+serialization, implicit component selection or alternative compatibility route.
+Update Foundation consumers together after publishing the matching packages.
+
+## Declaration and executor
+
+Each service keeps its source-root `permission.yml` and packages it. The installed
+package is the sole source of desired permissions. Host loads declarations into
+its installed-service inventory on startup and when packages change. Status reads
+use that memory snapshot; they do not scan packages or maintain a database copy.
+Stopped services retain their requirements. Invalid declarations remain visible.
+
+Each `HostPermission` is one component and one permission: `componentId`,
+`componentName`, `permission`, `feature`, `reason`, `observation`, `error`, and
+`supportedActions`. There are no grouped subjects or selected substitute executors.
+`PermissionObservation.processId` identifies the actual executing process, not an
+OS grant identity. A sidecar reports its own observation through its service.
+Reading status must not start an absent sidecar or substitute its parent's grant.
+
+A helper can share its responsible application's consent without any grouping
+fields in this protocol. Equal PIDs, signing teams or states alone do not establish
+shared grants. Automation keys remain distinct per target application.
+
+## Transport and actions
+
+- `GET /v1/permissions` returns `HostPermissions` for installed requirements,
+  including stopped services and declaration/collection failures.
+- `POST /internal/permissions/request` performs one explicit request or probe in
+  the selected service's actual execution context. It returns `{ "ok": true }`
+  once submitted, without collecting another snapshot or waiting for user consent.
+- `POST /internal/permissions/open-settings` opens the platform settings pane.
+  It returns `{ "ok": true }` after opening. Status is queried separately.
+- Both POSTs take `HostPermissionRequest`. `hostId`, `componentId` and `permission`
+  are mandatory. The component must declare that exact key. The caller cannot assert locality
+  or an arbitrary Settings URL.
+- Require valid local control credentials and matching Host identity. Native
+  Desktop and CLI use Client IPC. Remote Hosts accept status only. Do not send
+  local control credentials to discovered addresses or redirects. A future Hub
+  read can relay a report but cannot relay mutations or decide grants.
+- A service's `GET /internal/permissions` returns `ServicePermissions`. The outer
+  PID identifies the reporting service; individual observations can identify its
+  sidecar. The service rejects requests outside its declared requirements.
+
+Foundation owns native request deduplication in the actual executor. Transport
+timeouts do not release that ownership. UI polls status every two seconds while
+managing permissions and refreshes on focus; a pending read is shared. CLI batch
+requests query once after submission. Bound collection concurrency and the whole
+snapshot latency so a stalled executor cannot hold every other service indefinitely.
+
+## Authorization observations
+
+`PermissionObservation.state` describes application consent only. The report
+contains declared requirements and authorization observations; it does not collect
+or carry resource availability or business-operation results. `granted` and
+`notRequired` satisfy a requirement when the observation has valid evidence and
+no errors. Missing, denied or unreadable observations remain unresolved.
+
+- `system`: passive native authorization query and its timestamp.
+- `platform`: platform consent semantics, not measured resource availability.
+- `probe`: historical evidence from an explicit operation, with its timestamp.
+- `unavailable`: a reliable consent observation could not be obtained.
+- `notRequired`: this native backend has no application-consent step. It does not
+  bypass users/groups, D-Bus policies, device rules, sessions, portals or sandboxes.
+
+Passive report reads never request authorization, probe Local Network, scan
+Bluetooth, launch an Automation target, restart a service or open Settings.
+Local Network's last explicit probe is historical; ordinary Refresh cannot make
+it a fresh OS setting. Keep cached reports visibly stale when collection fails.
+Missing/malformed declarations remain errors; an empty list is not proof of a
+complete inventory. Do not grant by default on other OSes.
+
+## macOS and Linux
+
+macOS keeps Host's existing responsible application and managed process tree.
+Share identity only for validated permission/launch combinations. Services and
+sidecars retain their own valid signatures and required hardened-runtime
+entitlements. Signatures and launch association alone are not proof that an OS
+grant is shared. Unsupported sharing stays a separate request; it never causes
+business operations to migrate into Host. Never modify a signed plist in place.
+
+Foundation's macOS status functions remain in-process and passive. Bluetooth's
+explicit request initializes Core Bluetooth to request consent; merely opening
+Settings is not a first-request implementation. When the actual user of BLE is
+Matter's Node sidecar, obtain and request its state there. No Matter.js fork or
+Host BLE broker is implied by this contract.
+
+Linux native services use the configured ordinary runtime account and existing
+system interfaces, including BlueZ D-Bus. Foundation reports the absence of a
+native application-consent step as `notRequired`. Resource health belongs to the
+service's own diagnostics and does not affect this permission report.
+An installation preflight collects concrete missing conditions. An administrator
+may authorize a bounded, idempotent setup step for those conditions; service
+manifests must not supply privileged commands. Runtime processes remain ordinary
+users. Account/session refresh requirements remain explicit. New device or
+capability requirements can require additional setup. Container and sandbox
+policies are separate deployment conditions, not automatically inherited grants.
+
+## Acceptance
+
+Test passive reads without prompts; real signed allow/deny/revoke/relaunch
+behavior; shared grants across two executors; sidecar and stopped-service observations; conflicting per-component states;
+per-target Automation; cross-host mutation rejection; required component
+selection; incomplete manifests; bounded collection; native request deduplication; and
+Linux `notRequired` without any resource observation. Test Linux setup first as
+a dry-run and verify effective access in the intended ordinary runtime session.
+Signing fixtures and mocked status tests do not prove TCC attribution.

package/manifest/core.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.core.v1",
-  "contractVersion": "1.15.11",
+  "contractVersion": "1.17.0",
   "protocols": {
     "agentGateway": {
       "submitTarget": "/agent/submit",
@@ -76,6 +76,12 @@
         "failed",
         "unknown"
       ]
+    },
+    "hostPermissions": {
+      "schema": "schema/host-permissions.schema.json",
+      "statusPath": "/v1/permissions",
+      "requestPath": "/internal/permissions/request",
+      "settingsPath": "/internal/permissions/open-settings"
     }
   },
   "hostManagement": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/core-protocol",
-  "version": "1.15.11",
+  "version": "1.17.0",
   "description": "Build-time protocol artifacts for mhome.core",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,9 +1,10 @@
 {
   "protocol": "mhome.core",
-  "contractVersion": "1.15.11",
+  "contractVersion": "1.17.0",
   "manifest": "manifest/core.v1.json",
   "schemas": {
     "hostManagementRequest": "schema/host-management-request.v1.schema.json",
+    "hostPermissions": "schema/host-permissions.schema.json",
     "normalizedInbound": "schema/normalized-inbound.v4.schema.json",
     "messagingCommands": "schema/messaging-commands.v1.schema.json",
     "interactionFlowNode": "schema/interaction-flow-node.v1.schema.json",

package/schema/host-permissions.schema.json

@@ -0,0 +1,303 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/core/host-permissions.schema.json",
+  "title": "Host permission reports and local requests",
+  "$defs": {
+    "PermissionKey": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id"
+          ],
+          "properties": {
+            "id": {
+              "enum": [
+                "localNetwork",
+                "bluetooth",
+                "microphone",
+                "reminders"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id",
+            "targetBundleId"
+          ],
+          "properties": {
+            "id": {
+              "const": "automation"
+            },
+            "targetBundleId": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "PermissionObservation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "permission",
+        "processId",
+        "state",
+        "evidence",
+        "observedAtMs",
+        "error"
+      ],
+      "properties": {
+        "permission": {
+          "$ref": "#/$defs/PermissionKey"
+        },
+        "processId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "state": {
+          "enum": [
+            "unknown",
+            "notDetermined",
+            "granted",
+            "notRequired",
+            "denied",
+            "restricted",
+            "unsupported"
+          ]
+        },
+        "evidence": {
+          "enum": [
+            "system",
+            "platform",
+            "probe",
+            "unavailable"
+          ]
+        },
+        "observedAtMs": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "error": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "evidence": {
+                "const": "probe"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "observedAtMs": {
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          }
+        }
+      ]
+    },
+    "HostPermission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "componentId",
+        "componentName",
+        "permission",
+        "feature",
+        "reason",
+        "observation",
+        "error",
+        "supportedActions"
+      ],
+      "properties": {
+        "componentId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "componentName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "permission": {
+          "$ref": "#/$defs/PermissionKey"
+        },
+        "feature": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "observation": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/PermissionObservation"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "error": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "supportedActions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "request",
+              "openSettings"
+            ]
+          }
+        }
+      }
+    },
+    "PermissionDeclarationError": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "componentId",
+        "message"
+      ],
+      "properties": {
+        "componentId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "HostPermissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "hostId",
+        "hostVersion",
+        "platform",
+        "observedAtMs",
+        "permissions",
+        "declarationErrors"
+      ],
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hostVersion": {
+          "type": "string",
+          "minLength": 1
+        },
+        "platform": {
+          "type": "string",
+          "minLength": 1
+        },
+        "observedAtMs": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/HostPermission"
+          }
+        },
+        "declarationErrors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PermissionDeclarationError"
+          }
+        }
+      }
+    },
+    "HostPermissionRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "hostId",
+        "componentId",
+        "permission"
+      ],
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "componentId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "permission": {
+          "$ref": "#/$defs/PermissionKey"
+        }
+      }
+    },
+    "ServicePermissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "processId",
+        "permissions"
+      ],
+      "properties": {
+        "processId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PermissionObservation"
+          }
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/$defs/HostPermissions"
+    },
+    {
+      "$ref": "#/$defs/HostPermissionRequest"
+    },
+    {
+      "$ref": "#/$defs/ServicePermissions"
+    }
+  ]
+}