@mhome/app-facade-protocol 1.42.2 → 1.44.0

package/README.md

@@ -46,7 +46,7 @@ requests carry a stable `details.reason`. See
 [the contract](contract/pod-commissioning-v1.md). Targets, BLE constants, session
 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`;
-the owner's credential status is `schema/pod-credential-status.v1.schema.json`.
+User Pod enrollment uses a one-time login approval; activation is confirmed on the paired device.
 
 `host_provision` (1.34.0) defines BLE Wi-Fi provisioning of embedded Hosts
 (`/local/host/provision/*`) on the same BLE layer; discovery candidates carry
@@ -69,23 +69,21 @@ Host inventory and management on the selected Hub through `/app/system/hosts/*`.
 A native Client remains the path when no local Hub is selected. Lion's legacy
 controller annotations and non-`/app/*` protocols are outside this contract.
 
-### System plugin catalog
+### Plugin catalog
 
-`/app/plugin/catalog/list` returns `manifest/plugin-catalog.v1.json` from Cloud,
-without requiring a local Space or connected Hub. Authentication and Space
-membership still apply. Core also serves this catalog for clients with an older
-routing manifest. The response schema is `schema/plugin-catalog.v1.schema.json`.
+`/app/plugin/catalog/list` reads publisher-signed platform indexes under
+`https://install.mhome.ai/plugins/stable/<platform>/catalog.bundle.json`.
+Cloud serves this browsing view without a connected Hub. Authentication and
+Space membership still apply. Core exposes the same response for local callers.
+The response schema is `schema/plugin-catalog.v1.schema.json`; `platformErrors`
+reports unavailable indexes while preserving results from other platforms.
 
-The catalog describes supported types, not installed software or bindings.
-`componentId` joins to Host runtime inspection; `nodeType` joins to existing
-Plugin candidate and installed/binding queries. Platform installability and
-versions come from the Host release catalog, not this directory.
-
-Core and Cloud embed generated copies. After editing the catalog, run
-`node scripts/sync-plugin-catalog.mjs --write <core-resource> <cloud-resource>`
-from the Foundation root; omit `--write` to check conformance. Resource paths are
-`src/application/plugin-catalog.v1.json` (Core) and
-`src/main/resources/app/plugin-catalog.v1.json` (Cloud module-service).
+Foundation defines contracts, not the list of Plugins. Plugin source owns its
+definition; releases publish it with each immutable per-version manifest.
+`componentId` joins Host inventory, and `nodeType` joins candidates and bindings.
+Catalog availability is a browsing hint. Binding uses `/node/metadata` from the
+actual running Node, verifies publisher evidence, and persists that definition
+with the binding. A cached latest catalog never overrides installed facts.
 
 ## Shared messaging codes (1.10)
 
@@ -94,7 +92,8 @@ Code creation may omit bot/account and group/surface identifiers. The receiving
 ## Space runtime observations
 
 `/app/system/instances/get` reads Space instances; `/app/system/clients/get` reads
-client sessions; `/app/system/hosts/get`, `/app/system/hosts/runtime`, and
-`/app/system/hosts/claim` are Hub-vantage Host inventory, management, and
-first-claim. These remain Hub-owned with cloud relay and Space membership. See
-[SYSTEM.md](SYSTEM.md).
+Client sessions. Host inventory and operations use `/app/system/hosts/get` and
+`/app/system/hosts/runtime`, forwarding cloud-issued User tokens through the
+current Core. First claim is direct LAN only. See [SYSTEM.md](SYSTEM.md).
+
+Business operation permissions are declared once in [the authorization manifest](manifest/authorization.v1.json), consumed by Core and Lion. See [business authorization](contract/authorization-v1.md).

package/contract/host-provisioning-v1.md

@@ -134,18 +134,17 @@ Session states, in order: `connecting`, `awaiting_code`, `securing`,
 (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
-delivered, in a re-provision window, and with Hosts that predate claim tokens.
+delivered, in a re-provision window.
 No other state carries `claimToken`.
 
-The first claim (TOFU) of a Host that was provisioned over BLE must present this
-token: `/app/system/hosts/claim` takes `{"hostId","claimToken"?}` and the native
-`host.claim` passes it through to the Host's offline claim, `POST /v1/auth/claim`
-`{"proof","claimToken"?}` (`core-api` `host::auth::ClaimRequest`). Clients send
-`claimToken` only when they have one, because older Hosts reject unknown fields.
-While a token is outstanding the Host answers a claim without it, or with a
-different one, with 403 `{"code":"HOST_CLAIM_TOKEN_REQUIRED"}`. The token stays valid until a claim succeeds or the Host is
-factory reset; the UI claims automatically with it after `completed`. Hosts
-that were never provisioned over BLE keep the plain first claim.
+The first claim (TOFU) after BLE provisioning must include the returned token.
+Native `host.claim` passes it to `POST /v1/auth/claim`, alongside the environment,
+cloud proof and direct Client exchange secret (`core-api::host::access::ClaimRequest`).
+There is no Core-proxied first-claim route. The Host rejects a missing or incorrect
+provisioning token with 403 `HOST_CLAIM_TOKEN_REQUIRED`. The token remains valid
+until claim succeeds or factory reset. The App claims automatically after
+`completed`. Hosts that were not provisioned over BLE use the ordinary direct
+LAN claim flow. See the Foundation Host management authorization contract.
 
 Error codes are the pod session codes without the credential ones:
 `bluetooth_unavailable`, `device_busy`, `disconnected`, `code_rejected` (retry

package/contract/pod-commissioning-v1.md

@@ -130,7 +130,7 @@ the response also carries `"mode":"reprovision"` and `wifiConfigured` is false
 
 `pod-credential` requests:
 
-- `{"op":"deliver","clientMode":"user","podId","refreshToken","scopeId","cloudApi","cloudWs"}` →
+- `{"op":"deliver","clientMode":"user","podId","loginGrant","scopeId","cloudApi","cloudWs"}` →
   `{"ok":true,"state":"activating"}`. Accepted only in `wifi_connected` outside a
   Wi-Fi change window; otherwise `{"ok":false,"state":<current pod state>,"reason"}`
   with `reason` `invalid_payload` (a missing or malformed field, including a
@@ -220,136 +220,51 @@ Runtime states after commit:
   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.
-
-## 5. Lion credential API
-
-All bodies are JSON. Errors use the standard Lion envelope
-`{"error","message","details"?}`. Credential failures are `UNAUTHORIZED` with one
-of these `message` values: `pod_credential_invalid` (unknown pod, wrong or
-revoked refresh token, or an owner account that no longer exists),
-`pod_proof_invalid`, `pod_proof_replayed`, `pod_activation_expired`. A pod treats
-`pod_credential_invalid` and `pod_activation_expired` as revocation. Renaming a
-pod the caller does not own, or that does not exist, is `NOT_FOUND` with
-`pod_not_found`.
-
-### Issue
-
-`POST /api/v1/pod/credential/issue`, user `Authorization`, `ScopeId` header.
-
-```json
-{
-  "deviceId": "a0b1c2d3e4f5",
-  "model": "S1",
-  "platform": "esp32c5",
-  "firmwareVersion": "0.3.0",
-  "name": "MeowPod S1",
-  "identity": { "keyId": "p256:…", "alg": "ES256", "x": "…", "y": "…", "fingerprint": "…" },
-  "clientId": "issuing client id"
-}
-```
-
-`deviceId` matches `[A-Za-z0-9._:-]{1,64}`; `model` and `name` are 1–64
-characters, `platform` and `firmwareVersion` at most 64, `clientId` at most 128. Lion requires Space membership for `ScopeId`, validates the identity, and
-creates a `pending` credential that must activate before `activateBefore`
-(issue time + 10 minutes). Response `{"podId","refreshToken","activateBefore"}`.
-
-### Refresh and activation
-
-`POST /api/v1/pod/token/refresh`, body `{"podId","refreshToken","proof"}`.
-
-`proof` is a compact ES256 JWS signed by the identity key: header `kid=keyId`;
-claims `iss` and `sub` = `podId`, a single-valued `aud` = `pod-token-refresh`,
-`token_hash` = unpadded base64url SHA-256 of the UTF-8 refresh token (including
-`pod-`), `iat`, `exp` with `0 ≤ exp - iat ≤ 120 s`, and a unique `jti` of at most
-128 characters. Lion allows 120 s clock skew and remembers each `jti` for
-7 minutes (proof lifetime plus twice the skew, plus a minute), longer than any
-proof can be accepted; a reused `jti` in that window fails with
-`pod_proof_replayed`.
-
-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
-later refresh fails with `pod_credential_invalid`. Response
-`{"accessToken","expiresIn"}`.
-
-### Status
-
-`POST /api/v1/pod/credential/status`, user `Authorization`, body `{"podId"}` →
-`{"podId","status","activatedAt"?}` with `status` one of `pending`, `active`,
-`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`. It is informational;
-commissioning success requires the device confirmation described in section 7.
-
-### Reset and cleanup
-
-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
-
-`POST /api/v1/pod/list` (user) returns `{"pods":[…]}`, the user's active pods
-and unexpired pending pods, each
-`{"podId","name","deviceId","model","platform","firmwareVersion","identityFingerprint","status","issuedAt","activatedAt"}`.
-`POST /api/v1/pod/rename` `{"podId","name"}` (user) returns the updated pod.
-
-### Tokens
-
-- Access: `pod-` + HS256 JWT. Claims: `iss`, `aud`, `sub` = `podId`, `user_id`,
-  `tenant_id`, `device_id`, `token_type` = `pod_access`, `iat`, `exp` (3600 s),
-  `jti`. The signing key is derived from the Hub secret with HMAC-SHA256 over the
-  label `mhome-pod-access-v1`, so Hub and pod tokens never verify as each other.
-- Refresh: `pod-` + 43-character base64url of 32 random bytes. Lion stores only
-  its SHA-256. It never rotates; the identity proof binds it to the device.
-- Pods send `Authorization: Bearer pod-…` (and `"token":"Bearer pod-…"` on the
-  WebSocket). `pod-` is dispatched by prefix before any JWT parsing. Only the cloud WebSocket
-  `/auth` and `/api/v1/hub/token/exchange` accept pod access tokens. Every other
-  API keeps accepting user tokens only. No target allowlist applies in v1.
-- Lion checks an access token against the stored credential on every use, so a
-  revoked or superseded credential stops working before its `exp`.
-- A pod session acts as its user across all of that user's Spaces. A cloud
-  WebSocket session authenticated with a pod access token remembers the `podId`
-  and the token `exp`. Lion closes it with a policy-violation close whose reason
-  is `POD_TOKEN_EXPIRED` at `exp` and `POD_REVOKED` when the pod is revoked;
-  revocations reach sessions on every Lion instance through a shared event
-  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 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.
+Linux uses its OS time service and ESP uses background SNTP. User login proofs
+require usable UTC and cloud TLS retains normal CA and date validation. Space
+Client local authentication pins the enrolled Core identity and signs a fresh
+nonce; Core checks credential expiry with its own clock. HTTP `Date` is diagnostic
+and does not override the system clock or relax TLS validation.
+
+## 5. User Pod login approval
+
+`POST /api/v1/pod/login/approve` uses the assisting App's ordinary User
+Authorization. Its body contains `deviceId`, `model`, `platform`,
+`firmwareVersion`, `name`, `identity` (P-256 keyId, alg, x, y, fingerprint), and
+optional `clientId`. It has no Space authorization header or issued-Space scope.
+Lion returns `{podId, loginGrant, activateBefore}`. The random approval expires
+in ten minutes and is bound to this User and the Pod identity key. It is not a
+login refresh token. The helper must never deliver its own login credentials.
+
+The App delivers the approval through the paired LAN channel. `scopeId` in the
+device delivery selects the initial UI Space; it does not constrain the User
+identity or grant Space authority. The device independently redeems the approval
+at `POST /api/v1/pod/login/redeem` with `{podId, loginGrant, proof}`. The proof is
+signed by the paired device's key with audience `user-device-login` and binds the
+approval. Lion coordinates Cognito CUSTOM_AUTH to create the device's own
+ordinary Cognito session. Approval redemption is single-use. Only the device
+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.
+There is no cloud credential-status polling or server-side Pod revocation flow.
+Factory reset clears device credentials and rotates the pairing identity.
 
 ## 6. Pod runtime authentication
 
-- Cloud `/auth`: `{"token":"Bearer pod-…","devToken":null,"source":"pod","deviceId","activeScope"}`,
-  then `/focus`. Lion rejects `source=pod` without a pod token, a pod token
-  with any other source, and a `deviceId` other than the one the credential was
-  issued to.
-- The pod refreshes its access token proactively, 2 minutes before `exp`, and
-  re-authenticates the cloud session with the new token. A refresh rejected
-  with `pod_credential_invalid` or `pod_activation_expired` moves the pod to
-  `needs_recommission`.
-- Space switching: the pod chooses among the Spaces returned by `/auth` and
-  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, 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.
+User Pods use ordinary Cognito User authentication for cloud business traffic.
+Local Core connections use the same Lion-issued local credentials and Core
+verification as other User Clients. Each credential retains the actual User
+principal; initial Space selection is not embedded in a special Pod login token.
+Space Pods use only their enrolled local Core and their Space credential; they
+receive no User login grant or Cognito session. See section 8 for Space enrollment.
+
+Setup succeeds only after the paired device reports `commissioned`, meaning its
+business connection has authenticated. Cloud approval issuance alone is not
+activation. Reset clears the local credentials; an unreachable device is not
+considered reset.
 
 ## 7. Native Client targets
 
@@ -447,11 +362,12 @@ scan runs waits for it. `revision` increases on every observable change.
 `delivering` on it is `activateBefore` plus 30 seconds.
 
 Only the device's durable `commissioned` response confirms successful setup.
-Lost LAN 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 selects the network-ready device again, establishes
-a fresh LAN session and reads its actual activation status.
+Lost LAN confirmation triggers at most three reconnections to this attempt's
+endpoint. Each connection reestablishes channel security and checks device,
+environment and enrollment identity before reading status. Never issue or
+deliver a second credential during recovery. Failure to confirm, or expiry,
+ends the attempt; the user may then select the network-ready device again.
+Cloud state alone never confirms successful device setup.
 
 A refused `deliver` fails with `delivery_failed` carrying the pod's `reason`
 (`invalid_payload` or `wrong_state`) in `detail`. When the pod
@@ -480,7 +396,7 @@ The schemas are `schema/pod-discovery.v1.schema.json` and
 
 `POST /api/v1/pod/space/credential/issue` uses the assisting App's user
 `Authorization` and `ScopeId`, with the same device identity request as personal
-issuance. Any current member may assist. The Space must be local and have one
+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.