ZaparooProject · wizzomafizzo · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -213,9 +213,9 @@ This access is also allowed when a connection is made over a WebSocket Secure (w
 Core evaluates permissions for each request from connection locality and paired-client role:
 
 - **Localhost** requests originate from Core's device and have full access.
-- Paired **admin** clients have the `profiles.manage` and `settings.write` capabilities.
-- Paired **member** clients can use day-to-day methods, but cannot manage profiles or change protected settings.
-- **Unpaired remote** clients are possible only when encryption is disabled. For backward compatibility they receive admin capabilities, but methods explicitly restricted to localhost or to a paired admin still reject them.
+- Paired **admin** clients have the `profiles.manage`, `settings.write`, and `update.apply` capabilities.
+- Paired **member** clients can use day-to-day methods, but cannot manage profiles, change protected settings, or apply updates.
+- **Unpaired remote** clients are possible only when encryption is disabled. For backward compatibility they receive admin capabilities, but methods explicitly restricted to localhost or to a paired admin still reject them. They do not get the `update.apply` capability, and `update.check` is closed to them too.
 
 Call [`clients.current`](./methods.md#clientscurrent) to inspect current connection's role and capabilities. Every method in [API Methods](./methods) states its access requirements. Some read methods return additional sensitive fields to privileged clients; those fields are identified in their result contracts.
 
@@ -339,8 +339,8 @@ Methods execute actions and return data from Core. This catalog documents **88 n
 | settings.auth.link              | Start online account link.                                                            | Local/admin |
 | settings.auth.link.status       | Return online account link flow status.                                               | Tiered |
 | settings.auth.link.cancel       | Cancel online account link flow.                                                      | Local/admin |
-| update.check                    | Check for newer Core version.                                                         | All clients |
-| update.apply                    | Apply latest update and restart gracefully.                                           | All clients |
+| update.check                    | Check for newer Core version.                                                         | Localhost or any paired client |
+| update.apply                    | Apply latest update and restart gracefully.                                           | `update.apply` |
 
 ## Notifications
 
@@ -362,3 +362,4 @@ Notifications let a server or client know an event has occurred. See the [API No
 | playtime.limit.reached | A playtime limit (session or daily) has been reached and enforced.                |
 | playtime.limit.warning | A playtime warning notification sent at configured intervals before limit reached. |
 | inbox.added            | A new inbox message was added to the server.                                      |
+| update.state           | Progress of an update being applied.                                              |
diff --git a/docs/api/methods.md b/docs/api/methods.md
diff --git a/docs/api/notifications.md b/docs/api/notifications.md
@@ -612,3 +612,57 @@ The `finished` notification is terminal for that operation, whatever its outcome
   }
 }
 ```
+
+## Updates
+
+### update.state
+
+Sent while an update is being applied, so a client can show progress instead of a spinner that outlasts a large download.
+
+The stages that happen after the restart — `confirming`, `succeeded` and `rolledBack` — are not sent here, because no client is connected while they run. Read them from `update.check`'s `lastResult` once the service is back.
+
+Download progress is reported at most a few times a second, and the final byte always produces an event.
+
+#### Parameters
+
+| Key             | Type   | Required | Description                                                                              |
+| :-------------- | :----- | :------- | :---------------------------------------------------------------------------------------- |
+| stage           | string | Yes      | `checking`, `downloading`, `verifying`, `probing`, `installing`, `restarting`, or `failed`. |
+| version         | string | No       | The version being installed.                                                             |
+| trigger         | string | No       | Who asked for it: `manual` or `auto`.                                                    |
+| error           | string | No       | What went wrong. Only present on `failed`.                                               |
+| bytesDownloaded | number | No       | Bytes downloaded so far. Only present during `downloading`.                              |
+| bytesTotal      | number | No       | Total bytes to download, when the server reported a length.                              |
+
+#### Examples
+
+##### Downloading
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "update.state",
+  "params": {
+    "stage": "downloading",
+    "version": "2.10.0",
+    "trigger": "manual",
+    "bytesDownloaded": 4194304,
+    "bytesTotal": 12582912
+  }
+}
+```
+
+##### Failed
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "update.state",
+  "params": {
+    "stage": "failed",
+    "version": "2.10.0",
+    "trigger": "auto",
+    "error": "verifying the download: checksum mismatch"
+  }
+}
+```
diff --git a/pkg/api/methods/clients_test.go b/pkg/api/methods/clients_test.go
@@ -120,6 +120,13 @@ func TestHandleClientsCurrent(t *testing.T) {
 	adminCapabilities := []string{
 		string(permissions.CapProfilesManage),
 		string(permissions.CapSettingsWrite),
+		string(permissions.CapUpdateApply),
+	}
+	// An unpaired remote client gets the admin capabilities apart from
+	// update.apply.
+	unpairedCapabilities := []string{
+		string(permissions.CapProfilesManage),
+		string(permissions.CapSettingsWrite),
 	}
 	tests := []struct {
 		name             string
@@ -144,8 +151,8 @@ func TestHandleClientsCurrent(t *testing.T) {
 			wantPaired:       true,
 		},
 		{
-			name:             "remote unpaired keeps legacy grant",
-			wantCapabilities: adminCapabilities,
+			name:             "remote unpaired has no update.apply",
+			wantCapabilities: unpairedCapabilities,
 		},
 		{
 			name:             "local unpaired gets local grant",

diff --git a/pkg/api/methods/permissions.go b/pkg/api/methods/permissions.go
@@ -48,6 +48,17 @@ func requireCapability(env *requests.RequestEnv, capability permissions.Capabili
 	return nil
 }
 
+// requireAuthenticated returns a client error unless the request came from
+// the device itself or from a paired client. Any paired client passes,
+// member included. Use it for methods anyone in the household may call but
+// a stranger on the network may not.
+func requireAuthenticated(env *requests.RequestEnv) error {
+	if !requestGrant(env).Authenticated() {
+		return models.ClientErrf("%w", ErrForbidden)
+	}
+	return nil
+}
+
 // requireProfileManagement permits trusted local UI requests and requires
 // the profile-management capability from remote clients. Local profile PIN
 // prompts are a UI nuisance barrier, not API authorization.

diff --git a/pkg/api/methods/settings.go b/pkg/api/methods/settings.go
@@ -60,6 +60,8 @@ func HandleSettings(env requests.RequestEnv) (any, error) { //nolint:gocritic //
 
 	resp := models.SettingsResponse{
 		UpdateChannel:             env.Config.UpdateChannel(),
+		UpdateCheck:               env.Config.UpdateCheck(),
+		UpdateInstall:             env.Config.UpdateInstall(),
 		RunZapScript:              env.State.RunZapScriptEnabled(),
 		DebugLogging:              env.Config.DebugLogging(),
 		AudioScanFeedback:         env.Config.AudioFeedback(),
@@ -161,6 +163,21 @@ func HandleSettingsUpdate(env requests.RequestEnv) (any, error) {
 		}
 	}
 
+	// Installing updates without checking for them is not a state the device
+	// can be in, so the combination is refused rather than stored and quietly
+	// ignored. A client asking for both at once is fine.
+	if params.UpdateInstall != nil && *params.UpdateInstall {
+		checking := env.Config.UpdateCheck()
+		if params.UpdateCheck != nil {
+			checking = *params.UpdateCheck
+		}
+		if !checking {
+			return nil, models.ClientErrf(
+				"installing updates automatically needs automatic update checking turned on",
+			)
+		}
+	}
-	// Installing updates without checking for them is not a state the device
-	// can be in, so the combination is refused rather than stored and quietly
-	// ignored. A client asking for both at once is fine.
-	if params.UpdateInstall != nil && *params.UpdateInstall {
-		checking := env.Config.UpdateCheck()
-		if params.UpdateCheck != nil {
-			checking = *params.UpdateCheck
-		}
-		if !checking {
-			return nil, models.ClientErrf(
-				"installing updates automatically needs automatic update checking turned on",
-			)
-		}
-	}
+	// Reload configuration so validation reflects the current on-disk state.
+	if err := env.Config.Load(); err != nil {
+		log.Warn().Err(err).Msg("failed to reload config before settings update, using in-memory values")
+	}
+
+	// Installing updates without checking for them is not a state the device
+	// can be in, so the combination is refused rather than stored and quietly
+	// ignored. A client asking for both at once is fine.
+	if params.UpdateInstall != nil && *params.UpdateInstall {
+		checking := env.Config.UpdateCheck()
+		if params.UpdateCheck != nil {
+			checking = *params.UpdateCheck
+		}
+		if !checking {
+			return nil, models.ClientErrf(
+				"installing updates automatically needs automatic update checking turned on",
+			)
+		}
+	}
-	// Installing updates without checking for them is not a state the device
-	// can be in, so the combination is refused rather than stored and quietly
-	// ignored. A client asking for both at once is fine.
-	if params.UpdateInstall != nil && *params.UpdateInstall {
-		checking := env.Config.UpdateCheck()
-		if params.UpdateCheck != nil {
-			checking = *params.UpdateCheck
-		}
-		if !checking {
-			return nil, models.ClientErrf(
-				"installing updates automatically needs automatic update checking turned on",
-			)
-		}
-	}
+	// Reload configuration so validation reflects the current on-disk state.
+	if err := env.Config.Load(); err != nil {
+		log.Warn().Err(err).Msg("failed to reload config before settings update, using in-memory values")
+	}
+
+	// Installing updates without checking for them is not a state the device
+	// can be in, so the combination is refused rather than stored and quietly
+	// ignored. A client asking for both at once is fine.
+	if params.UpdateInstall != nil && *params.UpdateInstall {
+		checking := env.Config.UpdateCheck()
+		if params.UpdateCheck != nil {
+			checking = *params.UpdateCheck
+		}
+		if !checking {
+			return nil, models.ClientErrf(
+				"installing updates automatically needs automatic update checking turned on",
+			)
+		}
+	}
+
 	// Reload config from disk before applying mutations so that external
 	// edits (e.g. user hand-editing config.toml) are not lost on save.
 	// TODO: Load+Set+Save is not atomic — concurrent handler calls can
@@ -179,6 +196,16 @@ func HandleSettingsUpdate(env requests.RequestEnv) (any, error) {
 		env.Config.SetUpdateChannel(*params.UpdateChannel)
 	}
 
+	if params.UpdateCheck != nil {
+		log.Debug().Bool("updateCheck", *params.UpdateCheck).Msg("updating setting")
+		env.Config.SetUpdateCheck(*params.UpdateCheck)
+	}
+
+	if params.UpdateInstall != nil {
+		log.Debug().Bool("updateInstall", *params.UpdateInstall).Msg("updating setting")
+		env.Config.SetUpdateInstall(*params.UpdateInstall)
+	}
+
 	if params.DebugLogging != nil {
 		log.Debug().Bool("debugLogging", *params.DebugLogging).Msg("updating setting")
 		env.Config.SetDebugLogging(*params.DebugLogging)