diff --git a/cmd/silo/main.go b/cmd/silo/main.go index 92f4dbbbd8..1fc542431a 100644 --- a/cmd/silo/main.go +++ b/cmd/silo/main.go @@ -1156,9 +1156,7 @@ func main() { }() } - // The plugin event dispatcher observes what this process publishes, so - // each event reaches plugins once however many nodes receive it. - eventBus := cache.NewObservedEventBus(cache.NewEventBus(cfg.Redis)) + eventBus := cache.NewEventBus(cfg.Redis) if err := eventBus.Subscribe(appCtx, cache.ChannelCatalog, func(event cache.Event) { switch event.Type { case cache.EventScanComplete: @@ -1888,6 +1886,11 @@ func main() { installer := plugins.NewInstaller(installationStore, plugins.InstallerOptions{ BaseDir: pluginCacheDir, }) + // Approvals rebuild every API server's event subscriber index through + // the lifecycle path; pluginService is assigned below. + pluginPermissions := plugins.NewPermissionService(installationStore, deps.SecretCipher, + auth.PluginHostAPIKeys{Keys: auth.NewAPIKeyRepository(deps.DB)}, + func(ctx context.Context) { pluginService.OnLifecycleChange(ctx) }) libSource := pluginLibrarySource{groups: accessGroupStore} if deps.FolderRepo != nil { @@ -1961,9 +1964,10 @@ func main() { return runtimeConfigStore.PutGlobalConfig(ctx, installationID, key, value) }, ), - HostInfo: hostInfo, - InstanceState: instanceStateStore, - NetworkAccess: networkAccess, + HostInfo: hostInfo, + InstanceState: instanceStateStore, + NetworkAccess: networkAccess, + HostAPICredentials: pluginPermissions, Logger: hclog.New(&hclog.LoggerOptions{ Name: "plugin-host", Level: hclog.Info, @@ -1978,6 +1982,7 @@ func main() { installer, plugins.NewHostAdapter(pluginHost), ) + pluginService.SetPermissions(pluginPermissions) // Crashes of resident plugins (network access providers) reach the // supervisor through the host's exit watcher so they restart with // backoff instead of waiting for the next lazy RPC. @@ -2070,6 +2075,15 @@ func main() { } } } + // Installations from before permission grants keep the event access + // they had. This runs before the catalog auto-update below, so an + // update never meets an installation without a grant to hold back + // what it newly asks for. + if granted, err := installationStore.EnsurePermissionGrants(appCtx); err != nil { + log.Fatalf("record plugin permission grants: %v", err) + } else if granted > 0 { + slog.Info("recorded plugin permission grants for existing installations", "component", "plugins", "installations", granted) + } if err := pluginService.PreloadEnabled(appCtx); err != nil { log.Fatalf("preload enabled plugins: %v", err) } @@ -2137,7 +2151,6 @@ func main() { if err := dispatcher.Start(appCtx); err != nil { log.Fatalf("plugin event dispatcher: %v", err) } - eventBus.ObservePublishes(dispatcher.ObservePublish) defer dispatcher.Stop() // Rerun the lifecycle hooks registered so far. PreloadEnabled ran them // before PublishLifecycleChanges was registered, so this call is the diff --git a/contracts/api/v2/openapi.json b/contracts/api/v2/openapi.json index 91deced52b..d2ad5cb483 100644 --- a/contracts/api/v2/openapi.json +++ b/contracts/api/v2/openapi.json @@ -16812,6 +16812,38 @@ ], "type": "object" }, + "AdminPluginEventAccess": { + "additionalProperties": false, + "properties": { + "approved": { + "description": "Access classes an administrator approved. The plugin receives events of these classes and of no others that need approval.", + "items": { + "enum": [ + "admin", + "user_data" + ], + "type": "string" + }, + "type": "array" + }, + "required": { + "description": "Access classes of the events the plugin subscribes to that need approval: admin (server operations such as playback activity, scans and jobs) and user_data (one profile's personal data, such as its notifications). Public and plugin events need none. The vocabulary is open: ignore a class you don't know.", + "items": { + "enum": [ + "admin", + "user_data" + ], + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "required", + "approved" + ], + "type": "object" + }, "AdminPluginForm": { "additionalProperties": false, "properties": { @@ -16988,6 +17020,80 @@ ], "type": "object" }, + "AdminPluginHostAPIKey": { + "additionalProperties": false, + "properties": { + "id": { + "description": "The key on the API keys page, where it can be revoked; omitted while none is issued", + "examples": [ + "1" + ], + "minLength": 1, + "type": "string" + }, + "issued": { + "description": "True while a host API key is issued to the plugin", + "type": "boolean" + }, + "owner_user_id": { + "description": "The account the key acts as: the administrator whose approval issued it. It stops working if that account loses the admin role or is disabled, and is deleted with the account. Omitted while none is issued", + "examples": [ + "1" + ], + "minLength": 1, + "type": "string" + }, + "usable": { + "description": "True while the issued key can act for the plugin. False when none is issued, when the account it acts as is no longer an enabled administrator, or when this server can't read it (it was stored under another SECRET_KEY). An unusable key grants nothing: the plugin is pending and an approval issues a replacement", + "type": "boolean" + } + }, + "required": [ + "issued", + "usable" + ], + "type": "object" + }, + "AdminPluginHostAPIScopes": { + "additionalProperties": false, + "properties": { + "approved": { + "description": "Scopes the plugin's usable host API key carries; empty while none is usable, including after the key was revoked or its account lost the admin role", + "items": { + "type": "string" + }, + "type": "array" + }, + "requested": { + "description": "The manifest's host_api_scopes", + "items": { + "type": "string" + }, + "type": "array" + }, + "required": { + "description": "The requested scopes this server can issue", + "items": { + "type": "string" + }, + "type": "array" + }, + "unsupported": { + "description": "The requested scopes this server doesn't know; they are never granted", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "requested", + "required", + "unsupported", + "approved" + ], + "type": "object" + }, "AdminPluginInstallCreate": { "additionalProperties": false, "properties": { @@ -17082,6 +17188,10 @@ "type": "object", "x-silo-extension-bag": "plugin-json-value" }, + "permissions_pending": { + "description": "True while the installation asks for event access or host API scopes an administrator hasn't approved; see getAdminPluginInstallationPermissions", + "type": "boolean" + }, "plugin_id": { "type": "string" }, @@ -17170,6 +17280,7 @@ "auth_bindings", "task_bindings", "runtime", + "permissions_pending", "created_at", "updated_at" ], @@ -17193,6 +17304,55 @@ }, "type": "object" }, + "AdminPluginPermissions": { + "additionalProperties": false, + "properties": { + "approved_at": { + "description": "The last explicit approval; omitted when none was given, such as when event access was approved by installing the plugin", + "format": "date-time", + "pattern": "^(?:[1-9][0-9]{3}|0[1-9][0-9]{2}|00[1-9][0-9]|000[2-9])-", + "patternDescription": "a non-zero RFC 3339 instant", + "type": "string" + }, + "approved_by_user_id": { + "description": "The administrator who gave the last explicit approval; omitted when none was given or the account was deleted", + "examples": [ + "1" + ], + "minLength": 1, + "type": "string" + }, + "event_access": { + "$ref": "#/components/schemas/AdminPluginEventAccess" + }, + "host_api_key": { + "$ref": "#/components/schemas/AdminPluginHostAPIKey" + }, + "host_api_scopes": { + "$ref": "#/components/schemas/AdminPluginHostAPIScopes" + }, + "installation_id": { + "description": "Opaque identifier", + "examples": [ + "1" + ], + "minLength": 1, + "type": "string" + }, + "pending": { + "description": "True while the plugin asks for event access or host API scopes that aren't approved. It keeps what was approved before until an administrator approves the rest", + "type": "boolean" + } + }, + "required": [ + "installation_id", + "event_access", + "host_api_scopes", + "pending", + "host_api_key" + ], + "type": "object" + }, "AdminPluginPresentation": { "additionalProperties": false, "properties": { @@ -108605,7 +108765,394 @@ ], "responses": { "204": { - "description": "No Content" + "description": "No Content" + }, + "400": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Bad Request" + }, + "401": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Forbidden" + }, + "404": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Not Found" + }, + "406": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Not Acceptable" + }, + "409": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Conflict" + }, + "422": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unprocessable Entity" + }, + "429": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Too Many Requests" + }, + "500": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Internal Server Error" + }, + "503": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Service Unavailable" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Stop the plugin, delete the installation row (configuration, bindings and archives cascade) and remove its files. Row delete and file removal are not one transaction and a repeat finds no row: a later 404 is not this caller's receipt; never automatically retry.", + "tags": [ + "admin-plugins" + ], + "x-silo-class": "acting_admin", + "x-silo-demo-restricted": true, + "x-silo-retry-safety": "non_retryable", + "x-silo-service-backed": true + }, + "put": { + "operationId": "updateAdminPluginInstallation", + "parameters": [ + { + "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", + "in": "header", + "name": "X-Profile-Id", + "schema": { + "examples": [ + "1" + ], + "type": "string" + } + }, + { + "description": "Verification proof for a PIN-locked profile, issued by POST /api/v2/profiles/{id}/verify-pin; required only when the declared profile is locked", + "in": "header", + "name": "X-Profile-Token", + "schema": { + "examples": [ + "pvt_5f3a9c1e7b2d4e8fa0c6" + ], + "type": "string" + } + }, + { + "description": "Opaque identifier", + "in": "path", + "name": "id", + "required": true, + "schema": { + "description": "Opaque identifier", + "examples": [ + "1" + ], + "minLength": 1, + "pattern": "^[1-9][0-9]*$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminPluginInstallationUpdate" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminPluginInstallation" + } + } + }, + "description": "OK" + }, + "400": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Bad Request" + }, + "401": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Forbidden" + }, + "404": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Not Found" + }, + "406": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Not Acceptable" + }, + "408": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Request Timeout" + }, + "409": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Conflict" + }, + "413": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Request Entity Too Large" + }, + "415": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unsupported Media Type" + }, + "422": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unprocessable Entity" + }, + "429": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Too Many Requests" + }, + "500": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Internal Server Error" + }, + "503": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Service Unavailable" + } + }, + "security": [ + { + "bearerAuth": [] + } + ], + "summary": "Assign enabled and/or update_policy on one installation. Disabling stops the running plugin first. Repeating the same assignment converges on one stored row.", + "tags": [ + "admin-plugins" + ], + "x-silo-class": "acting_admin", + "x-silo-demo-restricted": true, + "x-silo-retry-safety": "natural_idempotent", + "x-silo-service-backed": true + } + }, + "/api/v2/admin/plugins/installations/{id}/auth-binding": { + "put": { + "operationId": "updateAdminPluginAuthBinding", + "parameters": [ + { + "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", + "in": "header", + "name": "X-Profile-Id", + "schema": { + "examples": [ + "1" + ], + "type": "string" + } + }, + { + "description": "Verification proof for a PIN-locked profile, issued by POST /api/v2/profiles/{id}/verify-pin; required only when the declared profile is locked", + "in": "header", + "name": "X-Profile-Token", + "schema": { + "examples": [ + "pvt_5f3a9c1e7b2d4e8fa0c6" + ], + "type": "string" + } + }, + { + "description": "Opaque identifier", + "in": "path", + "name": "id", + "required": true, + "schema": { + "description": "Opaque identifier", + "examples": [ + "1" + ], + "minLength": 1, + "pattern": "^[1-9][0-9]*$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminPluginAuthBindingWrite" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "No Content", + "headers": { + "X-Silo-Restart-Required": { + "schema": { + "description": "Always false: sign-in providers rebuild on every node when a binding changes", + "type": "string" + } + } + } }, "400": { "content": { @@ -108657,6 +109204,16 @@ }, "description": "Not Acceptable" }, + "408": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Request Timeout" + }, "409": { "content": { "application/problem+json": { @@ -108667,6 +109224,26 @@ }, "description": "Conflict" }, + "413": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Request Entity Too Large" + }, + "415": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Unsupported Media Type" + }, "422": { "content": { "application/problem+json": { @@ -108713,17 +109290,20 @@ "bearerAuth": [] } ], - "summary": "Stop the plugin, delete the installation row (configuration, bindings and archives cascade) and remove its files. Row delete and file removal are not one transaction and a repeat finds no row: a later 404 is not this caller's receipt; never automatically retry.", + "summary": "Replace the auth provider binding for one capability. Sign-in providers rebuild on every node without a restart. Enabling a binding while another one is enabled is 409 provider_already_enabled. The whole row is assigned, so repeating the request converges on one stored binding.", "tags": [ "admin-plugins" ], "x-silo-class": "acting_admin", "x-silo-demo-restricted": true, - "x-silo-retry-safety": "non_retryable", + "x-silo-retry-safety": "natural_idempotent", "x-silo-service-backed": true - }, - "put": { - "operationId": "updateAdminPluginInstallation", + } + }, + "/api/v2/admin/plugins/installations/{id}/auth-binding/test": { + "post": { + "description": "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically.", + "operationId": "testAdminPluginAuthBinding", "parameters": [ { "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", @@ -108767,7 +109347,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginInstallationUpdate" + "$ref": "#/components/schemas/AdminPluginAuthBindingTestInputBody" } } }, @@ -108778,7 +109358,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginInstallation" + "$ref": "#/components/schemas/AuthConnectionTestResult" } } }, @@ -108920,19 +109500,19 @@ "bearerAuth": [] } ], - "summary": "Assign enabled and/or update_policy on one installation. Disabling stops the running plugin first. Repeating the same assignment converges on one stored row.", + "summary": "Test an auth plugin's connection with staged, unsaved settings.", "tags": [ "admin-plugins" ], "x-silo-class": "acting_admin", "x-silo-demo-restricted": true, - "x-silo-retry-safety": "natural_idempotent", + "x-silo-retry-safety": "non_retryable", "x-silo-service-backed": true } }, - "/api/v2/admin/plugins/installations/{id}/auth-binding": { + "/api/v2/admin/plugins/installations/{id}/config": { "put": { - "operationId": "updateAdminPluginAuthBinding", + "operationId": "updateAdminPluginInstallationConfig", "parameters": [ { "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", @@ -108976,7 +109556,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginAuthBindingWrite" + "$ref": "#/components/schemas/AdminPluginConfigWrite" } } }, @@ -108984,15 +109564,7 @@ }, "responses": { "204": { - "description": "No Content", - "headers": { - "X-Silo-Restart-Required": { - "schema": { - "description": "Always false: sign-in providers rebuild on every node when a binding changes", - "type": "string" - } - } - } + "description": "No Content" }, "400": { "content": { @@ -109130,7 +109702,7 @@ "bearerAuth": [] } ], - "summary": "Replace the auth provider binding for one capability. Sign-in providers rebuild on every node without a restart. Enabling a binding while another one is enabled is 409 provider_already_enabled. The whole row is assigned, so repeating the request converges on one stored binding.", + "summary": "Replace one global configuration entry after validating it against the plugin manifest, then stop the running plugin so it rebinds. Omitted fields keep their stored values. A declared non-secret top-level field sent as null or a blank string is removed from the stored entry, so the plugin default applies; undeclared fields are kept. Blank secret fields keep stored secrets; only clear_secrets removes them. Repeating the same request converges on one stored entry.", "tags": [ "admin-plugins" ], @@ -109140,10 +109712,9 @@ "x-silo-service-backed": true } }, - "/api/v2/admin/plugins/installations/{id}/auth-binding/test": { + "/api/v2/admin/plugins/installations/{id}/config/test": { "post": { - "description": "The running plugin tests the staged configuration (merged over the stored entries it does not replace) and persists nothing. A failed check is a 200 result with ok false. A plugin without a connection test, or a disabled installation, is 409. The check reaches the provider and is bounded by a server timeout; never retry an uncertain result automatically.", - "operationId": "testAdminPluginAuthBinding", + "operationId": "testAdminPluginInstallationConfig", "parameters": [ { "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", @@ -109187,7 +109758,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginAuthBindingTestInputBody" + "$ref": "#/components/schemas/AdminPluginConfigWrite" } } }, @@ -109198,7 +109769,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthConnectionTestResult" + "$ref": "#/components/schemas/AdminPluginConnectionCheck" } } }, @@ -109340,7 +109911,7 @@ "bearerAuth": [] } ], - "summary": "Test an auth plugin's connection with staged, unsaved settings.", + "summary": "Probe one prospective configuration by starting a temporary plugin instance and running its connection check; nothing is stored. The check calls the plugin's provider and is bounded by a server timeout; never automatically retry an uncertain result. A failed check is a 200 result with success false.", "tags": [ "admin-plugins" ], @@ -109350,10 +109921,18 @@ "x-silo-service-backed": true } }, - "/api/v2/admin/plugins/installations/{id}/config": { - "put": { - "operationId": "updateAdminPluginInstallationConfig", + "/api/v2/admin/plugins/installations/{id}/permissions": { + "get": { + "operationId": "getAdminPluginInstallationPermissions", "parameters": [ + { + "description": "Optional first precondition, evaluated before If-None-Match: a tag that does not match the current representation is 412 precondition_failed.", + "in": "header", + "name": "If-Match", + "schema": { + "type": "string" + } + }, { "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", "in": "header", @@ -109390,21 +109969,44 @@ "pattern": "^[1-9][0-9]*$", "type": "string" } + }, + { + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AdminPluginConfigWrite" + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminPluginPermissions" + } + } + }, + "description": "OK", + "headers": { + "ETag": { + "description": "The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read.", + "schema": { + "type": "string" + } } } }, - "required": true - }, - "responses": { - "204": { - "description": "No Content" + "304": { + "description": "The representation named by If-None-Match is current; no body.", + "headers": { + "ETag": { + "description": "The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read.", + "schema": { + "type": "string" + } + } + } }, "400": { "content": { @@ -109456,16 +110058,6 @@ }, "description": "Not Acceptable" }, - "408": { - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/Problem" - } - } - }, - "description": "Request Timeout" - }, "409": { "content": { "application/problem+json": { @@ -109476,7 +110068,7 @@ }, "description": "Conflict" }, - "413": { + "412": { "content": { "application/problem+json": { "schema": { @@ -109484,17 +110076,15 @@ } } }, - "description": "Request Entity Too Large" - }, - "415": { - "content": { - "application/problem+json": { + "description": "Precondition Failed", + "headers": { + "ETag": { + "description": "The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read.", "schema": { - "$ref": "#/components/schemas/Problem" + "type": "string" } } - }, - "description": "Unsupported Media Type" + } }, "422": { "content": { @@ -109542,20 +110132,36 @@ "bearerAuth": [] } ], - "summary": "Replace one global configuration entry after validating it against the plugin manifest, then stop the running plugin so it rebinds. Omitted fields keep their stored values. A declared non-secret top-level field sent as null or a blank string is removed from the stored entry, so the plugin default applies; undeclared fields are kept. Blank secret fields keep stored secrets; only clear_secrets removes them. Repeating the same request converges on one stored entry.", + "summary": "Read what one installation asks to receive and call, and what an administrator approved: the event access classes its subscriptions need, the host API scopes its manifest requests, and the host API key issued for them. The key itself is never returned. The ETag validates the whole representation; approving requires it. The reserved builtin row is 409.", "tags": [ "admin-plugins" ], "x-silo-class": "acting_admin", - "x-silo-demo-restricted": true, - "x-silo-retry-safety": "natural_idempotent", + "x-silo-conditional": true, "x-silo-service-backed": true } }, - "/api/v2/admin/plugins/installations/{id}/config/test": { - "post": { - "operationId": "testAdminPluginInstallationConfig", + "/api/v2/admin/plugins/installations/{id}/permissions/approval": { + "put": { + "operationId": "approveAdminPluginInstallationPermissions", "parameters": [ + { + "description": "The resource's current ETag, or \"*\" to overwrite deliberately. A missing field is 428 precondition_required; a stale tag is 412 precondition_failed with the current ETag.", + "in": "header", + "name": "If-Match", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional second precondition, evaluated after If-Match succeeds: \"*\" or any tag matching the current representation is 412 precondition_failed with the current ETag.", + "in": "header", + "name": "If-None-Match", + "schema": { + "type": "string" + } + }, { "description": "Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted.", "in": "header", @@ -109594,26 +110200,24 @@ } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AdminPluginConfigWrite" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginConnectionCheck" + "$ref": "#/components/schemas/AdminPluginPermissions" } } }, - "description": "OK" + "description": "OK", + "headers": { + "ETag": { + "description": "The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read.", + "schema": { + "type": "string" + } + } + } }, "400": { "content": { @@ -109665,7 +110269,7 @@ }, "description": "Not Acceptable" }, - "408": { + "409": { "content": { "application/problem+json": { "schema": { @@ -109673,9 +110277,9 @@ } } }, - "description": "Request Timeout" + "description": "Conflict" }, - "409": { + "412": { "content": { "application/problem+json": { "schema": { @@ -109683,19 +110287,17 @@ } } }, - "description": "Conflict" - }, - "413": { - "content": { - "application/problem+json": { + "description": "Precondition Failed", + "headers": { + "ETag": { + "description": "The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read.", "schema": { - "$ref": "#/components/schemas/Problem" + "type": "string" } } - }, - "description": "Request Entity Too Large" + } }, - "415": { + "422": { "content": { "application/problem+json": { "schema": { @@ -109703,9 +110305,9 @@ } } }, - "description": "Unsupported Media Type" + "description": "Unprocessable Entity" }, - "422": { + "428": { "content": { "application/problem+json": { "schema": { @@ -109713,7 +110315,7 @@ } } }, - "description": "Unprocessable Entity" + "description": "Precondition Required" }, "429": { "content": { @@ -109751,13 +110353,14 @@ "bearerAuth": [] } ], - "summary": "Probe one prospective configuration by starting a temporary plugin instance and running its connection check; nothing is stored. The check calls the plugin's provider and is bounded by a server timeout; never automatically retry an uncertain result. A failed check is a 200 result with success false.", + "summary": "Approve everything the installation asks for now, as the acting administrator. If-Match must carry the ETag of the permissions read the administrator approved; the server compares it with the permissions inside the approval's transaction, so a plugin update that asks for more, or another approval, landing in between is 412 with the current ETag and changes nothing. When the installation requests host API scopes this server knows and has no usable key with exactly those, a key acting as the acting administrator is issued and the previous key revoked in the same transaction; when it requests none, its key is revoked. The event subscriber index rebuilds on every server; the plugin is not restarted.", "tags": [ "admin-plugins" ], "x-silo-class": "acting_admin", "x-silo-demo-restricted": true, - "x-silo-retry-safety": "non_retryable", + "x-silo-guarded": true, + "x-silo-retry-safety": "natural_idempotent", "x-silo-service-backed": true } }, diff --git a/docs/admin-api.md b/docs/admin-api.md index 5e7a4695a4..10bfc0b3c8 100644 --- a/docs/admin-api.md +++ b/docs/admin-api.md @@ -3439,7 +3439,8 @@ can be turned off or uninstalled; a server that still has a good copy of the fil unaffected. `DELETE /api/v2/admin/plugins/installations/{id}` stops the plugin, deletes the row -(configuration, bindings and archives cascade) and removes its files; on a failed row delete +(configuration, bindings, archives and the permission grant cascade) together with the +plugin's host API key in one transaction, and removes its files; on a failed row delete an enabled plugin is restarted. Row delete and file removal are not one transaction and a repeat finds no row, so a later 404 is not this caller's receipt; non-retryable. A row admitted before the host refused IDs and versions that map to an empty, `.` or `..` directory @@ -3526,6 +3527,54 @@ installation, 409 for the reserved built-in host row, 422 for a blank key or cap authority before each submission and ignores a completion that arrives under a replaced authority. +### Plugin permissions in v2 + +Every installation carries `permissions_pending`: true while it asks for event access or +host API scopes an administrator hasn't approved. The plugins page badges it. + +`GET /api/v2/admin/plugins/installations/{id}/permissions` answers what the installation +asks for and what was approved: + +- `event_access.required` is the access classes of the catalog events its + `event_consumer.v1` subscriptions name that need approval, `admin` and `user_data` + (public and plugin events need none). `event_access.approved` is what the grant approves; + the dispatcher delivers no event of an unapproved class. +- `host_api_scopes.requested` is the manifest's `host_api_scopes`; `required` is the subset + in this server's API key scope catalog; `unsupported` is the rest, which is never granted; + `approved` is the scopes of the issued key while it is usable, and empty otherwise: + none issued, the key revoked on the API keys page, its account no longer an enabled + administrator, or the key unreadable on this server. +- `pending`, `approved_at` and `approved_by_user_id` (the last explicit approval; omitted + when event access was approved by installing the plugin, or the account was deleted). +- `host_api_key`: `issued`, `usable` (false when the key's account is no longer an enabled + administrator or this server can't read the key; such a key grants nothing), its `id` on + the API keys page and `owner_user_id`, the account it acts as. The key itself is never + returned. + +The read is conditional: its `ETag` validates the whole representation, and +`If-None-Match` with it answers 304. + +`PUT /api/v2/admin/plugins/installations/{id}/permissions/approval` approves everything the +installation asks for now, as the acting administrator, and answers 200 with the same body +and its new `ETag`. It is guarded: `If-Match` must carry the `ETag` of the read the +administrator approved (428 without one). The server compares it with the permissions +inside the approval's transaction, so a plugin update that asks for more, another approval, +or a revoked key landing in between is 412 with the current `ETag` and changes nothing; the +web panel then reloads and shows the new requirements. When it requests known scopes and has +no usable key with exactly those, the server mints a key on the administrator's own account, +points the grant at it and deletes the previous key in that one transaction; when it +requests none, its key is deleted the same way. A repeat with a fresh `ETag` keeps a usable +key whose scopes match, so the operation is naturally idempotent. Every API server rebuilds +its event subscriber index; the plugin is not restarted. + +Both require an acting administrator, and the approval restricts demo access. They answer 404 +for an unknown installation, 409 for the reserved built-in host row, and 503 when the plugin +service is not wired. Installing a plugin approves the event access it asks for then; an +upgrade, including an automatic catalog update, never widens a grant. The plugin keeps what +was approved before until an administrator approves the rest. +[plugin-permissions.md](architecture/plugin-permissions.md) has the invariants. The frozen v1 +surface has no equivalent. + ## Bridge note The frozen alpha surface serves the same administration features under `/api/v1/admin` diff --git a/docs/architecture/backups.md b/docs/architecture/backups.md index 553477d86b..359bff6863 100644 --- a/docs/architecture/backups.md +++ b/docs/architecture/backups.md @@ -1929,7 +1929,10 @@ that holds a bearer secret or a public capability, each one way: with their tokens (one removed since would sync again), and plugins' configuration and stored state, which hold the keys and tokens a plugin presents to its service and which the server cannot tell apart from a - plugin's other settings. A restore + plugin's other settings. Plugins' permission grants are carried with + them: a grant names its host API key only where the carry kept that key, + and otherwise keeps its approvals without one, so the plugin waits for + approval ([plugin-permissions.md](plugin-permissions.md#backups)). A restore never brings back the backup's rows: one revoked after the backup would work again, and one created since would stop working. They stay in the dump (`marker_edit_audit` refers to API keys), and the restore replaces @@ -1939,14 +1942,14 @@ that holds a bearer secret or a public capability, each one way: are carried like the credentials above (a node or catalog removed since the backup stays removed), and each plugin installation the live server has, by id and plugin, takes the live release (version, install - path, repository, stored archive, and capabilities; - `CarryPluginReleases`), so a release replaced since the backup is never + path, repository, stored archive, capabilities, and requested host API + scopes; `CarryPluginReleases`), so a release replaced since the backup is never launched again; a catalog it names that the restored data lacks is dropped from the reference rather than failing the restore. An installation whose id is another plugin here, and every installation of another deployment's backup or a separate - restore, comes back off and is listed; one only the backup has is off - by its stricter switch. The trusted proxies are a stricter-of setting. + restore, comes back off and is listed, without a permission grant; one + only the backup has is off by its stricter switch. The trusted proxies are a stricter-of setting. - Custom access policies only tighten decisions, so a newer one lost to the backup would widen access: their documents and versions (`liveTables`) are taken from the live server as one unit, with the diff --git a/docs/architecture/plugin-event-delivery.md b/docs/architecture/plugin-event-delivery.md index 99d69f1455..ca77aeca22 100644 --- a/docs/architecture/plugin-event-delivery.md +++ b/docs/architecture/plugin-event-delivery.md @@ -13,22 +13,68 @@ Deliveries are not ordered. Only the API server that produced an event stores it, so the number of API servers does not change how often a plugin hears of it. -- Host code publishes catalog, admin and playback events on the - [Redis event bus](redis-event-bus.md). Redis hands every message to every - node, so the dispatcher does not subscribe to those channels. `main.go` - wraps the bus in `cache.ObservedEventBus` and registers - `EventDispatcher.ObservePublish`, which sees each event the process itself - publishes. Without Redis the bus delivers nothing, and the observer still - runs. -- Envelopes published on the `events.Hub`, which is where - `RuntimeHost.PublishEvent` puts plugin-published events. Each hub also - relays other nodes' envelopes to its local subscribers; the dispatcher - takes only envelopes whose `SourceID` is its own hub's. - -Both paths check the subscriber index before queueing, so events no plugin -subscribes to cost a map lookup and never take a place in the intake queue. -A bus event gets a new ULID as its `event_id`. An envelope keeps its -`EventID`. +The dispatcher reads envelopes published on the `events.Hub`. Each hub also +relays other nodes' envelopes to its local subscribers; the dispatcher takes +only envelopes whose `SourceID` is its own hub's, and skips `V2Only` ones. +`RuntimeHost.PublishEvent` puts plugin-published events on the hub too, on +`ChannelPlugins`. + +The hub keeps `ChannelPlugins` envelopes on the server that published them: +no websocket client receives that channel, and every other server's +dispatcher would drop them. Before it builds a plugin event's envelope, +`RuntimeHost.PublishEvent` asks the hub whether the event could have +subscribers (`Hub.PluginEventWanted`, answered from the dispatcher's index), +so a plugin event nobody subscribes to is not encoded or published. + +It does not read the [Redis event bus](redis-event-bus.md). Bus event types +are internal cache and coordination signals, not a plugin contract, and +Redis hands every message to every node. + +## Which events plugins receive + +Plugins receive only the events in the SDK's catalog +(`silo-plugin-sdk` `pkg/pluginsdk/events`, documented in its `docs/events.md`) +and plugin events (`plugin..`). The subscriber index leaves +out any other name a manifest lists, so an internal event such as +`user_state.changed` never reaches a plugin. + +Every identifier in a catalog payload is a JSON string. The host's +payloads are shared with the events socket, where numeric IDs such as +`library_id` stay JSON numbers, so the dispatcher converts them: a top-level +`id` or `*_id` field holding a number becomes its decimal string, and zero +becomes absent (a job the server queued itself has no `created_by_user_id`). +`notification.created` also gets the envelope's account as `user_id`, +because profile IDs repeat across accounts. + +Then `events.Project` rewrites the payload into the catalog's public shape: +the fields of the SDK payload type and nothing else. A field the host adds +for its own clients therefore stays off the plugin contract until the SDK +type adds it. An event whose payload doesn't fit its catalog type, such as a +number where the catalog has a string, is logged and not stored. + +`TestEventCatalogMatchesProducers` runs what each producer publishes through +that conversion and fails when a producer change drops or retypes a catalog +field, or when the SDK catalog gains an event without a producer case. + +The index check happens before queueing, so events no plugin subscribes to +cost a map lookup and never take a place in the intake queue. An envelope +keeps its `EventID`. + +## Gating by approved access + +Every catalog event has an access class (`events.AccessOf`): `public`, +`admin` or `user_data`. Plugin events are `public`. The subscriber index +includes a subscriber for an `admin` or `user_data` event only when its +installation's `plugin_permission_grants` row approves that class; public and +plugin events need no approval. An installation without a grant receives only +those. `buildIndex` reads every grant in one query with the enabled +installations, so gating costs nothing per event. + +An approval runs `Service.OnLifecycleChange`, which drops this server's index +and publishes `plugins_changed`, so every API server rebuilds its index on the +next event. It restarts no plugin. Installing, the boot pass and approvals are +the only writers of approved access; +[plugin-permissions.md](plugin-permissions.md) covers when each one runs. ## Outbox @@ -64,6 +110,15 @@ published while the server drains its requests after its context ended. - Never deliver plugin events from a bus subscription or from relayed hub envelopes. Every node receives those, and each would deliver the event again. +- Only catalog and plugin events reach plugins, in their projected shape. + Delivering another name, or a payload that skipped `events.Project`, makes + an internal detail part of the plugin contract. +- Catalog payload IDs are strings. Change a producer's ID to a string on the + events socket and the conversion leaves it alone; add a numeric ID under a + name other than `id` or `*_id` and projection refuses the event. +- An `admin` or `user_data` event reaches only installations whose grant + approves its class. The check lives in the index, so a stored delivery was + approved when its event was produced. - A claim must stay a `MATERIALIZED` CTE. As `id IN (SELECT ... LIMIT n FOR UPDATE SKIP LOCKED)` the planner may run the subquery more than once and claim more than `n` rows. @@ -80,11 +135,10 @@ published while the server drains its requests after its context ended. ## Limits - An event is lost before it is stored when its server dies first, when the - intake queue (1024 events) is full, or when the outbox write fails. A full - queue drops bus events with a log line. Hub envelopes wait in the hub's - 64-envelope buffer for the dispatcher, and `Hub.Dropped` counts the ones it - drops; once the server's context has ended, they are dropped with a log - line too. + intake queue (1024 events) is full, or when the outbox write fails. + Envelopes wait in the hub's 64-envelope buffer for the dispatcher, and + `Hub.Dropped` counts the ones it drops; once the server's context has + ended, they are dropped with a log line. - Each server delivers four events at a time across all plugins. A plugin that hangs holds a slot for 10 seconds per attempt, or a minute when it will not start, so its backlog delays other plugins' events. @@ -95,12 +149,14 @@ published while the server drains its requests after its context ended. up to a minute when the message is lost, miss the new subscriber. - One process sees each event, so a plugin that keeps per-process state cannot use events to keep every process's copy current. -- During a rolling upgrade, servers on older builds still deliver from their - bus and hub subscriptions, once per server, without retries and without an - `event_id`, until they are replaced. +- During a rolling upgrade, servers on older builds still deliver internal + event names, unprojected payloads and numeric IDs, and ignore grants, until + they are replaced. +- Gating applies when an event is stored. Deliveries already stored when an + approval narrows a grant are still delivered. ## Plugin contract -The SDK documents what plugin authors can rely on: `HandleEventRequest.event_id` -and the "Receiving events" section of `silo-plugin-sdk`'s -`docs/runtime-host.md`. +The SDK documents what plugin authors can rely on: the event catalog and +payloads in `silo-plugin-sdk`'s `docs/events.md`, `HandleEventRequest.event_id`, +and the "Receiving events" section of its `docs/runtime-host.md`. diff --git a/docs/architecture/plugin-permissions.md b/docs/architecture/plugin-permissions.md new file mode 100644 index 0000000000..e2aa0b1f3a --- /dev/null +++ b/docs/architecture/plugin-permissions.md @@ -0,0 +1,161 @@ +# Plugin permissions and the host API key + +An administrator approves what each plugin installation receives and may call: +the access classes of the events it subscribes to, and the host API scopes its +manifest asks for. Approval issues the plugin a scoped API key, which it reads +with `RuntimeHost.GetHostAPICredential`. The plugin-author contract is the +SDK's `docs/permissions.md`. + +Permissions are not a sandbox ([plugin-trust.md](plugin-trust.md)): a plugin +can still reach what the server's user can. They make what a plugin receives +visible, stop an upgrade from widening it unnoticed, and replace the full-access +API key an administrator would otherwise paste into a plugin's settings. + +## What an installation asks for + +`plugins.DeriveRequiredPermissions` (`internal/plugins/permissions.go`) reads +the stored capabilities and `plugin_installations.host_api_scopes`, which the +installer writes wherever it writes `plugin_capabilities`: + +- Event access: the `admin` and `user_data` classes (`events.AccessOf`) of the + catalog events its `event_consumer.v1` capabilities subscribe to. Public and + plugin events ask for nothing, and names outside the catalog are never + delivered. +- Host API scopes: the manifest's `host_api_scopes` that are in the API key + scope catalog (`auth.ValidAPIKeyScopes`). The rest are reported as + unsupported and never granted. + +An installation is pending while either set is not a subset of its grant. A +grant's scopes count only while its key is usable: it exists, it opens, and the +account it acts as is still an enabled administrator (`role = 'admin'` and +`enabled`, what the admin routes require of a key). A key revoked on the API +keys page, deleted with its owner, sealed under an earlier `SECRET_KEY`, or +owned by an account since demoted or disabled leaves the installation pending, +`GetHostAPICredential` refuses it, and the next approval replaces it with a key +owned by the approving administrator. + +## The grant + +`plugin_permission_grants` holds one row per installation: the approved event +access and scopes, the last explicit approval's administrator and time, and the +issued key (`api_key_id`, and the key sealed in `api_key_ciphertext` under AAD +`plugin_permission_grants:api_key_ciphertext::`). +Grants are written in three places: + +1. Every capability write (install and replace, in the same transaction) + inserts a grant approving the event access the installation asks for then, + with no scopes, unless one exists. Installing is consent to the events; + a replacement leaves an existing grant alone, except that one asking for + fewer scopes deletes the key (see Invariants). +2. At boot, before the catalog auto-update can run, + `InstallationStore.EnsurePermissionGrants` does the same for every + installation without a grant, so installations from before grants existed + keep the events they received. +3. `PermissionService.Approve`, behind + `PUT /api/v2/admin/plugins/installations/{id}/permissions/approval`, + approves the full current requirement as the acting administrator. + +## Approving what the administrator read + +The permissions read's `ETag` is a digest of its whole representation: +requirements, grant, and key state. The approval is a guarded `PUT`: it needs +`If-Match` (428 without one), and `Approve` takes an `ApprovalCheck` that the +API handler fills with the `If-Match` evaluation. The check runs inside the +approval's transaction, after the grant is locked, against the permissions read +in that transaction, and the grant written is exactly what the check saw. A +plugin update that asks for more, another approval, or a revoked key landing +between the administrator's read and the approval is 412 with the current +`ETag`, and nothing is written. The web panel then reloads and shows the new +requirements; it never sends `If-Match: *`. + +An approval runs `Service.OnLifecycleChange`, which rebuilds every API server's +[event subscriber index](plugin-event-delivery.md#gating-by-approved-access) +and restarts no plugin. + +## The host API key + +An approval that needs scopes and has no usable key with exactly those mints +one through `HostAPIKeyIssuer.IssueTx`, which runs +`APIKeyRepository.CreateAsActorTx(actor, actor, "Plugin: ", scopes)` +in the approval's transaction. The key sits on the approving administrator's +account and is listed on the API keys page. The audit row is written in the +transaction; its live frame is published only after the commit. `GetHostAPICredential` decrypts it for the calling installation, +which the host fixed when it started the process, and returns it with the +host's internal base URL. Proxy nodes don't wire the dependency and answer +`UNIMPLEMENTED`; a test run of a plugin (negative installation ID), or an +installation with nothing approved or its key revoked, gets +`FAILED_PRECONDITION`. + +## Invariants + +- One transaction per approval. Minting the new key, pointing the grant at + it, and deleting the key it replaces (`HostAPIKeyIssuer.RevokeTx`) commit + together, as does deleting the key when no scopes are asked for. A failure + or crash before the commit leaves the previous key, still named by the + grant, and no other; after it, the one live key is the one the grant names, + which uninstalling deletes. A key minted in a transaction that rolls back + never existed, and its bearer never left the server. +- Lock order: accounts, then the grant's key, then the grant. The key's + `ON DELETE SET NULL` writes the grant, so every API key deletion (the API + keys page, account deletion and promotion) already takes them in that order. + An approval share-locks the acting administrator and the audit row's + accounts (`HostAPIKeyIssuer.LockAccounts`), reads which key the grant names, + locks it, then locks the grant (`lockPermissionGrant`). If the grant then + names another key, it rolls back and starts again, up to five times. +- Uninstalling (`PermissionService.DeleteInstallation`) takes the same locks + in the same order, deletes the key through `HostAPIKeyIssuer.RevokeTx`, + which audits it like a deletion on the API keys page, and deletes the + installation, all in one transaction, so no scoped credential outlives its + plugin. An approval that lands meanwhile either + commits first, and its key is the one deleted, or finds the installation + gone and rolls back. +- An automatic or manual upgrade never widens a grant. New requirements stay + pending, and the plugin keeps what was approved, key included, until an + administrator approves the rest. +- An upgrade never leaves a key wider than the new manifest asks for. When + the key carries a scope outside the replacement's `host_api_scopes`, the + replacement's transaction (`narrowHostAPIKey`, called from + `InstallationStore.Update`) locks the key and the grant before the + installation row, deletes the key, and clears the approved scopes. The + plugin is then keyless, and pending while it still asks for scopes. No + administrator acts here, so that deletion has no audit entry. +- The key acts as its approving administrator. Scopes narrow; they never + grant. The key counts only while that account is an enabled administrator, + and is deleted with the account, which leaves the grant without a key and + the plugin pending. +- A plugin is never issued an unscoped key: `auth.PluginHostAPIKeys` refuses + an empty scope list. +- The API never returns the key. Approval responses name its ID and owner. + +## Backups + +A full restore keeps the live server's API keys and carries the live grants +with them (`internal/backup`, `secretTables`), for the installations the +restored data has. A grant names its key only where the restore kept that key; +one whose key it dropped (the key's owner is not in the backup, or has more +authority there) keeps its approvals without a key, so the plugin is pending, +and the restore reports it. `host_api_scopes` comes with the live release +(`CarryPluginReleases`). An installation whose id is another plugin in the +restored data comes back off without a grant. A restore that keeps no live +credentials (another deployment's backup, or a separate restore) restores no +grants: at the next start `EnsurePermissionGrants` gives each installation the +events it subscribes to and leaves its scopes pending. + +## Limits + +- Installations from before `host_api_scopes` was recorded ask for no scopes + until their next update or reinstall records the manifest's. + +- A plugin that read its key keeps it in memory. After a rotation or + revocation it holds the old key, now deleted, until it calls + `GetHostAPICredential` again, which the SDK tells it to do on `401`. +- Re-approving with the same scopes keeps a usable key, so its owner stays the + administrator who first approved those scopes. +- A demotion or disabling of the key's owner that commits while an approval + keeps that key leaves the key unusable once both commit. The permissions + read then shows the plugin pending, and the next approval replaces the key. +- A full restore that drops a grant (its installation is not in the backup, + or its id is another plugin there) keeps the key the grant named, which the + API keys carry kept on its own. Nothing can present that key afterwards (its + only sealed copy went with the grant), but it stays listed on its owner's API + keys page until an administrator deletes it. diff --git a/docs/architecture/redis-event-bus.md b/docs/architecture/redis-event-bus.md index e0c09f7715..55cd74ca36 100644 --- a/docs/architecture/redis-event-bus.md +++ b/docs/architecture/redis-event-bus.md @@ -62,10 +62,8 @@ server to move to. ## Invariants - A subscription runs on every node, the publisher's included. Work that must - happen once per event observes the publish on the node that made it: - `cache.ObservedEventBus` hands each event its process publishes to an - observer, with or without Redis. [Plugin event - delivery](plugin-event-delivery.md) works this way. + happen once per event runs on the node that made it, as [plugin event + delivery](plugin-event-delivery.md) does from its own hub's envelopes. - Publish and subscribe through `RedisEventBus`, or publish with `cache.PublishEvent` when a caller needs its own client. A `PUBLISH` or `SUBSCRIBE` sent on a go-redis client directly uses the bare name and reaches diff --git a/docs/architecture/secret-encryption.md b/docs/architecture/secret-encryption.md index df60f59680..9b5725f325 100644 --- a/docs/architecture/secret-encryption.md +++ b/docs/architecture/secret-encryption.md @@ -170,7 +170,12 @@ state (`plugin_auth_identities.refresh_state`, AAD [external-sign-in.md](external-sign-in.md#provider-re-check)). After a `SECRET_KEY` change that state no longer decrypts: it is sent as none, the OIDC plugin answers `UNSUPPORTED`, and those identities' sessions fall back to -the absolute session age until the person signs in again. Plugin runtime configuration is encrypted as one opaque +the absolute session age until the person signs in again. The host API key issued to a +plugin (`plugin_permission_grants.api_key_ciphertext`, AAD +`plugin_permission_grants:api_key_ciphertext::`) is covered too; +after a `SECRET_KEY` change the key no longer opens, the plugin shows as pending and gets +`FAILED_PRECONDITION`, and an administrator's next approval issues a new key +([plugin-permissions.md](plugin-permissions.md)). Plugin runtime configuration is encrypted as one opaque row-bound envelope rather than by manifest field. Consequently, runtime code must use `RuntimeConfigStore`; database JSON-member queries and indexes are not supported for `plugin_runtime_configs.config_value`. diff --git a/go.mod b/go.mod index 549064e510..8099b5bef1 100644 --- a/go.mod +++ b/go.mod @@ -134,7 +134,7 @@ require ( ) require ( - github.com/Silo-Server/silo-plugin-sdk v0.31.0 + github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261106014723-f52642897933 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.14 // indirect github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.30 // indirect github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.30 // indirect diff --git a/go.sum b/go.sum index 3925190e3b..733f9ac913 100644 --- a/go.sum +++ b/go.sum @@ -14,8 +14,8 @@ github.com/PuerkitoBio/goquery v1.8.0 h1:PJTF7AmFCFKk1N6V6jmKfrNH9tV5pNE6lZMkG0g github.com/PuerkitoBio/goquery v1.8.0/go.mod h1:ypIiRMtY7COPGk+I/YbZLbxsxn9g5ejnI2HSMtkjZvI= github.com/SherClockHolmes/webpush-go v1.4.0 h1:ocnzNKWN23T9nvHi6IfyrQjkIc0oJWv1B1pULsf9i3s= github.com/SherClockHolmes/webpush-go v1.4.0/go.mod h1:XSq8pKX11vNV8MJEMwjrlTkxhAj1zKfxmyhdV7Pd6UA= -github.com/Silo-Server/silo-plugin-sdk v0.31.0 h1:lpDqlkpv/GxnhBEzX2WY8nw3qILIKUI1EvjY8Mw/pu8= -github.com/Silo-Server/silo-plugin-sdk v0.31.0/go.mod h1:+r4X2TAiB9Gk22sUj1gFWUj65lll1P1/dMS+Ncvy3Y0= +github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261106014723-f52642897933 h1:WPrrqdIPrUVaZTfnSt3V28gX9fBppoUeRD1NU6GzDZU= +github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261106014723-f52642897933/go.mod h1:+r4X2TAiB9Gk22sUj1gFWUj65lll1P1/dMS+Ncvy3Y0= github.com/TwiN/go-color v1.4.1 h1:mqG0P/KBgHKVqmtL5ye7K0/Gr4l6hTksPgTgMk3mUzc= github.com/TwiN/go-color v1.4.1/go.mod h1:WcPf/jtiW95WBIsEeY1Lc/b8aaWoiqQpu5cf8WFxu+s= github.com/abadojack/whatlanggo v1.0.1 h1:19N6YogDnf71CTHm3Mp2qhYfkRdyvbgwWdd2EPxJRG4= diff --git a/internal/api/handlers/admin_plugin_lifecycle.go b/internal/api/handlers/admin_plugin_lifecycle.go index f92abc1b6b..832600a2e9 100644 --- a/internal/api/handlers/admin_plugin_lifecycle.go +++ b/internal/api/handlers/admin_plugin_lifecycle.go @@ -197,11 +197,9 @@ func (h *PluginHandler) DeleteAdminPluginInstallation(ctx context.Context, id in } stopped = true } - if err := h.installations.Delete(ctx, id); err != nil { + if err := h.deleteInstallation(ctx, id); err != nil { if stopped && installation.Enabled { - if _, restartErr := h.service.Start(ctx, id); restartErr != nil { - slog.ErrorContext(ctx, "restarting plugin after failed uninstall", "component", "api", "installation_id", id, "error", restartErr) - } + h.restartAfterFailedUninstall(ctx, id) } if errors.Is(err, plugins.ErrBuiltinInstallationImmutable) { return ErrPluginBuiltinInstallation @@ -214,6 +212,21 @@ func (h *PluginHandler) DeleteAdminPluginInstallation(ctx context.Context, id in return nil } +func (h *PluginHandler) restartAfterFailedUninstall(ctx context.Context, id int) { + if _, err := h.service.Start(ctx, id); err != nil { + slog.ErrorContext(ctx, "restarting plugin after failed uninstall", "component", "api", "installation_id", id, "error", err) + } +} + +// deleteInstallation uninstalls through the permission service when there is +// one, so the plugin's host API key is deleted with an audit entry. +func (h *PluginHandler) deleteInstallation(ctx context.Context, id int) error { + if permissions := h.service.Permissions(); permissions != nil { + return permissions.DeleteInstallation(ctx, actorUserID(ctx), id) + } + return h.installations.Delete(ctx, id) +} + // writePluginLifecycleError keeps the frozen bridge answers for the seams. func writePluginLifecycleError(w http.ResponseWriter, r *http.Request, err error, action string) { var apiErr *APIError diff --git a/internal/api/handlers/admin_plugin_permissions.go b/internal/api/handlers/admin_plugin_permissions.go new file mode 100644 index 0000000000..10d59ffc3b --- /dev/null +++ b/internal/api/handlers/admin_plugin_permissions.go @@ -0,0 +1,61 @@ +package handlers + +import ( + "context" + "errors" + "net/http" + + "github.com/Silo-Server/silo-server/internal/plugins" +) + +func (h *PluginHandler) pluginPermissions() (*plugins.PermissionService, error) { + if h != nil { + if permissions := h.service.Permissions(); permissions != nil { + return permissions, nil + } + } + return nil, apiError(http.StatusServiceUnavailable, "unavailable", "Plugin permissions not configured") +} + +func pluginPermissionsError(err error) error { + if errors.Is(err, plugins.ErrBuiltinInstallationImmutable) { + return ErrPluginBuiltinInstallation + } + return err +} + +// GetAdminPluginPermissions returns what the installation asks for and what +// an administrator approved. Errors: plugins.ErrInstallationNotFound, +// ErrPluginBuiltinInstallation. +func (h *PluginHandler) GetAdminPluginPermissions(ctx context.Context, id int) (*plugins.PluginPermissions, error) { + permissions, err := h.pluginPermissions() + if err != nil { + return nil, err + } + out, err := permissions.Permissions(ctx, id) + return out, pluginPermissionsError(err) +} + +// ApproveAdminPluginPermissions approves everything the installation asks for +// now as the request's account, issuing or revoking its host API key. check +// runs inside the approval's transaction (plugins.PermissionService.Approve) +// and its error comes back unchanged. Errors: plugins.ErrInstallationNotFound, +// ErrPluginBuiltinInstallation. +func (h *PluginHandler) ApproveAdminPluginPermissions(ctx context.Context, id int, check plugins.ApprovalCheck) (*plugins.PluginPermissions, error) { + permissions, err := h.pluginPermissions() + if err != nil { + return nil, err + } + out, err := permissions.Approve(ctx, actorUserID(ctx), id, check) + return out, ownerError(pluginPermissionsError(err)) +} + +// AdminPluginPermissionsPending reports which installations ask for +// permissions an administrator hasn't approved. +func (h *PluginHandler) AdminPluginPermissionsPending(ctx context.Context) (map[int]bool, error) { + permissions, err := h.pluginPermissions() + if err != nil { + return nil, err + } + return permissions.PendingByInstallation(ctx) +} diff --git a/internal/api/router.go b/internal/api/router.go index 18be87ac6f..c3fc0601a3 100644 --- a/internal/api/router.go +++ b/internal/api/router.go @@ -3100,6 +3100,7 @@ func newChiRouter(deps Dependencies) chi.Router { v2PluginHandler.SetAuthProvidersChanged(deps.OnAuthProvidersChanged) v2deps.AdminPluginInventory = v2PluginHandler v2deps.AdminPluginConfiguration = v2PluginHandler + v2deps.AdminPluginPermissions = v2PluginHandler v2deps.AdminPluginLifecycle = v2PluginHandler v2deps.AdminPluginUploads = v2PluginHandler externalSignInPlugins = v2PluginHandler diff --git a/internal/api/testdata/media_routes.txt b/internal/api/testdata/media_routes.txt index 6e9af8af7d..f1f11c3c31 100644 --- a/internal/api/testdata/media_routes.txt +++ b/internal/api/testdata/media_routes.txt @@ -288,6 +288,8 @@ PUT /api/v2/admin/plugins/installations/{id}/auth-binding non-media POST /api/v2/admin/plugins/installations/{id}/auth-binding/test non-media PUT /api/v2/admin/plugins/installations/{id}/config non-media POST /api/v2/admin/plugins/installations/{id}/config/test non-media +GET /api/v2/admin/plugins/installations/{id}/permissions non-media +PUT /api/v2/admin/plugins/installations/{id}/permissions/approval non-media POST /api/v2/admin/plugins/installations/{id}/restart non-media PUT /api/v2/admin/plugins/installations/{id}/task-bindings/{capability_id} non-media POST /api/v2/admin/plugins/installations/{id}/update non-media @@ -1643,6 +1645,8 @@ PUT /api/v2/admin/plugins/installations/{id}/auth-binding non-media POST /api/v2/admin/plugins/installations/{id}/auth-binding/test non-media PUT /api/v2/admin/plugins/installations/{id}/config non-media POST /api/v2/admin/plugins/installations/{id}/config/test non-media +GET /api/v2/admin/plugins/installations/{id}/permissions non-media +PUT /api/v2/admin/plugins/installations/{id}/permissions/approval non-media POST /api/v2/admin/plugins/installations/{id}/restart non-media PUT /api/v2/admin/plugins/installations/{id}/task-bindings/{capability_id} non-media POST /api/v2/admin/plugins/installations/{id}/update non-media diff --git a/internal/apiv2/admin_plugin_installations.go b/internal/apiv2/admin_plugin_installations.go index f8812e5d95..f670cbade3 100644 --- a/internal/apiv2/admin_plugin_installations.go +++ b/internal/apiv2/admin_plugin_installations.go @@ -237,6 +237,7 @@ type AdminPluginInstallation struct { AuthBindings []AdminPluginAuthBinding `json:"auth_bindings"` TaskBindings []AdminPluginTaskBinding `json:"task_bindings"` Runtime AdminPluginRuntime `json:"runtime"` + PermissionsPending bool `json:"permissions_pending" doc:"True while the installation asks for event access or host API scopes an administrator hasn't approved; see getAdminPluginInstallationPermissions"` CreatedAt Instant `json:"created_at"` UpdatedAt Instant `json:"updated_at"` } @@ -376,7 +377,16 @@ func adminPluginRuntimeOf(v *handlers.PluginRuntimeView) AdminPluginRuntime { return out } -func (reg *Registry) adminPluginInstallationOf(v handlers.PluginInstallationView) (AdminPluginInstallation, error) { +// adminPluginInstallationOne projects one installation a mutation returned. +func (reg *Registry) adminPluginInstallationOne(ctx context.Context, v handlers.PluginInstallationView) (AdminPluginInstallation, error) { + pending, err := reg.adminPluginPermissionsPending(ctx, v.ID) + if err != nil { + return AdminPluginInstallation{}, err + } + return reg.adminPluginInstallationOf(v, pending) +} + +func (reg *Registry) adminPluginInstallationOf(v handlers.PluginInstallationView, permissionsPending bool) (AdminPluginInstallation, error) { caps, err := adminPluginCapabilitiesOf(v.Capabilities) if err != nil { return AdminPluginInstallation{}, err @@ -389,7 +399,7 @@ func (reg *Registry) adminPluginInstallationOf(v handlers.PluginInstallationView if err != nil { return AdminPluginInstallation{}, err } - out := AdminPluginInstallation{ID: IDFromInt(int64(v.ID)), PluginID: v.PluginID, Version: v.Version, InstallPath: v.InstallPath, Enabled: v.Enabled, Kind: v.Kind, UpdatePolicy: v.UpdatePolicy, SourceKind: v.SourceKind, RepositoryName: v.RepositoryName, RepoURL: v.RepoURL, Presentation: adminPluginPresentationOf(v.Presentation), UpdatesPaused: v.UpdatesPaused, Capabilities: caps, GlobalConfigSchema: global, UserConfigSchema: user, Routes: pluginRoutesOf(v.Routes), Assets: pluginAssetsOf(v.Assets), Metadata: NonNilMap(PluginJSONValue(v.Metadata)), GlobalConfigs: make([]AdminPluginConfigValue, 0, len(v.GlobalConfigs)), AuthBindings: make([]AdminPluginAuthBinding, 0, len(v.AuthBindings)), TaskBindings: make([]AdminPluginTaskBinding, 0, len(v.TaskBindings)), Runtime: adminPluginRuntimeOf(v.Runtime), CreatedAt: NewInstant(v.CreatedAt), UpdatedAt: NewInstant(v.UpdatedAt)} + out := AdminPluginInstallation{ID: IDFromInt(int64(v.ID)), PluginID: v.PluginID, Version: v.Version, InstallPath: v.InstallPath, Enabled: v.Enabled, Kind: v.Kind, UpdatePolicy: v.UpdatePolicy, SourceKind: v.SourceKind, RepositoryName: v.RepositoryName, RepoURL: v.RepoURL, Presentation: adminPluginPresentationOf(v.Presentation), UpdatesPaused: v.UpdatesPaused, Capabilities: caps, GlobalConfigSchema: global, UserConfigSchema: user, Routes: pluginRoutesOf(v.Routes), Assets: pluginAssetsOf(v.Assets), Metadata: NonNilMap(PluginJSONValue(v.Metadata)), GlobalConfigs: make([]AdminPluginConfigValue, 0, len(v.GlobalConfigs)), AuthBindings: make([]AdminPluginAuthBinding, 0, len(v.AuthBindings)), TaskBindings: make([]AdminPluginTaskBinding, 0, len(v.TaskBindings)), Runtime: adminPluginRuntimeOf(v.Runtime), PermissionsPending: permissionsPending, CreatedAt: NewInstant(v.CreatedAt), UpdatedAt: NewInstant(v.UpdatedAt)} if v.RepositoryID != nil { out.RepositoryID = new(IDFromInt(int64(*v.RepositoryID))) } @@ -521,6 +531,12 @@ func registerAdminPluginInventory(reg *Registry) { seen[r.ID] = true } slices.SortFunc(rows, func(a, b handlers.PluginInstallationView) int { return cmp.Compare(a.ID, b.ID) }) + pending := map[int]bool{} + if svc := reg.deps.AdminPluginPermissions; svc != nil { + if pending, err = svc.AdminPluginPermissionsPending(ctx); err != nil { + return nil, serviceProblem(err) + } + } items := make([]AdminPluginInstallation, 0, in.Limit) next := "" last := 0 @@ -535,7 +551,7 @@ func registerAdminPluginInventory(reg *Registry) { } break } - item, err := reg.adminPluginInstallationOf(r) + item, err := reg.adminPluginInstallationOf(r, pending[r.ID]) if err != nil { return nil, serviceProblem(err) } diff --git a/internal/apiv2/admin_plugin_lifecycle.go b/internal/apiv2/admin_plugin_lifecycle.go index 148e207925..7b05a659bf 100644 --- a/internal/apiv2/admin_plugin_lifecycle.go +++ b/internal/apiv2/admin_plugin_lifecycle.go @@ -64,15 +64,19 @@ func adminPluginLifecycleProblem(err error) error { return adminPluginMutationProblem(err) } -func (reg *Registry) adminPluginInstallationOutput(view handlers.PluginInstallationView, err error) (*AdminPluginInstallationOutput, error) { - if err != nil { - return nil, adminPluginLifecycleProblem(err) - } - out, err := reg.adminPluginInstallationOf(view) - if err != nil { - return nil, serviceProblem(err) +// adminPluginInstallationOutput returns the projection of a lifecycle +// result, taking the seam's (view, error) pair directly. +func (reg *Registry) adminPluginInstallationOutput(ctx context.Context) func(handlers.PluginInstallationView, error) (*AdminPluginInstallationOutput, error) { + return func(view handlers.PluginInstallationView, err error) (*AdminPluginInstallationOutput, error) { + if err != nil { + return nil, adminPluginLifecycleProblem(err) + } + out, err := reg.adminPluginInstallationOne(ctx, view) + if err != nil { + return nil, serviceProblem(err) + } + return &AdminPluginInstallationOutput{Body: out}, nil } - return &AdminPluginInstallationOutput{Body: out}, nil } func registerAdminPluginLifecycle(reg *Registry) { @@ -102,7 +106,7 @@ func registerAdminPluginLifecycle(reg *Registry) { if !hasCatalog && strings.TrimSpace(input.ArchiveURL) == "" { return nil, validationProblem(locationBody+".archive_url", codeRequired, "Supply archive_url or repository_id, plugin_id and version.") } - return reg.adminPluginInstallationOutput(reg.deps.AdminPluginLifecycle.CreateAdminPluginInstallation(ctx, input)) + return reg.adminPluginInstallationOutput(ctx)(reg.deps.AdminPluginLifecycle.CreateAdminPluginInstallation(ctx, input)) }) update := op(http.MethodPut, "/{id}", "updateAdminPluginInstallation", "Assign enabled and/or update_policy on one installation. Disabling stops the running plugin first. Repeating the same assignment converges on one stored row.", RetrySafetyNaturalIdempotent) update.Errors = append(update.Errors, http.StatusNotFound, http.StatusConflict) @@ -120,7 +124,7 @@ func registerAdminPluginLifecycle(reg *Registry) { if in.Body.Enabled == nil && in.Body.UpdatePolicy == nil { return nil, validationProblem(locationBody, codeRequired, "Supply enabled or update_policy.") } - return reg.adminPluginInstallationOutput(reg.deps.AdminPluginLifecycle.UpdateAdminPluginInstallation(ctx, id, handlers.PluginInstallationUpdateInput{Enabled: in.Body.Enabled, UpdatePolicy: in.Body.UpdatePolicy})) + return reg.adminPluginInstallationOutput(ctx)(reg.deps.AdminPluginLifecycle.UpdateAdminPluginInstallation(ctx, id, handlers.PluginInstallationUpdateInput{Enabled: in.Body.Enabled, UpdatePolicy: in.Body.UpdatePolicy})) }) apply := op(http.MethodPost, "/{id}/update", "applyAdminPluginUpdate", "Install the recorded available version from the installation's repository, fetching over the network, and clear the marker. No applicable update is 409. There is no replay identity: a lost response may follow a committed update; reconcile from the installation and never automatically retry.", RetrySafetyNonRetryable) apply.Errors = append(apply.Errors, http.StatusNotFound, http.StatusConflict) @@ -132,7 +136,7 @@ func registerAdminPluginLifecycle(reg *Registry) { if p != nil { return nil, p } - return reg.adminPluginInstallationOutput(reg.deps.AdminPluginLifecycle.ApplyAdminPluginUpdate(ctx, id)) + return reg.adminPluginInstallationOutput(ctx)(reg.deps.AdminPluginLifecycle.ApplyAdminPluginUpdate(ctx, id)) }) restart := op(http.MethodPost, "/{id}/restart", "restartAdminPluginInstallation", "Stop the installation's process and, for a resident plugin (one the server supervises, such as a network access provider), start it again with a fresh failure budget; the response's runtime reports the outcome, including a launch that failed. A non-resident plugin is only stopped and launches on its next use. A disabled installation is 409. Repeating the request converges on one running process.", RetrySafetyNaturalIdempotent) restart.Errors = append(restart.Errors, http.StatusNotFound, http.StatusConflict) @@ -144,7 +148,7 @@ func registerAdminPluginLifecycle(reg *Registry) { if p != nil { return nil, p } - return reg.adminPluginInstallationOutput(reg.deps.AdminPluginLifecycle.RestartAdminPluginInstallation(ctx, id)) + return reg.adminPluginInstallationOutput(ctx)(reg.deps.AdminPluginLifecycle.RestartAdminPluginInstallation(ctx, id)) }) remove := op(http.MethodDelete, "/{id}", "deleteAdminPluginInstallation", "Stop the plugin, delete the installation row (configuration, bindings and archives cascade) and remove its files. Row delete and file removal are not one transaction and a repeat finds no row: a later 404 is not this caller's receipt; never automatically retry.", RetrySafetyNonRetryable) remove.DefaultStatus = http.StatusNoContent diff --git a/internal/apiv2/admin_plugin_permissions.go b/internal/apiv2/admin_plugin_permissions.go new file mode 100644 index 0000000000..0919bed082 --- /dev/null +++ b/internal/apiv2/admin_plugin_permissions.go @@ -0,0 +1,203 @@ +package apiv2 + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "net/http" + "strconv" + + "github.com/Silo-Server/silo-server/internal/plugins" +) + +// AdminPluginPermissionsService is the slice of *handlers.PluginHandler the +// plugin permission operations use. Every method refuses the reserved builtin +// row and reports an unknown installation as plugins.ErrInstallationNotFound. +// ApproveAdminPluginPermissions runs check inside the approval's transaction +// and returns its error unchanged. +type AdminPluginPermissionsService interface { + GetAdminPluginPermissions(context.Context, int) (*plugins.PluginPermissions, error) + ApproveAdminPluginPermissions(context.Context, int, plugins.ApprovalCheck) (*plugins.PluginPermissions, error) + AdminPluginPermissionsPending(context.Context) (map[int]bool, error) +} + +// AdminPluginEventAccess is the event access an installation asks for and +// has approved. +type AdminPluginEventAccess struct { + Required []string `json:"required" enum:"admin,user_data" doc:"Access classes of the events the plugin subscribes to that need approval: admin (server operations such as playback activity, scans and jobs) and user_data (one profile's personal data, such as its notifications). Public and plugin events need none. The vocabulary is open: ignore a class you don't know."` + Approved []string `json:"approved" enum:"admin,user_data" doc:"Access classes an administrator approved. The plugin receives events of these classes and of no others that need approval."` +} + +// AdminPluginHostAPIScopes is the API key scopes an installation asks for +// and has approved. +type AdminPluginHostAPIScopes struct { + Requested []string `json:"requested" doc:"The manifest's host_api_scopes"` + Required []string `json:"required" doc:"The requested scopes this server can issue"` + Unsupported []string `json:"unsupported" doc:"The requested scopes this server doesn't know; they are never granted"` + Approved []string `json:"approved" doc:"Scopes the plugin's usable host API key carries; empty while none is usable, including after the key was revoked or its account lost the admin role"` +} + +// AdminPluginHostAPIKey describes the key issued to a plugin, never the key +// itself. +type AdminPluginHostAPIKey struct { + Issued bool `json:"issued" doc:"True while a host API key is issued to the plugin"` + Usable bool `json:"usable" doc:"True while the issued key can act for the plugin. False when none is issued, when the account it acts as is no longer an enabled administrator, or when this server can't read it (it was stored under another SECRET_KEY). An unusable key grants nothing: the plugin is pending and an approval issues a replacement"` + ID *ID `json:"id,omitempty" doc:"The key on the API keys page, where it can be revoked; omitted while none is issued"` + OwnerUserID *ID `json:"owner_user_id,omitempty" doc:"The account the key acts as: the administrator whose approval issued it. It stops working if that account loses the admin role or is disabled, and is deleted with the account. Omitted while none is issued"` +} + +// AdminPluginPermissions is what one installation receives and may call: what +// it asks for, what an administrator approved, and the key it was issued. +type AdminPluginPermissions struct { + InstallationID ID `json:"installation_id"` + EventAccess AdminPluginEventAccess `json:"event_access"` + HostAPIScopes AdminPluginHostAPIScopes `json:"host_api_scopes"` + Pending bool `json:"pending" doc:"True while the plugin asks for event access or host API scopes that aren't approved. It keeps what was approved before until an administrator approves the rest"` + ApprovedAt *Instant `json:"approved_at,omitempty" doc:"The last explicit approval; omitted when none was given, such as when event access was approved by installing the plugin"` + ApprovedByUserID *ID `json:"approved_by_user_id,omitempty" doc:"The administrator who gave the last explicit approval; omitted when none was given or the account was deleted"` + HostAPIKey AdminPluginHostAPIKey `json:"host_api_key"` +} +type AdminPluginPermissionsOutput struct { + Status int + ETag string `header:"ETag"` + Body AdminPluginPermissions +} + +// AdminPluginPermissionsInput is the input of the conditional read and the +// guarded approval. +type AdminPluginPermissionsInput struct { + AdminPluginInstallationIDInput + IfMatch string `header:"If-Match"` + IfNoneMatch string `header:"If-None-Match"` +} + +// adminPluginPermissionsTag validates the whole permissions representation, +// so an approval sent with it approves exactly what the administrator read: +// a plugin update that asks for more, or another administrator's approval, +// changes it. A digest rather than a revision: the same requirements and +// grant read again are the same thing to approve. +func adminPluginPermissionsTag(ctx context.Context, body AdminPluginPermissions) (EntityTag, error) { + raw, err := json.Marshal(body) + if err != nil { + return EntityTag{}, err + } + digest := sha256.Sum256(raw) + return RenderETag("admin-plugin-permissions:"+strconv.Itoa(claimsFrom(ctx).UserID)+":"+profileFrom(ctx)+":"+viewerScopeDigest(ctx), + string(body.InstallationID)+":"+hex.EncodeToString(digest[:]), 1), nil +} + +func adminPluginPermissionsOf(p *plugins.PluginPermissions) AdminPluginPermissions { + out := AdminPluginPermissions{ + InstallationID: IDFromInt(int64(p.InstallationID)), + EventAccess: AdminPluginEventAccess{Required: NonNil(p.Required.EventAccess), Approved: []string{}}, + HostAPIScopes: AdminPluginHostAPIScopes{Requested: NonNil(p.Required.RequestedScopes), Required: NonNil(p.Required.RequiredScopes), + Unsupported: NonNil(p.Required.UnsupportedScopes), Approved: NonNil(p.Grant.EffectiveHostAPIScopes())}, + Pending: p.Pending, + } + grant := p.Grant + if grant == nil { + return out + } + out.EventAccess.Approved = NonNil(grant.ApprovedEventAccess) + if grant.ApprovedAt != nil { + out.ApprovedAt = new(NewInstant(*grant.ApprovedAt)) + } + if grant.ApprovedByUserID != nil { + out.ApprovedByUserID = new(IDFromInt(int64(*grant.ApprovedByUserID))) + } + if grant.APIKeyID != nil { + out.HostAPIKey.Issued = true + out.HostAPIKey.Usable = grant.HostAPIKeyUsable() + out.HostAPIKey.ID = new(IDFromInt(*grant.APIKeyID)) + if grant.APIKeyOwnerUserID != nil { + out.HostAPIKey.OwnerUserID = new(IDFromInt(int64(*grant.APIKeyOwnerUserID))) + } + } + return out +} + +func adminPluginPermissionsOutput(ctx context.Context, p *plugins.PluginPermissions) (*AdminPluginPermissionsOutput, EntityTag, error) { + body := adminPluginPermissionsOf(p) + tag, err := adminPluginPermissionsTag(ctx, body) + if err != nil { + return nil, EntityTag{}, err + } + return &AdminPluginPermissionsOutput{ETag: tag.String(), Body: body}, tag, nil +} + +// adminPluginPermissionsPending reports whether one installation asks for +// permissions that aren't approved; false when the service isn't wired. +func (reg *Registry) adminPluginPermissionsPending(ctx context.Context, installationID int) (bool, error) { + if reg.deps.AdminPluginPermissions == nil { + return false, nil + } + p, err := reg.deps.AdminPluginPermissions.GetAdminPluginPermissions(ctx, installationID) + if err != nil { + return false, err + } + return p.Pending, nil +} + +func registerAdminPluginPermissions(reg *Registry) { + op := func(method, path, id, summary string, safety RetrySafety) Operation { + o := Operation{Operation: humaOp(method, Prefix+"/admin/plugins/installations/{id}/"+path, id, "admin-plugins", summary), Class: ClassActingAdmin, DemoRestricted: isMutatingMethod(method), ServiceBacked: true, RetrySafety: safety} + o.Errors = []int{http.StatusNotFound, http.StatusConflict} + return o + } + read := op(http.MethodGet, "permissions", "getAdminPluginInstallationPermissions", "Read what one installation asks to receive and call, and what an administrator approved: the event access classes its subscriptions need, the host API scopes its manifest requests, and the host API key issued for them. The key itself is never returned. The ETag validates the whole representation; approving requires it. The reserved builtin row is 409.", "") + read.Conditional = true + Register(reg, read, func(ctx context.Context, in *AdminPluginPermissionsInput) (*AdminPluginPermissionsOutput, error) { + if reg.deps.AdminPluginPermissions == nil { + return nil, unavailable("plugin permissions") + } + id, p := adminPluginInstallationID(in.ID) + if p != nil { + return nil, p + } + permissions, err := reg.deps.AdminPluginPermissions.GetAdminPluginPermissions(ctx, id) + if err != nil { + return nil, adminPluginMutationProblem(err) + } + out, tag, err := adminPluginPermissionsOutput(ctx, permissions) + if err != nil { + return nil, serviceProblem(err) + } + if matched, p := EvaluateReadPreconditions(in.IfMatch, in.IfNoneMatch, tag); p != nil { + return nil, p + } else if matched { + return NotModified(out, tag), nil + } + return out, nil + }) + approve := op(http.MethodPut, "permissions/approval", "approveAdminPluginInstallationPermissions", "Approve everything the installation asks for now, as the acting administrator. If-Match must carry the ETag of the permissions read the administrator approved; the server compares it with the permissions inside the approval's transaction, so a plugin update that asks for more, or another approval, landing in between is 412 with the current ETag and changes nothing. When the installation requests host API scopes this server knows and has no usable key with exactly those, a key acting as the acting administrator is issued and the previous key revoked in the same transaction; when it requests none, its key is revoked. The event subscriber index rebuilds on every server; the plugin is not restarted.", RetrySafetyNaturalIdempotent) + approve.Guarded = true + Register(reg, approve, func(ctx context.Context, in *AdminPluginPermissionsInput) (*AdminPluginPermissionsOutput, error) { + if reg.deps.AdminPluginPermissions == nil { + return nil, unavailable("plugin permissions") + } + id, p := adminPluginInstallationID(in.ID) + if p != nil { + return nil, p + } + check := func(current *plugins.PluginPermissions) error { + tag, err := adminPluginPermissionsTag(ctx, adminPluginPermissionsOf(current)) + if err != nil { + return err + } + if p := EvaluateGuardedPreconditions(in.IfMatch, in.IfNoneMatch, tag); p != nil { + return p + } + return nil + } + permissions, err := reg.deps.AdminPluginPermissions.ApproveAdminPluginPermissions(ctx, id, check) + if err != nil { + return nil, adminPluginMutationProblem(err) + } + out, _, err := adminPluginPermissionsOutput(ctx, permissions) + if err != nil { + return nil, serviceProblem(err) + } + return out, nil + }) +} diff --git a/internal/apiv2/admin_plugin_permissions_test.go b/internal/apiv2/admin_plugin_permissions_test.go new file mode 100644 index 0000000000..ab8db34b0e --- /dev/null +++ b/internal/apiv2/admin_plugin_permissions_test.go @@ -0,0 +1,93 @@ +package apiv2 + +import ( + "context" + "net/http" + "testing" + + "github.com/Silo-Server/silo-server/internal/plugins" +) + +// fakePluginPermissions serves one installation whose requirements a test +// can change, and approves through the check as the real service does: in +// what stands for the approval's transaction, after beforeCheck. +type fakePluginPermissions struct { + scopes []string + approved []string + approvals int + beforeCheck func() +} + +func (f *fakePluginPermissions) current() *plugins.PluginPermissions { + required := plugins.DeriveRequiredPermissions(nil, f.scopes, []string{"admin:monitor:read", "admin:users"}) + grant := &plugins.PermissionGrant{InstallationID: 7, ApprovedEventAccess: []string{}, ApprovedHostAPIScopes: f.approved} + return &plugins.PluginPermissions{InstallationID: 7, Required: required, Grant: grant, Pending: len(f.approved) != len(required.RequiredScopes)} +} + +func (f *fakePluginPermissions) GetAdminPluginPermissions(context.Context, int) (*plugins.PluginPermissions, error) { + return f.current(), nil +} + +func (f *fakePluginPermissions) ApproveAdminPluginPermissions(_ context.Context, _ int, check plugins.ApprovalCheck) (*plugins.PluginPermissions, error) { + if f.beforeCheck != nil { + f.beforeCheck() + } + if err := check(f.current()); err != nil { + return nil, err + } + f.approved = f.current().Required.RequiredScopes + f.approvals++ + return f.current(), nil +} + +func (f *fakePluginPermissions) AdminPluginPermissionsPending(context.Context) (map[int]bool, error) { + return map[int]bool{7: f.current().Pending}, nil +} + +// TestAdminPluginPermissionsApprovalGuard covers the approval's validator: +// it is required, it must name the permissions the administrator read, and +// an update that lands between that read and the approval's check is 412 +// with the current validator and approves nothing. +func TestAdminPluginPermissionsApprovalGuard(t *testing.T) { + f := &fakePluginPermissions{scopes: []string{"admin:monitor:read"}} + deps := requestDeps(fixtureRequests()) + deps.AdminPluginPermissions = f + h := NewHandler(deps) + path := Prefix + "/admin/plugins/installations/7/permissions" + + read := do(t, h, http.MethodGet, path, "", actingRequestAdmin) + seen := read.Header().Get("ETag") + if read.Code != http.StatusOK || seen == "" { + t.Fatal(read.Code, read.Body.String()) + } + if cached := do(t, h, http.MethodGet, path, "", with(actingRequestAdmin, "If-None-Match", seen)); cached.Code != http.StatusNotModified { + t.Fatal(cached.Code, cached.Body.String()) + } + requireProblem(t, do(t, h, http.MethodPut, path+"/approval", "", actingRequestAdmin), TypePreconditionRequired) + + // An update asking for more lands after the read. + f.scopes = []string{"admin:users"} + stale := do(t, h, http.MethodPut, path+"/approval", "", with(actingRequestAdmin, "If-Match", seen)) + requireProblem(t, stale, TypePreconditionFailed) + current := do(t, h, http.MethodGet, path, "", actingRequestAdmin).Header().Get("ETag") + if stale.Header().Get("ETag") != current || current == seen || f.approvals != 0 { + t.Fatalf("stale approval: ETag %q, current %q, approvals %d", stale.Header().Get("ETag"), current, f.approvals) + } + + // The update lands after the read but before the approval's check. + f.beforeCheck = func() { f.scopes = []string{"admin:monitor:read", "admin:users"} } + requireProblem(t, do(t, h, http.MethodPut, path+"/approval", "", with(actingRequestAdmin, "If-Match", current)), TypePreconditionFailed) + if f.approvals != 0 { + t.Fatalf("an approval landed against requirements the administrator never read") + } + f.beforeCheck = nil + + current = do(t, h, http.MethodGet, path, "", actingRequestAdmin).Header().Get("ETag") + approved := do(t, h, http.MethodPut, path+"/approval", "", with(actingRequestAdmin, "If-Match", current)) + if approved.Code != http.StatusOK || f.approvals != 1 { + t.Fatal(approved.Code, approved.Body.String()) + } + if after := do(t, h, http.MethodGet, path, "", actingRequestAdmin).Header().Get("ETag"); approved.Header().Get("ETag") != after || after == current { + t.Fatalf("approval ETag %q, read after %q, before %q", approved.Header().Get("ETag"), after, current) + } +} diff --git a/internal/apiv2/admin_plugin_uploads.go b/internal/apiv2/admin_plugin_uploads.go index 5ba9657ed2..43840cf348 100644 --- a/internal/apiv2/admin_plugin_uploads.go +++ b/internal/apiv2/admin_plugin_uploads.go @@ -115,7 +115,7 @@ func registerAdminPluginUploads(reg *Registry) { if err != nil { return nil, adminPluginUploadProblem(err) } - out, err := reg.adminPluginInstallationOf(view) + out, err := reg.adminPluginInstallationOne(ctx, view) if err != nil { return nil, serviceProblem(err) } @@ -173,7 +173,7 @@ func registerAdminPluginUploads(reg *Registry) { if err != nil { return nil, adminPluginUploadProblem(err) } - out, err := reg.adminPluginInstallationOf(view) + out, err := reg.adminPluginInstallationOne(ctx, view) if err != nil { return nil, serviceProblem(err) } diff --git a/internal/apiv2/document.go b/internal/apiv2/document.go index 67b9b6fe5e..1730a3c078 100644 --- a/internal/apiv2/document.go +++ b/internal/apiv2/document.go @@ -613,6 +613,7 @@ func registerAll(reg *Registry) { registerAdminPluginRepositoryDelete(reg) registerAdminPluginInventory(reg) registerAdminPluginConfiguration(reg) + registerAdminPluginPermissions(reg) registerAdminPluginLifecycle(reg) registerAdminPluginUploads(reg) registerAdminTelemetryParity(reg) diff --git a/internal/apiv2/router.go b/internal/apiv2/router.go index 8bd77036d3..c8bbcbae25 100644 --- a/internal/apiv2/router.go +++ b/internal/apiv2/router.go @@ -233,6 +233,7 @@ type Dependencies struct { AdminPluginRepositoryDeletes AdminPluginRepositoryDeleteService AdminPluginInventory AdminPluginInventoryService AdminPluginConfiguration AdminPluginConfigurationService + AdminPluginPermissions AdminPluginPermissionsService AdminPluginLifecycle AdminPluginLifecycleService AdminPluginUploads AdminPluginUploadService AdminTelemetryParity AdminTelemetryParityService diff --git a/internal/auth/api_key_metadata.go b/internal/auth/api_key_metadata.go index 8c3c2bef34..c46b183103 100644 --- a/internal/auth/api_key_metadata.go +++ b/internal/auth/api_key_metadata.go @@ -182,17 +182,7 @@ func (r *APIKeyRepository) DeleteByAdminConditional(ctx context.Context, id int6 return err } defer func() { _ = tx.Rollback(context.Background()) }() - if err := auditmutation.LockActors(ctx, tx); err != nil { - return err - } - before, err := lockAPIKeyMetadata(ctx, tx, id, guard) - if err != nil { - return err - } - if _, err = tx.Exec(ctx, `DELETE FROM api_keys WHERE id=$1`, id); err != nil { - return err - } - audit, err := recordAPIKeyMutation(ctx, tx, before, nil) + audit, err := deleteAPIKeyTx(ctx, tx, id, guard) if err != nil { return err } @@ -203,6 +193,35 @@ func (r *APIKeyRepository) DeleteByAdminConditional(ctx context.Context, id int6 return nil } +// DeleteByAdminTx deletes any API key inside the caller's transaction, as +// DeleteByAdminConditional does with an Any precondition: ErrAPIKeyNotFound +// when the key is gone. The caller runs committed after tx commits, which +// publishes the audit entry, and never runs it otherwise. +func (r *APIKeyRepository) DeleteByAdminTx(ctx context.Context, tx pgx.Tx, id int64) (func(), error) { + audit, err := deleteAPIKeyTx(ctx, tx, id, APIKeyPrecondition{Any: true}) + if err != nil { + return nil, err + } + return func() { auditmutation.CommitMutation(ctx, audit) }, nil +} + +// deleteAPIKeyTx deletes the key and records its audit row in tx. The audit +// row's account locks come before the key row lock, the order an account +// deletion takes them in. +func deleteAPIKeyTx(ctx context.Context, tx pgx.Tx, id int64, guard APIKeyPrecondition) (*auditmutation.Entry, error) { + if err := auditmutation.LockActors(ctx, tx); err != nil { + return nil, err + } + before, err := lockAPIKeyMetadata(ctx, tx, id, guard) + if err != nil { + return nil, err + } + if _, err = tx.Exec(ctx, `DELETE FROM api_keys WHERE id=$1`, id); err != nil { + return nil, err + } + return recordAPIKeyMutation(ctx, tx, before, nil) +} + // apiKeyAuditValues is the API key audit allowlist: the key's configuration, // never the credential, its prefix or its usage. func apiKeyAuditValues(key *models.APIKeyMetadata) map[string]any { diff --git a/internal/auth/api_key_repository.go b/internal/auth/api_key_repository.go index d8a9bdd3ec..8a40aa9d9b 100644 --- a/internal/auth/api_key_repository.go +++ b/internal/auth/api_key_repository.go @@ -94,8 +94,7 @@ func (r *APIKeyRepository) Create(ctx context.Context, userID int, label string, // refused when CheckOwnerTarget refuses actorID acting on that account. Both // accounts stay share-locked, in id order as ownership transfers lock them, // until the key is inserted: a promotion or transfer that commits first is -// what the check sees, and a later promotion of the account, or transfer of -// ownership to it, deletes the key with the account's other keys. An unknown account passes the check and fails the +// what the check sees, and a later promotion of the account, or transfer of ownership to it, deletes the key with the account's other keys. An unknown account passes the check and fails the // insert, as it does with Create. func (r *APIKeyRepository) CreateAsActor(ctx context.Context, actorID, userID int, label string, scopes []string) (*models.APIKey, error) { tx, err := r.pool.Begin(ctx) @@ -107,19 +106,52 @@ func (r *APIKeyRepository) CreateAsActor(ctx context.Context, actorID, userID in defer cancel() _ = tx.Rollback(cleanupCtx) }() - // The audit row's accounts, an impersonator included, join that id order. + created, committed, err := r.CreateAsActorTx(ctx, tx, actorID, userID, label, scopes) + if err != nil { + return nil, err + } + if err := tx.Commit(ctx); err != nil { + return nil, fmt.Errorf("committing api key creation: %w", err) + } + committed() + return created, nil +} + +// CreateAsActorTx is CreateAsActor inside the caller's transaction: the key +// exists only once tx commits. The caller runs committed after that commit +// succeeds, which publishes the audit entry, and never runs it otherwise. +func (r *APIKeyRepository) CreateAsActorTx(ctx context.Context, tx pgx.Tx, actorID, userID int, label string, scopes []string) (*models.APIKey, func(), error) { + actor, target, err := lockAPIKeyAccounts(ctx, tx, actorID, userID) + if err != nil { + return nil, nil, err + } + if err := CheckOwnerTarget(actor, target); err != nil { + return nil, nil, err + } + created, audit, err := insertAPIKeyTx(ctx, tx, userID, label, scopes) + if err != nil { + return nil, nil, err + } + return created, func() { auditmutation.CommitMutation(ctx, audit) }, nil +} + +// lockAPIKeyAccounts share-locks the actor, the key's account and the audit +// row's accounts (an impersonator included) in one id order, and returns +// what CheckOwnerTarget needs. Account locks come before any key row lock, +// the order an account deletion takes them in. +func lockAPIKeyAccounts(ctx context.Context, tx pgx.Tx, actorID, userID int) (OwnerActor, *models.User, error) { rows, err := tx.Query(ctx, `SELECT id, role, is_owner FROM users WHERE id = ANY($1) ORDER BY id FOR SHARE`, append([]int{actorID, userID}, auditmutation.ActorIDs(ctx)...)) if err != nil { - return nil, fmt.Errorf("locking api key accounts: %w", err) + return OwnerActor{}, nil, fmt.Errorf("locking api key accounts: %w", err) } + defer rows.Close() actor := OwnerActor{ID: actorID} var target *models.User for rows.Next() { var user models.User if err := rows.Scan(&user.ID, &user.Role, &user.IsOwner); err != nil { - rows.Close() - return nil, fmt.Errorf("scanning api key account: %w", err) + return OwnerActor{}, nil, fmt.Errorf("scanning api key account: %w", err) } if user.ID == actorID { actor.IsOwner = user.IsOwner @@ -128,22 +160,33 @@ func (r *APIKeyRepository) CreateAsActor(ctx context.Context, actorID, userID in target = &user } } - rows.Close() if err := rows.Err(); err != nil { - return nil, fmt.Errorf("locking api key accounts: %w", err) - } - if err := CheckOwnerTarget(actor, target); err != nil { - return nil, err + return OwnerActor{}, nil, fmt.Errorf("locking api key accounts: %w", err) } - return insertAPIKey(ctx, tx, userID, label, scopes) + return actor, target, nil } // insertAPIKey inserts the key and its audit row in tx and commits tx. func insertAPIKey(ctx context.Context, tx pgx.Tx, userID int, label string, scopes []string) (*models.APIKey, error) { - key, err := generateAPIKey() + created, audit, err := insertAPIKeyTx(ctx, tx, userID, label, scopes) if err != nil { return nil, err } + if err := tx.Commit(ctx); err != nil { + return nil, fmt.Errorf("committing api key creation: %w", err) + } + auditmutation.CommitMutation(ctx, audit) + return created, nil +} + +// insertAPIKeyTx inserts the key and its audit row in tx without committing. +// The returned key carries its bearer, disclosed this once: no ordinary row +// projection carries it. +func insertAPIKeyTx(ctx context.Context, tx pgx.Tx, userID int, label string, scopes []string) (*models.APIKey, *auditmutation.Entry, error) { + key, err := generateAPIKey() + if err != nil { + return nil, nil, err + } if scopes == nil { scopes = []string{} } @@ -154,20 +197,15 @@ func insertAPIKey(ctx context.Context, tx pgx.Tx, userID int, label string, scop created, err := scanAPIKey(tx.QueryRow(ctx, query, userID, label, HashLinkToken(key), key[:11], scopes)) if err != nil { - return nil, err + return nil, nil, err } audit, err := recordAPIKeyMutation(ctx, tx, nil, &models.APIKeyMetadata{ID: created.ID, UserID: created.UserID, Label: created.Label, RateTier: created.RateTier, Scopes: created.Scopes}) if err != nil { - return nil, err + return nil, nil, err } - if err := tx.Commit(ctx); err != nil { - return nil, fmt.Errorf("committing api key creation: %w", err) - } - auditmutation.CommitMutation(ctx, audit) - // The bearer is disclosed once. No ordinary row projection carries it. created.Key = key - return created, nil + return created, audit, nil } // GetByKey looks up an API key by its full key string (including "sa_" prefix). diff --git a/internal/auth/plugin_host_api_keys.go b/internal/auth/plugin_host_api_keys.go new file mode 100644 index 0000000000..e276b6ab9d --- /dev/null +++ b/internal/auth/plugin_host_api_keys.go @@ -0,0 +1,58 @@ +package auth + +import ( + "context" + "errors" + + "github.com/jackc/pgx/v5" + + "github.com/Silo-Server/silo-server/internal/plugins" +) + +// PluginHostAPIKeys issues the scoped API keys plugins call the host API +// with. It is the plugins.HostAPIKeyIssuer of plugins.PermissionService. +type PluginHostAPIKeys struct { + Keys *APIKeyRepository +} + +var _ plugins.HostAPIKeyIssuer = PluginHostAPIKeys{} + +// KnownScopes is the API key scope catalog. +func (PluginHostAPIKeys) KnownScopes() []string { return ValidAPIKeyScopes() } + +// LockAccounts share-locks, in tx, the accounts IssueTx and RevokeTx lock +// for actorID: the actor and the audit row's accounts, in id order. +func (PluginHostAPIKeys) LockAccounts(ctx context.Context, tx pgx.Tx, actorID int) error { + _, _, err := lockAPIKeyAccounts(ctx, tx, actorID, actorID) + return err +} + +// IssueTx mints, in tx, a key with exactly scopes on actorID's own account. +// Like any key, it acts as that account: a key whose owner loses the admin +// role stops reaching admin routes, and one whose owner is deleted is +// deleted with it. The caller runs committed once tx commits. +func (k PluginHostAPIKeys) IssueTx(ctx context.Context, tx pgx.Tx, actorID int, label string, scopes []string) (int64, string, func(), error) { + normalized, err := NormalizeAPIKeyScopes(scopes) + if err != nil { + return 0, "", nil, err + } + if len(normalized) == 0 { + // An unscoped key is full access as its owner; a plugin never gets one. + return 0, "", nil, errors.New("a plugin host API key needs at least one scope") + } + key, committed, err := k.Keys.CreateAsActorTx(ctx, tx, actorID, actorID, label, normalized) + if err != nil { + return 0, "", nil, err + } + return key.ID, key.Key, committed, nil +} + +// RevokeTx deletes the key in tx. A key already deleted is not an error. The +// caller runs committed once tx commits. +func (k PluginHostAPIKeys) RevokeTx(ctx context.Context, tx pgx.Tx, id int64) (func(), error) { + committed, err := k.Keys.DeleteByAdminTx(ctx, tx, id) + if errors.Is(err, ErrAPIKeyNotFound) { + return func() {}, nil + } + return committed, err +} diff --git a/internal/backup/backup_postgres_test.go b/internal/backup/backup_postgres_test.go index 1953460384..b74141afab 100644 --- a/internal/backup/backup_postgres_test.go +++ b/internal/backup/backup_postgres_test.go @@ -496,6 +496,7 @@ func checkCredentials(t *testing.T, loader PGLoader, pool *pgxpool.Pool, dsn, in checkCarryAuthority(t, loader, pool, dsn, into, restored, userID, keptID, liveKeys) checkCarryInvitation(t, loader, pool, dsn, into, restored, "invite-"+suffix) checkCarryAutoProvision(t, loader, pool, dsn, into, restored) + checkCarryPluginGrant(t, loader, pool, dsn, into, restored, userID, newUser) checkOutboundConnections(t, loader, pool, dsn, into, restored, userID) checkInterruptedWork(t, loader, pool, dsn, into, restored, userID) checkOutboundSettings(t, loader, pool, dsn, into, restored) @@ -697,8 +698,9 @@ func checkStricterFlags(t *testing.T, loader PGLoader, pool *pgxpool.Pool, dsn, // checkLiveReleasesAndNodes: what the server launches or routes clients // through is the live server's. A plugin both have runs the live release, -// archive and capabilities included; one whose id is another plugin here -// comes back off and is reported; a stream node removed since the backup +// archive, capabilities, and requested host API scopes included; one whose +// id is another plugin here comes back off and is reported, without the +// other plugin's permission grant; a stream node removed since the backup // stays removed. func checkLiveReleasesAndNodes(t *testing.T, loader PGLoader, pool *pgxpool.Pool, dsn, into string, restored *pgxpool.Pool) { t.Helper() @@ -728,21 +730,34 @@ func checkLiveReleasesAndNodes(t *testing.T, loader PGLoader, pool *pgxpool.Pool install(restored, same, "release-plugin", "1.0.0", "backup") install(pool, other, "live-plugin", "1.0.0", "live") install(restored, other, "backup-plugin", "1.0.0", "backup") + exec(pool, `UPDATE plugin_installations SET host_api_scopes = '{library.read}' WHERE id = $1`, same) + // The credential carry gave each installation the live grant of its id, + // including the one that is another plugin here. + for _, id := range []int64{same, other} { + exec(restored, `INSERT INTO plugin_permission_grants (plugin_installation_id, approved_event_access) VALUES ($1, '{user_data}')`, id) + } off, err := loader.CarryPluginReleases(ctx, into, dsn) if err != nil { t.Fatal(err) } var version, checksum, capability string + var scopes []string var enabled bool - if err := restored.QueryRow(ctx, `SELECT i.version, a.checksum, c.capability_id FROM plugin_installations i + if err := restored.QueryRow(ctx, `SELECT i.version, a.checksum, c.capability_id, i.host_api_scopes FROM plugin_installations i JOIN plugin_archives a ON a.plugin_installation_id = i.id JOIN plugin_capabilities c ON c.plugin_installation_id = i.id - WHERE i.id = $1`, same).Scan(&version, &checksum, &capability); err != nil || version != "2.0.0" || checksum != "live" || capability != "2.0.0" { - t.Fatalf("a plugin both have runs %s %s %s (%v), want the live release", version, checksum, capability, err) + WHERE i.id = $1`, same).Scan(&version, &checksum, &capability, &scopes); err != nil || version != "2.0.0" || checksum != "live" || capability != "2.0.0" || + !slices.Equal(scopes, []string{"library.read"}) { + t.Fatalf("a plugin both have runs %s %s %s asking for %v (%v), want the live release", version, checksum, capability, scopes, err) } if err := restored.QueryRow(ctx, `SELECT enabled FROM plugin_installations WHERE id = $1`, other).Scan(&enabled); err != nil || enabled || !slices.ContainsFunc(off, func(s string) bool { return strings.Contains(s, "backup-plugin") }) { t.Fatalf("an installation of another plugin here: enabled %v (%v), reported %v; want it off and reported", enabled, err, off) } + var grants []int64 + if err := restored.QueryRow(ctx, `SELECT coalesce(array_agg(plugin_installation_id), '{}') FROM plugin_permission_grants WHERE plugin_installation_id = ANY($1)`, + []int64{same, other}).Scan(&grants); err != nil || !slices.Equal(grants, []int64{same}) { + t.Fatalf("grants after the release carry: %v (%v); want only the plugin both have keeping its own", grants, err) + } // Reinstalled since the backup from a catalog added since: the live // release names a catalog the backup does not have. var catalogID int64 @@ -1003,6 +1018,71 @@ func checkCarryAutoProvision(t *testing.T, loader PGLoader, pool *pgxpool.Pool, } } +// checkCarryPluginGrant: a plugin's permission grant is the live one, with +// the host API key it names. Where the carry drops that key (its owner is +// not in the backup) the grant keeps its approvals without a key, so the +// plugin waits for approval, and is reported; an approver the backup lacks +// is cleared rather than failing the restore on its foreign key. +func checkCarryPluginGrant(t *testing.T, loader PGLoader, pool *pgxpool.Pool, dsn, into string, restored *pgxpool.Pool, userID, newUser int64) { + t.Helper() + ctx := t.Context() + var installation int64 + if err := pool.QueryRow(ctx, `INSERT INTO plugin_installations (plugin_id, version, install_path, enabled) VALUES ('granted-plugin', '1.0.0', '/plugins/g', true) RETURNING id`).Scan(&installation); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + _, _ = pool.Exec(context.Background(), `DELETE FROM plugin_installations WHERE id = $1`, installation) + }) + if _, err := restored.Exec(ctx, `INSERT INTO plugin_installations (id, plugin_id, version, install_path, enabled) VALUES ($1, 'granted-plugin', '1.0.0', '/plugins/g', true)`, installation); err != nil { + t.Fatal(err) + } + key := func(owner int64) int64 { + t.Helper() + var id int64 + if err := pool.QueryRow(ctx, `INSERT INTO api_keys (user_id, label, key_hash) VALUES ($1, 'Plugin: granted-plugin', encode(sha256(convert_to($2, 'UTF8')), 'hex')) RETURNING id`, + owner, "plugin-"+randomHex(t, 4)).Scan(&id); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _, _ = pool.Exec(context.Background(), `DELETE FROM api_keys WHERE id = $1`, id) }) + return id + } + grant := func(approver, keyID int64) { + t.Helper() + if _, err := pool.Exec(ctx, `INSERT INTO plugin_permission_grants (plugin_installation_id, approved_event_access, approved_host_api_scopes, approved_by_user_id, approved_at, api_key_id, api_key_ciphertext) + VALUES ($1, '{user_data}', '{library.read}', $2, now(), $3, 'enc:v1:sealed') + ON CONFLICT (plugin_installation_id) DO UPDATE SET approved_by_user_id = EXCLUDED.approved_by_user_id, api_key_id = EXCLUDED.api_key_id`, installation, approver, keyID); err != nil { + t.Fatal(err) + } + } + read := func() (access []string, approver, keyID *int64, sealed *string) { + t.Helper() + if err := restored.QueryRow(ctx, `SELECT approved_event_access, approved_by_user_id, api_key_id, api_key_ciphertext FROM plugin_permission_grants WHERE plugin_installation_id = $1`, + installation).Scan(&access, &approver, &keyID, &sealed); err != nil { + t.Fatal(err) + } + return access, approver, keyID, sealed + } + report := fmt.Sprintf("permissions of plugin installation %d: ", installation) + reported := func(c CarriedCredentials) bool { + return slices.ContainsFunc(c.Limited, func(s string) bool { return strings.HasPrefix(s, report) }) + } + + kept := key(userID) + grant(userID, kept) + carried, err := loader.CarryCredentials(ctx, into, dsn) + if access, approver, keyID, sealed := read(); err != nil || reported(carried) || !slices.Equal(access, []string{"user_data"}) || + approver == nil || *approver != userID || keyID == nil || *keyID != kept || sealed == nil { + t.Fatalf("carried %+v (%v): grant %v by %v, key %v sealed %v; want the live grant with its key", carried, err, access, approver, keyID, sealed) + } + + grant(newUser, key(newUser)) + carried, err = loader.CarryCredentials(ctx, into, dsn) + if access, approver, keyID, sealed := read(); err != nil || !reported(carried) || !slices.Equal(access, []string{"user_data"}) || + approver != nil || keyID != nil || sealed != nil { + t.Fatalf("carried %+v (%v): grant %v by %v, key %v sealed %v; want the approvals kept without the dropped key or the missing approver", carried, err, access, approver, keyID, sealed) + } +} + // checkCarryInvitation: a pending invitation is dropped when the account it // would create gets more under the restored data than live (its default // group had no stream cap in the backup and has one now), and kept when the diff --git a/internal/backup/credentials.go b/internal/backup/credentials.go index 89e2b0b4f1..2fc8550661 100644 --- a/internal/backup/credentials.go +++ b/internal/backup/credentials.go @@ -94,6 +94,9 @@ type carrySpec struct { // limit, when set, turns a switch off on a carried row instead of // dropping it. limit *carryLimit + // detach clears references to rows the restored data may not have, + // instead of dropping the row or failing on its foreign key. + detach []carryDetach } // carryLimit carries a row with column false where keep, over the live row @@ -102,6 +105,14 @@ type carryLimit struct { column, keep, why string } +// carryDetach carries a row with columns NULL where keep, over the live row +// r, does not hold. When why is set, a row whose first column it clears is +// reported with why. +type carryDetach struct { + columns []string + keep, why string +} + // everyRow is a carrySpec.credential that selects every row. const everyRow = "true" @@ -314,6 +325,20 @@ var secretTables = []secretTable{ key: "plugin_installation_id, host_scope, state_key", same: []string{columnInstallation, "host_scope", "state_key"}, credential: everyRow, owned: pluginInstalled, describe: `format('state %L of plugin installation %s', r.state_key, r.plugin_installation_id)`, }}, + // What an administrator approved for a plugin, with the host API key it + // was issued (sealed). It follows api_keys: a grant names a key only + // where the carry kept that key, and otherwise keeps its approvals + // without one, which leaves the plugin waiting for approval as when the + // key is deleted on the API keys page. + {name: "plugin_permission_grants", handling: secretCarried, why: "plugin permissions and the host API key each was issued", carry: &carrySpec{ + key: columnInstallation, same: []string{columnInstallation}, credential: everyRow, owned: pluginInstalled, + describe: `format('permissions of plugin installation %s', r.plugin_installation_id)`, + detach: []carryDetach{ + {columns: []string{"api_key_id", "api_key_ciphertext"}, keep: `EXISTS (SELECT 1 FROM api_keys k WHERE k.id = r.api_key_id)`, + why: "its host API key was not kept; approve the plugin's permissions again"}, + {columns: []string{"approved_by_user_id"}, keep: `EXISTS (SELECT 1 FROM users u WHERE u.id = r.approved_by_user_id)`}, + }, + }}, // Stream nodes are what clients' requests are routed through, some with // the client's bearer: a node removed since the backup stays removed. {name: "stream_nodes", handling: secretCarried, why: "stream nodes, which clients' requests are routed through", carry: &carrySpec{ @@ -385,7 +410,7 @@ func leftOutTables() []string { // carriedKinds is what the restore output calls the carried tables. const carriedKinds = "API keys, pending invitations, invite codes, autoscan webhook tokens, audiobook RSS feed links, " + "Plex and Jellyfin webhook sync secrets, external sign-in links and providers, watch-provider connections, " + - "plugin configuration and state, and notification destinations " + + "plugin configuration, state, and permissions, and notification destinations " + "(push registrations, webhooks, email addresses, Discord links, server channels)" // CarriedCredentials is what DatabaseLoader.CarryCredentials did. @@ -737,6 +762,11 @@ func (t secretTable) carryInto(ctx context.Context, tx pgx.Tx, live string, resu values := make([]string, len(columns)) for i, col := range columns { values[i] = "r." + col + for _, d := range c.detach { + if slices.Contains(d.columns, col) { + values[i] = fmt.Sprintf("CASE WHEN %s THEN r.%s END", d.keep, col) + } + } if l := c.limit; l != nil && col == l.column { values[i] = fmt.Sprintf("(r.%s AND (%s))", col, l.keep) limited, err := collectStrings(ctx, tx, fmt.Sprintf(`SELECT %s FROM %s WHERE (%s) AND r.%s AND NOT (%s)`, c.describe, rows, c.owned, col, l.keep), live) @@ -748,6 +778,19 @@ func (t secretTable) carryInto(ctx context.Context, tx pgx.Tx, live string, resu } } } + for _, d := range c.detach { + if d.why == "" { + continue + } + detached, err := collectStrings(ctx, tx, fmt.Sprintf(`SELECT %s FROM %s WHERE (%s) AND r.%s IS NOT NULL AND NOT (%s)`, + c.describe, rows, c.owned, d.columns[0], d.keep), live) + if err != nil { + return err + } + for _, row := range detached { + result.Limited = append(result.Limited, row+": "+d.why) + } + } tag, err := tx.Exec(ctx, fmt.Sprintf(`INSERT INTO %s (%s) OVERRIDING SYSTEM VALUE SELECT %s FROM %s WHERE %s ON CONFLICT (%s) DO UPDATE SET %s`, diff --git a/internal/backup/plugin_releases.go b/internal/backup/plugin_releases.go index 4637c6da0d..c9710ef0f6 100644 --- a/internal/backup/plugin_releases.go +++ b/internal/backup/plugin_releases.go @@ -5,6 +5,7 @@ import ( "errors" "fmt" "io" + "slices" "strings" "github.com/jackc/pgx/v5" @@ -15,15 +16,22 @@ import ( // besides its id, plugin, and switch: which release it runs and where. var pluginReleaseColumns = []string{"repository_id", "version", "install_path", "update_policy", "available_version", "kind", "runtime_generation"} +// pluginReleaseColumnsSince are release columns a backup's older schema may +// lack, copied only where the restored schema has them. Without them the +// migration adds the column empty and, at the next start, +// EnsurePermissionGrants records the scopes from the stored manifest. +var pluginReleaseColumnsSince = []string{"host_api_scopes"} + // CarryPluginReleases gives each plugin installation of the restored // database (dbURL) that the live server (liveURL) has, by id and plugin, // the live release: its row's release columns, its stored archive, and its // capabilities, so a release replaced since the backup is never launched // again. An installation of the same id but another plugin, and every // installation when liveURL is "" (another deployment, or a separate -// restore), is turned off and reported; one only the backup has is turned -// off by the stricter switches (stricterFlags). It returns the -// installations it turned off here. +// restore), is turned off and reported, and loses the permission grant the +// credential carry gave it from the live installation with its id; one only +// the backup has is turned off by the stricter switches (stricterFlags). It +// returns the installations it turned off here. func (l PGLoader) CarryPluginReleases(ctx context.Context, dbURL, liveURL string) ([]string, error) { conn, err := pgx.Connect(ctx, dbURL) if err != nil { @@ -43,6 +51,20 @@ func (l PGLoader) CarryPluginReleases(ctx context.Context, dbURL, liveURL string if err != nil { return err } + columns, err := tableColumns(ctx, tx, "plugin_installations") + if err != nil { + return err + } + release := slices.Clone(pluginReleaseColumns) + for _, col := range pluginReleaseColumnsSince { + if slices.Contains(columns, col) { + release = append(release, col) + } + } + var grants bool + if err := tx.QueryRow(ctx, `SELECT to_regclass('plugin_permission_grants') IS NOT NULL`).Scan(&grants); err != nil { + return err + } for id, plugin := range restored { matched := false if live != nil { @@ -57,7 +79,7 @@ func (l PGLoader) CarryPluginReleases(ctx context.Context, dbURL, liveURL string matched = livePlugin == plugin } if matched { - if err := copyPluginRelease(ctx, live, tx, id); err != nil { + if err := copyPluginRelease(ctx, live, tx, id, release); err != nil { return fmt.Errorf("plugin installation %d: %w", id, err) } continue @@ -65,6 +87,13 @@ func (l PGLoader) CarryPluginReleases(ctx context.Context, dbURL, liveURL string if _, err := tx.Exec(ctx, `UPDATE plugin_installations SET enabled = false WHERE id = $1`, id); err != nil { return err } + // What was approved for another plugin is not this one's: it + // waits for approval once enabled, as a fresh install does. + if grants { + if _, err := tx.Exec(ctx, `DELETE FROM plugin_permission_grants WHERE plugin_installation_id = $1`, id); err != nil { + return err + } + } off = append(off, fmt.Sprintf("%s (installation %d)", plugin, id)) } return nil @@ -73,13 +102,14 @@ func (l PGLoader) CarryPluginReleases(ctx context.Context, dbURL, liveURL string } // copyPluginRelease writes the live installation id's release into tx: -// the release columns, the stored archive, and the capabilities. -func copyPluginRelease(ctx context.Context, live *pgx.Conn, tx pgx.Tx, id int64) error { - set := make([]string, len(pluginReleaseColumns)) - args := make([]any, 0, len(pluginReleaseColumns)+1) +// the release columns (release, which starts with pluginReleaseColumns), +// the stored archive, and the capabilities. +func copyPluginRelease(ctx context.Context, live *pgx.Conn, tx pgx.Tx, id int64, release []string) error { + set := make([]string, len(release)) + args := make([]any, 0, len(release)+1) args = append(args, id) - row := live.QueryRow(ctx, `SELECT `+strings.Join(pluginReleaseColumns, ", ")+` FROM plugin_installations WHERE id = $1`, id) - values := make([]any, len(pluginReleaseColumns)) + row := live.QueryRow(ctx, `SELECT `+strings.Join(release, ", ")+` FROM plugin_installations WHERE id = $1`, id) + values := make([]any, len(release)) ptrs := make([]any, len(values)) for i := range values { ptrs[i] = &values[i] @@ -87,7 +117,7 @@ func copyPluginRelease(ctx context.Context, live *pgx.Conn, tx pgx.Tx, id int64) if err := row.Scan(ptrs...); err != nil { return err } - for i, col := range pluginReleaseColumns { + for i, col := range release { set[i] = fmt.Sprintf("%s = $%d", col, i+2) args = append(args, values[i]) } diff --git a/internal/cache/observed_bus.go b/internal/cache/observed_bus.go deleted file mode 100644 index 8866c7dc70..0000000000 --- a/internal/cache/observed_bus.go +++ /dev/null @@ -1,45 +0,0 @@ -package cache - -import ( - "context" - "sync/atomic" -) - -// PublishObserver is called with every event this process publishes. -type PublishObserver func(channel string, event Event) - -// ObservedEventBus is an EventBus that also hands every event published -// through it to an observer, whether or not Redis carries it to other nodes. -// Subscribers on every node receive a published event, so a subscriber cannot -// tell which node produced it; the observer runs only on the producing node. -// It runs without Redis too, where the bus itself delivers nothing. -type ObservedEventBus struct { - EventBus - observer atomic.Pointer[PublishObserver] -} - -// NewObservedEventBus wraps bus. The observer is set later with -// ObservePublishes; events published before then are not observed. -func NewObservedEventBus(bus EventBus) *ObservedEventBus { - return &ObservedEventBus{EventBus: bus} -} - -// ObservePublishes sets the observer, replacing any earlier one. The observer -// runs on the publisher's goroutine and must not block. -func (b *ObservedEventBus) ObservePublishes(observer PublishObserver) { - if observer == nil { - b.observer.Store(nil) - return - } - b.observer.Store(&observer) -} - -// Publish publishes event on the wrapped bus, then hands it to the observer. -// The observer sees the event even when the bus fails to publish it. -func (b *ObservedEventBus) Publish(ctx context.Context, channel string, event Event) error { - err := b.EventBus.Publish(ctx, channel, event) - if observer := b.observer.Load(); observer != nil { - (*observer)(channel, event) - } - return err -} diff --git a/internal/cache/observed_bus_test.go b/internal/cache/observed_bus_test.go deleted file mode 100644 index 68ce57bb34..0000000000 --- a/internal/cache/observed_bus_test.go +++ /dev/null @@ -1,28 +0,0 @@ -package cache - -import ( - "context" - "errors" - "testing" -) - -type failingBus struct{ *NoopEventBus } - -func (failingBus) Publish(context.Context, string, Event) error { return errors.New("redis down") } - -func TestObservedEventBusObservesEveryPublish(t *testing.T) { - ctx := context.Background() - bus := NewObservedEventBus(failingBus{&NoopEventBus{}}) - if err := bus.Publish(ctx, ChannelCatalog, Event{Type: EventScanComplete}); err == nil { - t.Fatal("Publish hid the bus's error") - } - - var seen []string - bus.ObservePublishes(func(channel string, event Event) { seen = append(seen, channel+" "+event.Type) }) - if err := bus.Publish(ctx, ChannelAdmin, Event{Type: EventSettingsChanged}); err == nil { - t.Fatal("Publish hid the bus's error") - } - if len(seen) != 1 || seen[0] != ChannelAdmin+" "+EventSettingsChanged { - t.Fatalf("observed %v, want the one event published after ObservePublishes, even though the bus failed", seen) - } -} diff --git a/internal/contractledger/ledger_test.go b/internal/contractledger/ledger_test.go index 8e7dcdb747..5322949712 100644 --- a/internal/contractledger/ledger_test.go +++ b/internal/contractledger/ledger_test.go @@ -623,14 +623,15 @@ func TestConcurrencyMarkingIsRestricted(t *testing.T) { // is empty today; the reconcile test refuses an unmapped guarded operation // that is not listed here. var guardedWithoutLegacyRow = map[string]string{ - "updateRequestRoute": "V2-only request routing rule: the rule's revision from request_editor_revision_seq is its ETag.", - "deleteRequestRoute": "V2-only request routing rule: deletion is guarded by the rule's revision.", - "updateAdminRequestGroupLimit": "V2-only access-group request limit: the limit's revision from request_editor_revision_seq is its ETag; a group with none saved is revision zero.", - "updateRequestRouting": "V2-only request routing mode (Standard or Advanced): the mode's revision from request_editor_revision_seq is its ETag.", - "updateRequestDiscoverLayout": "V2-only Requests Discover layout: the layout's revision from request_editor_revision_seq is its ETag; the default layout, with none stored, is revision zero.", - "resetRequestDiscoverLayout": "V2-only return to the default Discover layout: guarded by the stored layout's revision.", - "setStoredSubtitleTiming": "V2-only stored subtitle timing correction: guarded by the viewer subtitle validator, whose revision every subtitle row update bumps.", - "setSubtitleTiming": "V2-only timing correction of a stored subtitle or a sidecar: guarded by a validator over the stored row's revision, or the sidecar's bytes and its correction's revision.", + "updateRequestRoute": "V2-only request routing rule: the rule's revision from request_editor_revision_seq is its ETag.", + "deleteRequestRoute": "V2-only request routing rule: deletion is guarded by the rule's revision.", + "updateAdminRequestGroupLimit": "V2-only access-group request limit: the limit's revision from request_editor_revision_seq is its ETag; a group with none saved is revision zero.", + "updateRequestRouting": "V2-only request routing mode (Standard or Advanced): the mode's revision from request_editor_revision_seq is its ETag.", + "updateRequestDiscoverLayout": "V2-only Requests Discover layout: the layout's revision from request_editor_revision_seq is its ETag; the default layout, with none stored, is revision zero.", + "resetRequestDiscoverLayout": "V2-only return to the default Discover layout: guarded by the stored layout's revision.", + "setStoredSubtitleTiming": "V2-only stored subtitle timing correction: guarded by the viewer subtitle validator, whose revision every subtitle row update bumps.", + "setSubtitleTiming": "V2-only timing correction of a stored subtitle or a sidecar: guarded by a validator over the stored row's revision, or the sidecar's bytes and its correction's revision.", + "approveAdminPluginInstallationPermissions": "V2-only plugin permission approval: guarded by a digest of the permissions representation the administrator read, so an update that asks for more between the read and the approval is 412.", } // TestGuardedOperationsAreMarkedIfMatch reconciles the v2 registry with the @@ -1081,11 +1082,12 @@ var mutationWithoutLegacyRow = map[string]string{ "queryWatchTogetherMemberState": "V2-only POST-shaped read: the content id set (up to 200) exceeds what a query string carries. It changes no state; repeating it returns the current classification.", "resetAdminRecommendationEmbeddings": "V2-only embeddings reset: v1 had no way to clear the embedding lock. A replay right after success deletes nothing more, but a later replay also deletes what the embedding job built since, so it is non-retryable like the recommendation job triggers.", - "replaceAdminUserProfileSectionOverrides": "V2-only administrator edit of one profile's page layout: v1 could only change the caller's own profile. It runs the same full-replacement write as replaceProfileSectionOverrides, which is non-retryable because a save can start a trending refresh.", - "resetAdminUserProfileSectionOverrides": "V2-only administrator reset of one profile's page layout: v1 reset only the caller's own profile or every profile at once. It runs the same delete as resetProfileSectionOverrides and is non-retryable like it.", - "createAdminUserProfile": "V2-only administrator creation of a profile on any account: v1 created profiles only on the caller's own household. It runs the same create as createProfile, which is non-retryable because a retry after a lost response makes a second profile or answers 409.", - "updateAdminUserProfile": "V2-only administrator edit of any account's profile, including setting or removing its PIN: v1 edited profiles only on the caller's own household. It runs the same write as updateProfile and is non-retryable like it: a retried PIN advances the profile's PIN revision again.", - "deleteAdminUserProfile": "V2-only administrator deletion of any account's profile: v1 deleted profiles only on the caller's own household. It runs the same delete as deleteProfile and is non-retryable like the other admin profile writes; a repeat answers 404.", + "replaceAdminUserProfileSectionOverrides": "V2-only administrator edit of one profile's page layout: v1 could only change the caller's own profile. It runs the same full-replacement write as replaceProfileSectionOverrides, which is non-retryable because a save can start a trending refresh.", + "resetAdminUserProfileSectionOverrides": "V2-only administrator reset of one profile's page layout: v1 reset only the caller's own profile or every profile at once. It runs the same delete as resetProfileSectionOverrides and is non-retryable like it.", + "createAdminUserProfile": "V2-only administrator creation of a profile on any account: v1 created profiles only on the caller's own household. It runs the same create as createProfile, which is non-retryable because a retry after a lost response makes a second profile or answers 409.", + "updateAdminUserProfile": "V2-only administrator edit of any account's profile, including setting or removing its PIN: v1 edited profiles only on the caller's own household. It runs the same write as updateProfile and is non-retryable like it: a retried PIN advances the profile's PIN revision again.", + "deleteAdminUserProfile": "V2-only administrator deletion of any account's profile: v1 deleted profiles only on the caller's own household. It runs the same delete as deleteProfile and is non-retryable like the other admin profile writes; a repeat answers 404.", + "approveAdminPluginInstallationPermissions": "V2-only approval of a plugin's event access and host API scopes (v1 is frozen). It requires If-Match; a replay with the same tag after a lost response is 412 when the first attempt changed the representation, and a repeat with a fresh tag keeps a usable key whose scopes already match, so it converges on one grant and one key.", } // retrySafetyMismatches compares every operation the v2 registry declares diff --git a/internal/events/hub.go b/internal/events/hub.go index 59015efe7c..517248e242 100644 --- a/internal/events/hub.go +++ b/internal/events/hub.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "sync" + "sync/atomic" "time" "github.com/Silo-Server/silo-server/internal/cache" @@ -21,6 +22,9 @@ type Hub struct { sourceID string eventBus cache.EventBus drops map[EventChannel]uint64 + // pluginSubscribers reports whether a plugin event has subscribers. It + // is nil until the plugin event dispatcher installs it. + pluginSubscribers atomic.Pointer[func(event string) bool] } func NewHub(sourceID string, eventBus cache.EventBus) *Hub { @@ -45,6 +49,26 @@ func (h *Hub) SourceID() string { return h.sourceID } +// SetPluginSubscribers installs the plugin event dispatcher's check for +// whether an event could have subscribers. +func (h *Hub) SetPluginSubscribers(check func(event string) bool) { + if h == nil { + return + } + h.pluginSubscribers.Store(&check) +} + +// PluginEventWanted reports whether a plugin event could have subscribers, so +// a publisher can skip building an envelope no plugin receives. It is true +// until the dispatcher installs its check. +func (h *Hub) PluginEventWanted(event string) bool { + if h == nil { + return false + } + check := h.pluginSubscribers.Load() + return check == nil || (*check)(event) +} + func (h *Hub) Subscribe() (<-chan Envelope, func()) { sub := &subscriber{ch: make(chan Envelope, 64)} h.mu.Lock() @@ -78,7 +102,10 @@ func (h *Hub) Publish(ctx context.Context, env Envelope) error { h.publishLocal(env) - if h.eventBus == nil { + // Plugin envelopes stay on this server: no websocket client receives the + // plugin channel, and each server's plugin event dispatcher stores only + // the envelopes published on it. + if h.eventBus == nil || env.Channel == ChannelPlugins { return nil } diff --git a/internal/pluginhost/host.go b/internal/pluginhost/host.go index 80fed2ecf3..95f4d7e8e9 100644 --- a/internal/pluginhost/host.go +++ b/internal/pluginhost/host.go @@ -58,6 +58,10 @@ type Config struct { // the host starts, revokes it when the process stops, and receives status // pushes. When nil, providers get no token and pushes are dropped. NetworkAccess NetworkAccessBroker + // HostAPICredentials answers GetHostAPICredential with the API key + // issued for the calling installation. When nil, the RPC is + // Unimplemented: proxy nodes issue no keys. + HostAPICredentials HostAPICredentialSource } type StartRequest struct { @@ -89,6 +93,7 @@ type Host struct { instanceState InstanceStateStore runtimeHostForStart func(context.Context) (HostInfoFunc, InstanceStateStore, error) networkAccess NetworkAccessBroker + hostAPICredentials HostAPICredentialSource mu sync.RWMutex instances map[int]*instance @@ -148,6 +153,7 @@ func NewHost(cfg Config) *Host { instanceState: cfg.InstanceState, runtimeHostForStart: cfg.RuntimeHostForStart, networkAccess: cfg.NetworkAccess, + hostAPICredentials: cfg.HostAPICredentials, instances: make(map[int]*instance), starting: make(map[int]chan struct{}), } @@ -541,7 +547,7 @@ func (h *Host) stopInstance(instance *instance) { // Skipped when no RuntimeHost services are configured. func (h *Host) bindRuntimeHost(ctx context.Context, sdkClient *sdkruntime.Client, pluginID string, installationID int, provider, ingressToken string, hostInfo HostInfoFunc, instanceState InstanceStateStore) error { if h.eventPublisher == nil && h.libraryLister == nil && h.catalogPresence == nil && h.installedPlugins == nil && h.globalConfigSetter == nil && - hostInfo == nil && instanceState == nil && h.networkAccess == nil { + hostInfo == nil && instanceState == nil && h.networkAccess == nil && h.hostAPICredentials == nil { return nil } @@ -564,6 +570,7 @@ func (h *Host) bindRuntimeHost(ctx context.Context, sdkClient *sdkruntime.Client HostInfo: hostInfo, InstanceState: instanceState, NetworkAccess: h.networkAccess, + HostAPICredentials: h.hostAPICredentials, Logger: h.logger, PluginID: pluginID, InstallationID: installationID, @@ -571,6 +578,9 @@ func (h *Host) bindRuntimeHost(ctx context.Context, sdkClient *sdkruntime.Client IngressToken: ingressToken, }) pluginv1.RegisterRuntimeHostServer(s, srv) + // The host API credential is its own service on the same + // connection, so RuntimeHost's generated interfaces stay unchanged. + pluginv1.RegisterHostAPICredentialsServer(s, srv) return s }) diff --git a/internal/pluginhost/host_api_credential.go b/internal/pluginhost/host_api_credential.go new file mode 100644 index 0000000000..97a2686527 --- /dev/null +++ b/internal/pluginhost/host_api_credential.go @@ -0,0 +1,26 @@ +package pluginhost + +import ( + "context" + "errors" +) + +// ErrHostAPINotGranted means an installation has no usable host API key: its +// manifest asks for no host_api_scopes, an administrator hasn't approved +// them, or the key was revoked. GetHostAPICredential answers it with +// FAILED_PRECONDITION and the wrapped message. +var ErrHostAPINotGranted = errors.New("no approved host API key") + +// HostAPICredential is the API key the host issued for one installation's +// approved host_api_scopes, and the scopes it carries. +type HostAPICredential struct { + Token string + Scopes []string +} + +// HostAPICredentialSource looks up the host API key issued to an +// installation. The installation is the calling process's, fixed by the host +// when it started the plugin, never one the plugin names. +type HostAPICredentialSource interface { + HostAPICredential(ctx context.Context, installationID int) (HostAPICredential, error) +} diff --git a/internal/pluginhost/host_api_credential_test.go b/internal/pluginhost/host_api_credential_test.go new file mode 100644 index 0000000000..b0de3f7df7 --- /dev/null +++ b/internal/pluginhost/host_api_credential_test.go @@ -0,0 +1,86 @@ +package pluginhost_test + +import ( + "context" + "fmt" + "testing" + + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + + "github.com/Silo-Server/silo-server/internal/pluginhost" +) + +// credentialStore holds one key per installation and records which +// installations were asked for. +type credentialStore struct { + keys map[int]pluginhost.HostAPICredential + asked []int +} + +func (s *credentialStore) HostAPICredential(_ context.Context, installationID int) (pluginhost.HostAPICredential, error) { + s.asked = append(s.asked, installationID) + credential, ok := s.keys[installationID] + if !ok { + return pluginhost.HostAPICredential{}, fmt.Errorf("%w: an administrator hasn't approved this plugin's host API scopes", pluginhost.ErrHostAPINotGranted) + } + return credential, nil +} + +// TestGetHostAPICredentialAnswersOnlyForTheCallingInstallation covers the +// RPC's authority: the installation is the one the host bound the process to, +// so a plugin only ever reads its own key; one with nothing approved, or a +// test run, gets FAILED_PRECONDITION; a host that issues no keys answers +// UNIMPLEMENTED. +func TestGetHostAPICredentialAnswersOnlyForTheCallingInstallation(t *testing.T) { + store := &credentialStore{keys: map[int]pluginhost.HostAPICredential{ + 5: {Token: "sa_five", Scopes: []string{"admin:monitor:read"}}, + 6: {Token: "sa_six", Scopes: []string{"admin:users"}}, + }} + hostInfo := func(context.Context) (pluginhost.HostInfo, error) { + return pluginhost.HostInfo{Listeners: []pluginhost.HostListener{{Name: pluginhost.ListenerAPI, Address: "127.0.0.1:8080"}}}, nil + } + call := func(installationID int, source pluginhost.HostAPICredentialSource) (*pluginv1.GetHostAPICredentialResponse, error) { + srv := pluginhost.NewRuntimeHostServerWithOptions(pluginhost.RuntimeHostOptions{ + PluginID: "silo.test", InstallationID: installationID, HostInfo: hostInfo, HostAPICredentials: source, + }) + return srv.GetHostAPICredential(context.Background(), &pluginv1.GetHostAPICredentialRequest{}) + } + + resp, err := call(5, store) + if err != nil { + t.Fatalf("installation 5: %v", err) + } + if resp.GetToken() != "sa_five" || len(resp.GetScopes()) != 1 || resp.GetScopes()[0] != "admin:monitor:read" || resp.GetBaseUrl() != "http://127.0.0.1:8080" { + t.Fatalf("installation 5 response = %+v", resp) + } + + for _, tc := range []struct { + name string + installationID int + source pluginhost.HostAPICredentialSource + want codes.Code + }{ + {"nothing approved", 7, store, codes.FailedPrecondition}, + {"test run of a plugin", -3, store, codes.FailedPrecondition}, + {"host without the dependency", 5, nil, codes.Unimplemented}, + } { + t.Run(tc.name, func(t *testing.T) { + resp, err := call(tc.installationID, tc.source) + if status.Code(err) != tc.want { + t.Fatalf("code = %v (%v), want %v", status.Code(err), err, tc.want) + } + if resp.GetToken() != "" { + t.Fatalf("a refused call returned a token") + } + }) + } + + for _, asked := range store.asked { + if asked != 5 && asked != 7 { + t.Fatalf("the source was asked for installation %d; only the bound installations may be looked up", asked) + } + } +} diff --git a/internal/pluginhost/runtime_host_server.go b/internal/pluginhost/runtime_host_server.go index 6543ba814f..2bd8a4f871 100644 --- a/internal/pluginhost/runtime_host_server.go +++ b/internal/pluginhost/runtime_host_server.go @@ -23,6 +23,20 @@ type EventPublisher interface { Publish(ctx context.Context, env events.Envelope) error } +// pluginEventGate is implemented by an EventPublisher that knows whether a +// plugin event has subscribers (*events.Hub does), so an event nobody +// subscribes to is not built or published. +type pluginEventGate interface { + PluginEventWanted(event string) bool +} + +// wantsEvent reports whether the publisher could deliver eventName to a +// subscriber. +func (s *RuntimeHostServer) wantsEvent(eventName string) bool { + gate, ok := s.publisher.(pluginEventGate) + return !ok || gate.PluginEventWanted(eventName) +} + // LibraryRecord is the wire shape for libraries returned to plugins. Mirrors // the proto Library message. type LibraryRecord struct { @@ -107,9 +121,10 @@ type RuntimeHostServer struct { configSetter GlobalConfigSetter installationID int - hostInfo HostInfoFunc - instanceState InstanceStateStore - networkAccess NetworkAccessBroker + hostInfo HostInfoFunc + instanceState InstanceStateStore + networkAccess NetworkAccessBroker + hostAPICredentials HostAPICredentialSource // ingressToken is the token issued to this process instance; pushes are // accepted only while it is current. ingressToken string @@ -129,6 +144,9 @@ type RuntimeHostOptions struct { HostInfo HostInfoFunc InstanceState InstanceStateStore NetworkAccess NetworkAccessBroker + // HostAPICredentials answers GetHostAPICredential. When nil, as on proxy + // nodes, the RPC is Unimplemented. + HostAPICredentials HostAPICredentialSource Logger hclog.Logger // EventRatePerSec caps PublishEvent; <= 0 takes DefaultPublishEventRatePerSec. EventRatePerSec int @@ -155,6 +173,7 @@ func NewRuntimeHostServerWithOptions(opts RuntimeHostOptions) *RuntimeHostServer s.hostInfo = opts.HostInfo s.instanceState = opts.InstanceState s.networkAccess = opts.NetworkAccess + s.hostAPICredentials = opts.HostAPICredentials s.provider = opts.NetworkAccessProvider s.ingressToken = opts.IngressToken s.logger = opts.Logger @@ -237,6 +256,10 @@ func (s *RuntimeHostServer) PublishEvent(ctx context.Context, req *pluginv1.Publ return nil, fmt.Errorf("server: event publisher not configured") } + prefixed := "plugin." + s.pluginID + "." + name + if !s.wantsEvent(prefixed) { + return &pluginv1.PublishEventResponse{}, nil + } var payload json.RawMessage if p := req.GetPayload(); p != nil { raw, err := p.MarshalJSON() @@ -246,7 +269,6 @@ func (s *RuntimeHostServer) PublishEvent(ctx context.Context, req *pluginv1.Publ payload = raw } - prefixed := "plugin." + s.pluginID + "." + name env := events.Envelope{ Channel: events.ChannelPlugins, Event: prefixed, @@ -279,6 +301,10 @@ func (s *RuntimeHostServer) PublishEventTo(ctx context.Context, req *pluginv1.Pu return nil, fmt.Errorf("server: event publisher not configured") } + prefixed := "plugin." + s.pluginID + "." + name + if !s.wantsEvent(prefixed) { + return &pluginv1.PublishEventToResponse{}, nil + } var payload json.RawMessage if p := req.GetPayload(); p != nil { raw, err := p.MarshalJSON() @@ -290,7 +316,7 @@ func (s *RuntimeHostServer) PublishEventTo(ctx context.Context, req *pluginv1.Pu env := events.Envelope{ Channel: events.ChannelPlugins, - Event: "plugin." + s.pluginID + "." + name, + Event: prefixed, Data: payload, TargetPluginID: targetPluginID, } @@ -414,10 +440,8 @@ func (s *RuntimeHostServer) GetHostInfo(ctx context.Context, _ *pluginv1.GetHost if resp.PublicBaseUrl != "" && info.PluginContentPrefix != "" && s.installationID > 0 { resp.PluginProxyBaseUrl = resp.PublicBaseUrl + info.PluginContentPrefix + "/plugins/" + strconv.Itoa(s.installationID) } + resp.InternalBaseUrl = internalBaseURL(info) for _, listener := range info.Listeners { - if listener.Name == ListenerAPI && listener.Address != "" { - resp.InternalBaseUrl = "http://" + listener.Address - } resp.Listeners = append(resp.Listeners, &pluginv1.HostListener{ Name: listener.Name, Address: listener.Address, @@ -432,6 +456,48 @@ func (s *RuntimeHostServer) GetHostInfo(ctx context.Context, _ *pluginv1.GetHost return resp, nil } +// internalBaseURL is the loopback base URL of the host's API listener, or +// empty when the host has none. +func internalBaseURL(info HostInfo) string { + for _, listener := range info.Listeners { + if listener.Name == ListenerAPI && listener.Address != "" { + return "http://" + listener.Address + } + } + return "" +} + +// GetHostAPICredential returns the API key the host issued for this +// installation's approved host_api_scopes, with the host's internal base URL. +// The installation is the one the host started this process for. A test run +// of a plugin, or an installation with nothing approved, gets +// FAILED_PRECONDITION; a host that issues no keys answers Unimplemented. +func (s *RuntimeHostServer) GetHostAPICredential(ctx context.Context, _ *pluginv1.GetHostAPICredentialRequest) (*pluginv1.GetHostAPICredentialResponse, error) { + if s.hostAPICredentials == nil { + return nil, status.Error(codes.Unimplemented, "this host does not issue host API credentials") + } + if s.installationID <= 0 { + return nil, status.Error(codes.FailedPrecondition, "a test run of a plugin has no host API key") + } + credential, err := s.hostAPICredentials.HostAPICredential(ctx, s.installationID) + if errors.Is(err, ErrHostAPINotGranted) { + return nil, status.Error(codes.FailedPrecondition, err.Error()) + } + if err != nil { + s.logger.Warn("host API credential lookup failed", "plugin_id", s.pluginID, "installation_id", s.installationID, "error", err) + return nil, status.Error(codes.Internal, "host API credential lookup failed") + } + resp := &pluginv1.GetHostAPICredentialResponse{Token: credential.Token, Scopes: credential.Scopes} + if s.hostInfo != nil { + info, err := s.hostInfo(ctx) + if err != nil { + return nil, fmt.Errorf("host info: %w", err) + } + resp.BaseUrl = internalBaseURL(info) + } + return resp, nil +} + // ReadInstanceState returns one key of the instance's private state. The // scope is fixed by the store the host configured for this process. func (s *RuntimeHostServer) ReadInstanceState(ctx context.Context, req *pluginv1.ReadInstanceStateRequest) (*pluginv1.ReadInstanceStateResponse, error) { diff --git a/internal/plugins/event_catalog_contract_test.go b/internal/plugins/event_catalog_contract_test.go new file mode 100644 index 0000000000..f897e0fc4b --- /dev/null +++ b/internal/plugins/event_catalog_contract_test.go @@ -0,0 +1,177 @@ +package plugins_test + +import ( + "context" + "encoding/json" + "testing" + "time" + + publicevents "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/events" + + "github.com/Silo-Server/silo-server/internal/apiv2" + "github.com/Silo-Server/silo-server/internal/cache" + evt "github.com/Silo-Server/silo-server/internal/events" + "github.com/Silo-Server/silo-server/internal/models" + "github.com/Silo-Server/silo-server/internal/notifications" + "github.com/Silo-Server/silo-server/internal/plugins" +) + +// TestEventCatalogMatchesProducers runs what each producer of a catalog event +// actually publishes through the dispatcher's projection into the SDK's +// public payload type, and checks the fields the producer set survive, IDs as +// strings. A producer that renames or retypes a field breaks the plugin +// contract; this catches it. Every catalog event needs a case, so an event +// added to the SDK catalog gets one too. +func TestEventCatalogMatchesProducers(t *testing.T) { + at := time.Date(2026, 11, 4, 10, 0, 0, 0, time.UTC) + season := 2 + libraryID := 3 + published := publishedByNotificationsHub(t) + + scan := func(status string) evt.Envelope { + return envelope("scan", mustJSON(t, evt.ScanRun{ID: "scan-1", LibraryID: 7, Mode: "full", Trigger: "manual", Status: status, StartedAt: &at, + Result: &evt.ScanRunResult{New: 3, Missing: 1}})) + } + session := envelope("session", mustJSON(t, apiv2.AdminPlaybackLifecycleEvent{SessionID: "s1", Seq: 4, At: apiv2.NewInstant(at), State: "playing", + Session: &apiv2.AdminPlaybackSession{SessionID: "s1", UserID: "7", Username: "josh", ProfileID: "p1", MediaTitle: "Heat", + StartedAt: apiv2.NewInstant(at), UpdatedAt: apiv2.NewInstant(at)}})) + stopped := envelope("session", mustJSON(t, apiv2.AdminPlaybackLifecycleEvent{SessionID: "s1", Seq: 5, At: apiv2.NewInstant(at), State: "stopped", + History: &apiv2.AdminPlaybackHistoryEntry{SessionID: "s1", UserID: "7", MediaTitle: "Heat", + StartedAt: apiv2.NewInstant(at), EndedAt: apiv2.NewInstant(at.Add(time.Hour))}})) + notification := envelope(publicevents.NotificationCreated, mustJSON(t, notifications.PayloadForRow(notifications.DeliveryRow{ + Delivery: notifications.Delivery{ID: "d1", Type: "episode.available", UserID: 7, ProfileID: "p1", LibraryID: &libraryID, + CreatedAt: at}, + SeriesTitle: "Severance", SeasonNumber: &season, + }))) + // The notifications dispatcher addresses the envelope to the account. + notification.UserID = 7 + + cases := map[string]struct { + env evt.Envelope + check func(payload any) bool + }{ + publicevents.CatalogLibraryChanged: {published[publicevents.CatalogLibraryChanged], func(p any) bool { + return p.(*publicevents.LibraryChanged).LibraryID == "7" && p.(*publicevents.LibraryChanged).New == 3 + }}, + publicevents.CatalogItemChanged: {published[publicevents.CatalogItemChanged], func(p any) bool { + item := p.(*publicevents.ItemChanged) + return item.LibraryID == "7" && item.ContentID == "c1" && item.Change == "artwork" + }}, + publicevents.SessionStarted: {session, sessionCheck("Heat")}, + publicevents.SessionPaused: {session, sessionCheck("Heat")}, + publicevents.SessionResumed: {session, sessionCheck("Heat")}, + publicevents.SessionStopped: {stopped, func(p any) bool { + history, err := p.(*publicevents.SessionEvent).DecodeHistory() + return err == nil && history != nil && history.MediaTitle == "Heat" && history.EndedAt.Equal(at.Add(time.Hour)) + }}, + publicevents.ScanStarted: {scan("running"), scanCheck}, + publicevents.ScanCompleted: {scan("completed"), scanCheck}, + publicevents.ScanFailed: {scan("failed"), scanCheck}, + publicevents.ScanCancelled: {scan("canceled"), scanCheck}, + // job.created comes from a job the server queued itself: no creator. + publicevents.JobCreated: {published[publicevents.JobCreated], func(p any) bool { + job := p.(*publicevents.JobEvent) + return job.ID == "j0" && job.CreatedByUserID == nil + }}, + publicevents.JobCompleted: {published[publicevents.JobFailed], jobCheck}, + publicevents.JobFailed: {published[publicevents.JobFailed], jobCheck}, + publicevents.JobCancelled: {published[publicevents.JobFailed], jobCheck}, + publicevents.NotificationCreated: {notification, func(p any) bool { + n := p.(*publicevents.Notification) + return n.ID == "d1" && n.UserID == "7" && n.ProfileID == "p1" && n.LibraryID != nil && *n.LibraryID == "3" && + n.SeriesTitle == "Severance" && n.SeasonNumber != nil && *n.SeasonNumber == 2 && n.CreatedAt.Equal(at) + }}, + } + + for _, definition := range publicevents.Catalog() { + tc, ok := cases[definition.Name] + if !ok { + t.Errorf("%s: no producer case; add one", definition.Name) + continue + } + if len(tc.env.Data) == 0 { + t.Errorf("%s: the producer published nothing", definition.Name) + continue + } + tc.env.Event = definition.Name + projected, err := plugins.PublicPayloadJSON(tc.env) + if err != nil { + t.Errorf("%s: %v", definition.Name, err) + continue + } + payload := definition.NewPayload() + if err := json.Unmarshal(projected, payload); err != nil || !tc.check(payload) { + t.Errorf("%s: projected payload %s lost the producer's fields (%v)", definition.Name, projected, err) + } + } +} + +func sessionCheck(title string) func(any) bool { + return func(p any) bool { + session, err := p.(*publicevents.SessionEvent).DecodeSession() + return err == nil && session != nil && session.MediaTitle == title && session.UserID == "7" && p.(*publicevents.SessionEvent).Seq > 0 + } +} + +func scanCheck(p any) bool { + scan := p.(*publicevents.ScanEvent) + return scan.LibraryID == "7" && scan.Result != nil && scan.Result.New == 3 && scan.StartedAt != nil +} + +func jobCheck(p any) bool { + job := p.(*publicevents.JobEvent) + return job.ID == "j1" && job.JobType == "library_refresh" && job.Status == "failed" && job.ErrorMessage == "boom" && + job.CreatedByUserID != nil && *job.CreatedByUserID == "9" +} + +func envelope(event string, data []byte) evt.Envelope { + return evt.Envelope{Event: event, Data: data} +} + +// publishedByNotificationsHub runs the catalog and job publishers that build +// their payloads internally and returns each envelope by event name. +func publishedByNotificationsHub(t *testing.T) map[string]evt.Envelope { + t.Helper() + ctx := context.Background() + hub := notifications.NewHub("api", &cache.NoopEventBus{}) + envelopes, unsubscribe := hub.EventsHub().Subscribe() + defer unsubscribe() + + if err := hub.PublishCatalogLibraryChanged(ctx, notifications.LibraryChangeEvent{LibraryID: 7, Reason: "scan", New: 3}); err != nil { + t.Fatal(err) + } + if err := hub.PublishCatalogItemChanged(ctx, notifications.MetadataUpdateEvent{LibraryID: 7, ContentID: "c1", Change: "artwork"}); err != nil { + t.Fatal(err) + } + now := time.Date(2026, 11, 4, 10, 0, 0, 0, time.UTC) + queued := &models.AdminJob{ID: "j0", JobType: "library_refresh", Status: "queued", RequestedAt: now, UpdatedAt: now} + if err := hub.PublishJob(ctx, notifications.TypeJobCreated, queued); err != nil { + t.Fatal(err) + } + failed := &models.AdminJob{ID: "j1", JobType: "library_refresh", Status: "failed", ErrorMessage: "boom", CreatedByUserID: 9, + RequestPayload: json.RawMessage(`{"library_id":7}`), RequestedAt: now, UpdatedAt: now} + if err := hub.PublishJob(ctx, notifications.TypeJobFailed, failed); err != nil { + t.Fatal(err) + } + + out := map[string]evt.Envelope{} + for { + select { + case env := <-envelopes: + if _, seen := out[env.Event]; !seen { + out[env.Event] = env + } + default: + return out + } + } +} + +func mustJSON(t *testing.T, v any) []byte { + t.Helper() + raw, err := json.Marshal(v) + if err != nil { + t.Fatal(err) + } + return raw +} diff --git a/internal/plugins/event_dispatcher.go b/internal/plugins/event_dispatcher.go index cc206dfa69..a078267aa6 100644 --- a/internal/plugins/event_dispatcher.go +++ b/internal/plugins/event_dispatcher.go @@ -6,13 +6,15 @@ import ( "errors" "fmt" "log/slog" + "strconv" + "strings" "sync" "time" - "github.com/oklog/ulid/v2" "google.golang.org/protobuf/types/known/structpb" pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + publicevents "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/events" "github.com/Silo-Server/silo-server/internal/cache" "github.com/Silo-Server/silo-server/internal/events" @@ -86,16 +88,13 @@ var eventRetryDelays = []time.Duration{ // Deliveries are not ordered. An event is lost before it is stored when its // server dies first, when the intake is full, or when the write fails. // -// Events come from two places on the producing server: -// -// - ObservePublish, registered on the cache.ObservedEventBus, receives the -// catalog, admin and playback events host code publishes on the bus. -// Redis hands those to every server, so subscribing to them would store -// each one once per server. -// - The events.Hub, for envelopes published on this server. This is the -// path plugin-published events take (RuntimeHostServer.PublishEvent -// stamps `plugin..` and writes an envelope on ChannelPlugins). -// Envelopes the hub relays from other servers are theirs to store. +// Events come from the events.Hub: envelopes published on this server. +// Envelopes the hub relays from other servers are theirs to store. Only the +// events in the SDK's catalog (pkg/pluginsdk/events) and plugin events reach +// plugins; plugin events take this path too (RuntimeHostServer.PublishEvent +// stamps `plugin..` and writes an envelope on ChannelPlugins, which the +// hub keeps on this server). Each payload is rewritten into its catalog +// shape, with string IDs, before it is stored. // // Dispatch is fan-out only: every subscriber to event_name receives the event. // Plugins wanting to address a single peer should embed a target identifier @@ -103,7 +102,7 @@ var eventRetryDelays = []time.Duration{ type EventDispatcher struct { bus cache.EventBus hub *events.Hub - installations taskInstallationStore + installations eventInstallationStore resolver eventConsumerResolver deliveries eventDeliveryStore // sem holds one token per delivery in flight on this server. @@ -141,6 +140,14 @@ type EventDispatcher struct { now func() time.Time } +// eventInstallationStore is what the dispatcher reads to build its index: +// the enabled installations, their capabilities, and the event access each +// one's permission grant approves. +type eventInstallationStore interface { + taskInstallationStore + ApprovedEventAccess(ctx context.Context) (map[int][]string, error) +} + // eventSubscriber is the event_consumer.v1 capability an installation // receives one event name on. type eventSubscriber struct { @@ -157,14 +164,14 @@ type producedEvent struct { // installations. targetPluginID string // payload decodes the event's payload. It runs on the intake goroutine, - // off the publisher's. - payload func() *structpb.Struct + // off the publisher's. An error means the event is not delivered. + payload func() (*structpb.Struct, error) } func NewEventDispatcher( bus cache.EventBus, hub *events.Hub, - installations taskInstallationStore, + installations eventInstallationStore, resolver eventConsumerResolver, deliveries eventDeliveryStore, concurrency int, @@ -189,7 +196,7 @@ func NewEventDispatcher( func NewEventDispatcherWithTypedResolver( bus cache.EventBus, hub *events.Hub, - installations taskInstallationStore, + installations eventInstallationStore, resolver interface { EventConsumerClient(ctx context.Context, installationID int, capabilityID string) (*pluginhost.EventConsumerClient, error) }, @@ -207,8 +214,7 @@ func NewEventDispatcherWithTypedResolver( // Start follows lifecycle changes from other servers, takes envelopes from // the hub, and starts storing and delivering events until ctx ends or Stop -// is called. Bus events arrive through ObservePublish, which the caller -// registers. +// is called. func (d *EventDispatcher) Start(ctx context.Context) error { ctx, d.cancel = context.WithCancel(ctx) if err := d.bus.Subscribe(ctx, cache.ChannelAdmin, func(event cache.Event) { @@ -220,6 +226,8 @@ func (d *EventDispatcher) Start(ctx context.Context) error { } if d.hub != nil { + // Plugin hosts ask the hub before building a plugin event's envelope. + d.hub.SetPluginSubscribers(d.mayHaveSubscribers) envCh, unsub := d.hub.Subscribe() d.hubUnsubscribe = unsub d.loops.Go(func() { d.consumeHub(ctx, envCh) }) @@ -263,20 +271,6 @@ func (d *EventDispatcher) mayHaveSubscribers(eventName string) bool { return !ok || len(index[eventName]) > 0 } -// ObservePublish takes an event this server published on the bus. It is a -// cache.PublishObserver and never blocks the publisher. -func (d *EventDispatcher) ObservePublish(channel string, event cache.Event) { - switch channel { - case cache.ChannelCatalog, cache.ChannelAdmin, cache.ChannelPlayback: - default: - return - } - if !d.mayHaveSubscribers(event.Type) { - return - } - d.offer(busEvent(event)) -} - // offer queues an event without waiting, and logs it when the intake is full. func (d *EventDispatcher) offer(produced producedEvent) { select { @@ -286,21 +280,72 @@ func (d *EventDispatcher) offer(produced producedEvent) { } } -func busEvent(event cache.Event) producedEvent { - return producedEvent{ - id: ulid.Make().String(), - name: event.Type, - payload: func() *structpb.Struct { return decodeStringPayload(event.Payload) }, - } -} - func hubEvent(env events.Envelope) producedEvent { return producedEvent{ id: env.EventID, name: env.Event, targetPluginID: env.TargetPluginID, - payload: func() *structpb.Struct { return decodeRawJSON(env.Data) }, + payload: func() (*structpb.Struct, error) { return publicPayload(env) }, + } +} + +// publicPayload rewrites an envelope's data into the public shape the SDK's +// event catalog defines, so fields the host adds internally never reach +// plugins. Data that doesn't match the event's catalog type is an error. +func publicPayload(env events.Envelope) (*structpb.Struct, error) { + raw, err := withStringIDs(env) + if err != nil { + return nil, err + } + projected, err := publicevents.Project(env.Event, raw) + if err != nil { + return nil, err + } + return decodeRawJSON(projected), nil +} + +// withStringIDs makes a catalog event's identifiers JSON strings, as the +// catalog defines them. The host's payloads are shared with the events +// socket, which carries numeric IDs as numbers, so the conversion happens +// here: a top-level `id` or `*_id` field holding a number becomes its +// decimal string, and zero, which no stored row has, becomes absent (a +// server-queued job's created_by_user_id). A notification names only its +// profile, and profile IDs repeat across accounts, so the account the +// envelope is addressed to is added as user_id. Plugin events pass through. +func withStringIDs(env events.Envelope) (json.RawMessage, error) { + if publicevents.IsPluginEvent(env.Event) || len(env.Data) == 0 { + return env.Data, nil + } + var fields map[string]json.RawMessage + if err := json.Unmarshal(env.Data, &fields); err != nil { + return nil, fmt.Errorf("decode %s payload: %w", env.Event, err) } + if fields == nil { + return env.Data, nil + } + for key, value := range fields { + if (key != "id" && !strings.HasSuffix(key, "_id")) || !isJSONNumber(value) { + continue + } + if string(value) == "0" { + delete(fields, key) + continue + } + fields[key] = jsonString(string(value)) + } + if env.Event == publicevents.NotificationCreated && env.UserID > 0 { + fields["user_id"] = jsonString(strconv.Itoa(env.UserID)) + } + return json.Marshal(fields) +} + +func isJSONNumber(value json.RawMessage) bool { + return len(value) > 0 && (value[0] == '-' || (value[0] >= '0' && value[0] <= '9')) +} + +func jsonString(s string) json.RawMessage { + encoded, _ := json.Marshal(s) + return encoded } // consumeHub reads until Stop unsubscribes, so envelopes published while the @@ -344,8 +389,13 @@ func (d *EventDispatcher) store(ctx context.Context, produced producedEvent) { if len(subscribers) == 0 { return } + decoded, err := produced.payload() + if err != nil { + slog.WarnContext(ctx, "plugin event dispatcher: payload doesn't match the event catalog, event not delivered to plugins", "component", "plugins", "event_name", produced.name, "event_id", produced.id, "error", err) + return + } var payload json.RawMessage - if decoded := produced.payload(); decoded != nil { + if decoded != nil { encoded, err := decoded.MarshalJSON() if err != nil { slog.WarnContext(ctx, "plugin event dispatcher: encode payload failed, event not delivered to plugins", "component", "plugins", "event_name", produced.name, "event_id", produced.id, "error", err) @@ -370,24 +420,6 @@ func (d *EventDispatcher) store(ctx context.Context, produced producedEvent) { d.wakeDeliveries() } -// decodeStringPayload tries to JSON-decode a cache.Event.Payload string into a -// structpb. Plugin consumers expect top-level fields (e.g. p["libraryId"]), so -// when the payload parses we pass it through as-is. If it doesn't parse — the -// payload is an opaque id rather than JSON — we still hand the raw value over -// under "raw" so the consumer can ignore it without misreading nil fields. -func decodeStringPayload(raw string) *structpb.Struct { - if raw == "" { - return nil - } - var m map[string]any - if err := json.Unmarshal([]byte(raw), &m); err == nil { - s, _ := structpb.NewStruct(m) - return s - } - s, _ := structpb.NewStruct(map[string]any{"raw": raw}) - return s -} - func decodeRawJSON(raw json.RawMessage) *structpb.Struct { if len(raw) == 0 { return nil @@ -473,14 +505,20 @@ func (d *EventDispatcher) invalidateIndex() { // buildIndex maps every event name an enabled installation subscribes to onto // that installation's first event_consumer.v1 capability listing it, which -// preserves one delivery per installation. Subscribers stay in installation -// order. complete is false when an installation's capabilities could not be -// read; that installation is left out and the caller must not keep the index. +// preserves one delivery per installation. An admin or user_data event is +// indexed only when the installation's permission grant approves its access +// class. Subscribers stay in installation order. complete is false when an +// installation's capabilities could not be read; that installation is left +// out and the caller must not keep the index. func (d *EventDispatcher) buildIndex(ctx context.Context) (index map[string][]eventSubscriber, complete bool, err error) { installations, err := d.installations.ListEnabled(ctx) if err != nil { return nil, false, err } + approved, err := d.installations.ApprovedEventAccess(ctx) + if err != nil { + return nil, false, err + } index = make(map[string][]eventSubscriber) complete = true @@ -507,6 +545,13 @@ func (d *EventDispatcher) buildIndex(ctx context.Context) (index map[string][]ev if _, ok := indexed[eventName]; ok { continue } + // Only catalog and plugin events reach plugins; the host's + // internal event names are not a contract. Admin activity + // and personal data reach only installations approved for it. + access, deliverable := publicevents.AccessOf(eventName) + if !deliverable || !eventAccessApproved(access, approved[installation.ID]) { + continue + } indexed[eventName] = struct{}{} index[eventName] = append(index[eventName], eventSubscriber{ installationID: installation.ID, diff --git a/internal/plugins/event_dispatcher_delivery_test.go b/internal/plugins/event_dispatcher_delivery_test.go index 83c0e5b1a5..a9a03ba7df 100644 --- a/internal/plugins/event_dispatcher_delivery_test.go +++ b/internal/plugins/event_dispatcher_delivery_test.go @@ -19,7 +19,6 @@ import ( // hub, dispatcher and plugin process, over the cluster's shared bus and // outbox. type apiServer struct { - bus *cache.ObservedEventBus hub *events.Hub dispatcher *EventDispatcher } @@ -27,8 +26,7 @@ type apiServer struct { func startAPIServer(t *testing.T, name string, shared cache.EventBus, deliveries eventDeliveryStore, client eventConsumerClient, subscriptions ...string) apiServer { t.Helper() ctx := t.Context() - bus := cache.NewObservedEventBus(shared) - hub := events.NewHub(name, bus) + hub := events.NewHub(name, shared) if err := hub.Start(ctx); err != nil { t.Fatalf("start %s hub: %v", name, err) } @@ -36,13 +34,12 @@ func startAPIServer(t *testing.T, name string, shared cache.EventBus, deliveries installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", subscriptions...)}}, } - d := NewEventDispatcher(bus, hub, store, staticResolver{client: client}, deliveries, 4) + d := NewEventDispatcher(shared, hub, store, staticResolver{client: client}, deliveries, 4) if err := d.Start(ctx); err != nil { t.Fatalf("start %s dispatcher: %v", name, err) } - bus.ObservePublishes(d.ObservePublish) t.Cleanup(d.Stop) - return apiServer{bus: bus, hub: hub, dispatcher: d} + return apiServer{hub: hub, dispatcher: d} } type staticResolver struct{ client eventConsumerClient } @@ -52,19 +49,19 @@ func (r staticResolver) EventConsumerClient(context.Context, int, string) (event } // TestClusterDeliversEachEventOnce runs two API servers on one bus and one -// outbox. Redis hands every bus event, and every hub envelope, to both -// servers; each event must still reach the installation once. +// outbox. Redis hands every hub envelope to both servers; each event must +// still reach the installation once. func TestClusterDeliversEachEventOnce(t *testing.T) { ctx := t.Context() shared := newFakeBus() deliveries := newMemoryDeliveryStore() client := &recordingClient{done: make(chan struct{}), want: 3} - subscriptions := []string{cache.EventScanComplete, "plugin.silo.other.ping", "plugin.silo.other.pong"} + subscriptions := []string{"scan.completed", "plugin.silo.other.ping", "plugin.silo.other.pong"} a := startAPIServer(t, "api-a", shared, deliveries, client, subscriptions...) b := startAPIServer(t, "api-b", shared, deliveries, client, subscriptions...) - if err := a.bus.Publish(ctx, cache.ChannelCatalog, cache.Event{Type: cache.EventScanComplete, Payload: "7"}); err != nil { - t.Fatalf("publish bus event: %v", err) + if err := a.hub.Publish(ctx, events.Envelope{Channel: events.ChannelScans, Event: "scan.completed", Data: json.RawMessage(`{"id":"scan-1","library_id":7}`)}); err != nil { + t.Fatalf("publish catalog event: %v", err) } if err := a.hub.Publish(ctx, events.Envelope{Channel: events.ChannelPlugins, Event: "plugin.silo.other.ping", Data: json.RawMessage(`{"n":1}`)}); err != nil { t.Fatalf("publish envelope on api-a: %v", err) @@ -96,18 +93,18 @@ func TestClusterDeliversEachEventOnce(t *testing.T) { } } -// TestServerWithoutRedisDeliversBusEvents covers a single server without a +// TestServerWithoutRedisDeliversEvents covers a single server without a // Redis URL, whose bus delivers nothing to subscribers. -func TestServerWithoutRedisDeliversBusEvents(t *testing.T) { +func TestServerWithoutRedisDeliversEvents(t *testing.T) { client := &recordingClient{done: make(chan struct{}), want: 1} - server := startAPIServer(t, "api", &cache.NoopEventBus{}, newMemoryDeliveryStore(), client, cache.EventScanComplete) + server := startAPIServer(t, "api", &cache.NoopEventBus{}, newMemoryDeliveryStore(), client, "scan.completed") - if err := server.bus.Publish(t.Context(), cache.ChannelCatalog, cache.Event{Type: cache.EventScanComplete, Payload: `{"libraryId":"lib-1"}`}); err != nil { + if err := server.hub.Publish(t.Context(), events.Envelope{Channel: events.ChannelScans, Event: "scan.completed", Data: json.RawMessage(`{"id":"scan-1","library_id":7}`)}); err != nil { t.Fatalf("publish: %v", err) } waitFor(t, client) - if got := client.get()[0].GetPayload().AsMap()["libraryId"]; got != "lib-1" { - t.Fatalf("payload libraryId = %v, want lib-1", got) + if got := client.get()[0].GetPayload().AsMap()["library_id"]; got != "7" { + t.Fatalf("payload library_id = %v, want \"7\"", got) } } @@ -139,7 +136,7 @@ func newDeliveryFixture(client eventConsumerClient) (*EventDispatcher, *memoryDe deliveries := newMemoryDeliveryStore() store := &fakeInstallationStore{ installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, - capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", cache.EventScanComplete)}}, + capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", "scan.completed")}}, } return NewEventDispatcher(newFakeBus(), nil, store, staticResolver{client: client}, deliveries, 4), deliveries } @@ -149,7 +146,7 @@ func TestFailedDeliveryIsRetriedWithTheSameEventID(t *testing.T) { client := &flakyClient{failures: 2, err: errors.New("plugin restarting")} d, deliveries := newDeliveryFixture(client) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete, Payload: "7"}) + d.dispatchEnvelope(ctx, scanCompleted()) for _, delay := range eventRetryDelays[:2] { pending := deliveries.pending() if len(pending) != 1 || pending[0].lastError != "plugin restarting" { @@ -186,7 +183,7 @@ func TestDeliveryGivesUpAfterTheLastRetry(t *testing.T) { client := &flakyClient{failures: 1 << 30, err: errors.New("broken")} d, deliveries := newDeliveryFixture(client) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete}) + d.dispatchEnvelope(ctx, scanCompleted()) for _, delay := range eventRetryDelays { deliveries.advance(delay) d.deliverDue(ctx) @@ -207,7 +204,7 @@ func TestDeliveryToDisabledInstallationIsRetried(t *testing.T) { deliveries := newMemoryDeliveryStore() store := &fakeInstallationStore{ installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, - capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", cache.EventScanComplete)}}, + capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", "scan.completed")}}, } client := &flakyClient{} disabled := true @@ -219,7 +216,7 @@ func TestDeliveryToDisabledInstallationIsRetried(t *testing.T) { }) d := NewEventDispatcher(newFakeBus(), nil, store, resolver, deliveries, 4) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete}) + d.dispatchEnvelope(ctx, scanCompleted()) if pending := deliveries.pending(); len(pending) != 1 || len(pending[0].delays) != 1 { t.Fatalf("outbox after delivering to a disabled installation = %+v, want the delivery waiting to retry", pending) } @@ -238,7 +235,7 @@ func TestUndeliverablePayloadIsDropped(t *testing.T) { ctx := t.Context() client := &flakyClient{} d, deliveries := newDeliveryFixture(client) - if err := deliveries.Enqueue(ctx, []EventDelivery{{EventID: "e", EventName: cache.EventScanComplete, Payload: []byte(`[1]`), InstallationID: 1, CapabilityID: "events"}}); err != nil { + if err := deliveries.Enqueue(ctx, []EventDelivery{{EventID: "e", EventName: "scan.completed", Payload: []byte(`[1]`), InstallationID: 1, CapabilityID: "events"}}); err != nil { t.Fatal(err) } d.deliverDue(ctx) @@ -250,31 +247,49 @@ func TestUndeliverablePayloadIsDropped(t *testing.T) { } } -// TestUnsubscribedEventsAreNotQueued: once the index is built, events no -// installation subscribes to never take a place in the intake. -func TestUnsubscribedEventsAreNotQueued(t *testing.T) { +// TestPayloadOffTheCatalogIsNotQueued: a payload that doesn't fit its +// catalog type is dropped, not queued without its data. +func TestPayloadOffTheCatalogIsNotQueued(t *testing.T) { ctx := t.Context() - d, _ := newDeliveryFixture(&flakyClient{}) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete}) - - d.ObservePublish(cache.ChannelPlayback, cache.Event{Type: cache.EventPlaybackSessionsChanged}) - if got := len(d.intake); got != 0 { - t.Fatalf("intake after an unsubscribed event = %d, want 0", got) + d, deliveries := newDeliveryFixture(&flakyClient{}) + d.store(ctx, hubEvent(catalogEnvelope("scan.completed", `{"id":"scan-1","library_id":true}`))) + if pending := deliveries.pending(); len(pending) != 0 { + t.Fatalf("outbox = %+v, want empty", pending) } - d.ObservePublish(cache.ChannelCatalog, cache.Event{Type: cache.EventScanComplete}) - if got := len(d.intake); got != 1 { - t.Fatalf("intake after a subscribed event = %d, want 1", got) +} + +// TestOnlyCatalogEventsAreQueued: once the index is built, an event no +// installation subscribes to never takes a place in the intake, and neither +// does an internal event a plugin subscribed to anyway. +func TestOnlyCatalogEventsAreQueued(t *testing.T) { + ctx := t.Context() + store := &fakeInstallationStore{ + installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, + capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", "scan.completed", "user_state.changed", "plugin.silo.other.ping")}}, + } + d := NewEventDispatcher(newFakeBus(), nil, store, staticResolver{client: &flakyClient{}}, newMemoryDeliveryStore(), 4) + d.dispatchEnvelope(ctx, scanCompleted()) // builds the index + + for name, want := range map[string]bool{ + "scan.completed": true, + "plugin.silo.other.ping": true, + "session.started": false, // in the catalog, not subscribed + "user_state.changed": false, // subscribed, not in the catalog + } { + if got := d.mayHaveSubscribers(name); got != want { + t.Errorf("mayHaveSubscribers(%q) = %v, want %v", name, got, want) + } } } // TestStopStoresEventsPublishedWhileDraining: the server's context ends -// before it drains its requests, and the bus events and hub envelopes those -// requests publish must still reach the outbox. +// before it drains its requests, and the events those requests publish must +// still reach the outbox. func TestStopStoresEventsPublishedWhileDraining(t *testing.T) { deliveries := newMemoryDeliveryStore() store := &fakeInstallationStore{ installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, - capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", cache.EventScanComplete, "plugin.silo.other.ping")}}, + capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", "scan.completed", "plugin.silo.other.ping")}}, } bus := newFakeBus() hub := events.NewHub("api", bus) @@ -285,7 +300,9 @@ func TestStopStoresEventsPublishedWhileDraining(t *testing.T) { } cancel() - d.ObservePublish(cache.ChannelCatalog, cache.Event{Type: cache.EventScanComplete, Payload: "7"}) + if err := hub.Publish(context.Background(), events.Envelope{Channel: events.ChannelScans, Event: "scan.completed", Data: json.RawMessage(`{}`)}); err != nil { + t.Fatal(err) + } if err := hub.Publish(context.Background(), events.Envelope{Channel: events.ChannelPlugins, Event: "plugin.silo.other.ping"}); err != nil { t.Fatal(err) } @@ -295,7 +312,7 @@ func TestStopStoresEventsPublishedWhileDraining(t *testing.T) { names = append(names, pending.EventName) } slices.Sort(names) - if want := []string{"plugin.silo.other.ping", cache.EventScanComplete}; !slices.Equal(names, want) { + if want := []string{"plugin.silo.other.ping", "scan.completed"}; !slices.Equal(names, want) { t.Fatalf("outbox after Stop = %v, want %v", names, want) } } @@ -323,7 +340,7 @@ func TestShutdownDuringStoreKeepsTheEvent(t *testing.T) { deliveries := &cancelAwareStore{memoryDeliveryStore: newMemoryDeliveryStore(), entered: make(chan struct{}), release: make(chan struct{})} store := &fakeInstallationStore{ installations: []*Installation{{ID: 1, PluginID: "silo.notify", Enabled: true}}, - capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", cache.EventScanComplete)}}, + capabilities: map[int][]*Capability{1: {eventConsumer(1, "events", "scan.completed")}}, } d := NewEventDispatcher(newFakeBus(), nil, store, staticResolver{client: &flakyClient{}}, deliveries, 4) ctx, cancel := context.WithCancel(context.Background()) @@ -331,7 +348,7 @@ func TestShutdownDuringStoreKeepsTheEvent(t *testing.T) { t.Fatal(err) } - d.ObservePublish(cache.ChannelCatalog, cache.Event{Type: cache.EventScanComplete}) + d.offer(hubEvent(scanCompleted())) <-deliveries.entered cancel() close(deliveries.release) @@ -349,7 +366,7 @@ func TestDeliveryClaimedByDeadServerIsDeliveredByAnother(t *testing.T) { ctx := t.Context() client := &flakyClient{} d, deliveries := newDeliveryFixture(client) - d.store(ctx, busEvent(cache.Event{Type: cache.EventScanComplete})) + d.store(ctx, hubEvent(scanCompleted())) dead, err := deliveries.Claim(ctx, 10, eventDeliveryLease) if err != nil || len(dead) != 1 { @@ -382,7 +399,7 @@ func TestDeliveryErrorIsSanitized(t *testing.T) { client := &flakyClient{failures: 1, err: errors.New("rpc error: desc = api_key=SECRET rejected")} d, deliveries := newDeliveryFixture(client) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete}) + d.dispatchEnvelope(ctx, scanCompleted()) pending := deliveries.pending() if len(pending) != 1 || strings.Contains(pending[0].lastError, "SECRET") || !strings.Contains(pending[0].lastError, "api_key=") { t.Fatalf("stored error = %+v, want the message with the key's value masked", pending) diff --git a/internal/plugins/event_dispatcher_index_test.go b/internal/plugins/event_dispatcher_index_test.go index f5db2af3ca..e3b86cb50f 100644 --- a/internal/plugins/event_dispatcher_index_test.go +++ b/internal/plugins/event_dispatcher_index_test.go @@ -28,6 +28,26 @@ type countingDispatchStore struct { onListEnabled func() // capabilitiesErr fails ListCapabilities for the listed installations. capabilitiesErr map[int]error + // approved is each installation's approved event access; nil approves + // every class for every installation. + approved map[int][]string +} + +func (s *countingDispatchStore) ApprovedEventAccess(context.Context) (map[int][]string, error) { + s.mu.Lock() + defer s.mu.Unlock() + return approvedOrAll(s.approved, s.installations), nil +} + +// approve sets an installation's approved event access, as an administrator's +// approval on another replica would. +func (s *countingDispatchStore) approve(installationID int, access ...string) { + s.mu.Lock() + defer s.mu.Unlock() + if s.approved == nil { + s.approved = map[int][]string{} + } + s.approved[installationID] = access } func (s *countingDispatchStore) ListEnabled(context.Context) ([]*Installation, error) { @@ -97,7 +117,7 @@ type delivery struct { } // deliveryRecorder resolves every installation to a client that records the -// call. dispatchBusEvent and dispatchEnvelope wait for their deliveries, so +// call. dispatchEnvelope waits for its deliveries, so // they have finished recording by the time they return. type deliveryRecorder struct { mu sync.Mutex @@ -148,12 +168,12 @@ func eventConsumer(installationID int, id string, subscriptions ...string) *Capa // newIndexFixture returns a store with one builtin and three plugin // installations, of which only installation 1 subscribes to -// library.media_added and installation 3 subscribes to a plugin event. +// catalog.library.changed and installation 3 subscribes to a plugin event. func newIndexFixture() *countingDispatchStore { store := &countingDispatchStore{} store.install(&Installation{ID: 1, PluginID: "silo.alpha", Enabled: true}, - eventConsumer(1, "first", "library.media_added"), - eventConsumer(1, "second", "library.media_added", cache.EventScanComplete), + eventConsumer(1, "first", "catalog.library.changed"), + eventConsumer(1, "second", "catalog.library.changed", "scan.completed"), ) store.install(&Installation{ID: 2, PluginID: "silo.metadata", Enabled: true}, &Capability{InstallationID: 2, Type: "metadata_provider.v1", ID: "tmdb"}, @@ -165,9 +185,8 @@ func newIndexFixture() *countingDispatchStore { return store } -func mediaAdded() cache.Event { - body, _ := json.Marshal(map[string]any{"libraryId": "lib-1"}) - return cache.Event{Type: "library.media_added", Payload: string(body)} +func mediaAdded() events.Envelope { + return catalogEnvelope("catalog.library.changed", `{"library_id":1,"reason":"scan","new":2}`) } // TestDispatcherStoreReadsPerEvent measures how many plugin store reads one @@ -181,7 +200,7 @@ func TestDispatcherStoreReadsPerEvent(t *testing.T) { d := NewEventDispatcher(newFakeBus(), nil, store, recorder, newMemoryDeliveryStore(), 4) // Warm up: the first event may build whatever the dispatcher caches. - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) recorder.take() const eventCount = 100 @@ -196,11 +215,11 @@ func TestDispatcherStoreReadsPerEvent(t *testing.T) { return reads } - unsubscribedBus := measure("bus event, 0 subscribers", func() { - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventPlaybackSessionsChanged, Payload: "42"}) + unsubscribedCatalog := measure("catalog event, 0 subscribers", func() { + d.dispatchEnvelope(ctx, catalogEnvelope("session.started", `{"session_id":"s1"}`)) }) // The envelope a progress sync publishes for each updated item. - unsubscribedHub := measure("hub event, 0 subscribers", func() { + unsubscribedHub := measure("internal event, 0 subscribers", func() { d.dispatchEnvelope(ctx, events.Envelope{ Channel: events.ChannelUserState, Event: "user_state.changed", @@ -213,21 +232,21 @@ func TestDispatcherStoreReadsPerEvent(t *testing.T) { t.Fatalf("unsubscribed events were delivered: %+v", got) } - subscribed := measure("bus event, 1 subscriber", func() { d.dispatchBusEvent(ctx, mediaAdded()) }) + subscribed := measure("catalog event, 1 subscriber", func() { d.dispatchEnvelope(ctx, mediaAdded()) }) got := recorder.take() if len(got) != eventCount { t.Fatalf("subscribed deliveries = %d, want %d", len(got), eventCount) } for _, delivered := range got { - want := delivery{installationID: 1, capabilityID: "first", eventName: "library.media_added"} + want := delivery{installationID: 1, capabilityID: "first", eventName: "catalog.library.changed"} if delivered != want { t.Fatalf("delivery = %+v, want %+v", delivered, want) } } - if unsubscribedBus != 0 || unsubscribedHub != 0 || subscribed != 0 { - t.Fatalf("store reads per %d events: bus unsubscribed=%d hub unsubscribed=%d subscribed=%d, want 0 each", - eventCount, unsubscribedBus, unsubscribedHub, subscribed) + if unsubscribedCatalog != 0 || unsubscribedHub != 0 || subscribed != 0 { + t.Fatalf("store reads per %d events: catalog unsubscribed=%d internal unsubscribed=%d subscribed=%d, want 0 each", + eventCount, unsubscribedCatalog, unsubscribedHub, subscribed) } } @@ -250,7 +269,7 @@ func TestDispatcherFollowsPluginsChangedFromAnotherReplica(t *testing.T) { publish := func() []int { t.Helper() - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) var ids []int for _, delivered := range recorder.take() { ids = append(ids, delivered.installationID) @@ -281,7 +300,7 @@ func TestDispatcherFollowsPluginsChangedFromAnotherReplica(t *testing.T) { // The other replica commits the new installation. Until its notification // arrives this replica keeps dispatching from its index. store.install(&Installation{ID: 5, PluginID: "silo.delta", Enabled: true}, - eventConsumer(5, "watcher", "library.media_added"), + eventConsumer(5, "watcher", "catalog.library.changed"), ) if got := publish(); !reflect.DeepEqual(got, []int{1}) { t.Fatalf("deliveries before plugins_changed = %v, want [1]", got) @@ -349,20 +368,20 @@ func TestServiceLifecycleChangeRebuildsDispatcherIndex(t *testing.T) { t.Cleanup(d.Stop) svc.SetEventDispatcher(d) - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := recorder.take(); len(got) != 1 { t.Fatalf("initial deliveries = %+v, want one", got) } store.install(&Installation{ID: 5, PluginID: "silo.delta", Enabled: true}, - eventConsumer(5, "watcher", "library.media_added"), + eventConsumer(5, "watcher", "catalog.library.changed"), ) store.resetReads() svc.OnLifecycleChange(ctx) changeReads := store.reads() store.resetReads() - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) eventReads := store.reads() t.Logf("store reads: %d during OnLifecycleChange, %d for the next event", changeReads, eventReads) var ids []int @@ -388,11 +407,11 @@ func TestDispatcherDeliversOncePerInstallation(t *testing.T) { recorder := &deliveryRecorder{} d := NewEventDispatcher(newFakeBus(), nil, newIndexFixture(), recorder, newMemoryDeliveryStore(), 4) - d.dispatchBusEvent(ctx, mediaAdded()) - d.dispatchBusEvent(ctx, cache.Event{Type: cache.EventScanComplete, Payload: "7"}) + d.dispatchEnvelope(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, scanCompleted()) want := []delivery{ - {installationID: 1, capabilityID: "first", eventName: "library.media_added"}, - {installationID: 1, capabilityID: "second", eventName: cache.EventScanComplete}, + {installationID: 1, capabilityID: "first", eventName: "catalog.library.changed"}, + {installationID: 1, capabilityID: "second", eventName: "scan.completed"}, } if got := recorder.take(); !reflect.DeepEqual(got, want) { t.Fatalf("deliveries = %+v, want %+v", got, want) @@ -409,7 +428,7 @@ func TestDispatcherIndexNotKeptAfterRacingInvalidation(t *testing.T) { d := NewEventDispatcher(newFakeBus(), nil, store, recorder, newMemoryDeliveryStore(), 4) store.onListEnabled = d.invalidateIndex - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := recorder.take(); len(got) != 1 { t.Fatalf("racing rebuild deliveries = %+v, want one", got) } @@ -419,12 +438,12 @@ func TestDispatcherIndexNotKeptAfterRacingInvalidation(t *testing.T) { store.onListEnabled = nil store.resetReads() - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := store.reads(); got != 4 { t.Fatalf("store reads after racing rebuild = %d, want 4 (index was not kept)", got) } store.resetReads() - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := store.reads(); got != 0 { t.Fatalf("store reads once rebuilt = %d, want 0", got) } @@ -439,17 +458,17 @@ func TestDispatcherIndexExpires(t *testing.T) { now := time.Unix(1_700_000_000, 0) d.now = func() time.Time { return now } - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) store.resetReads() now = now.Add(DefaultLifecyclePollInterval - time.Second) - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := store.reads(); got != 0 { t.Fatalf("store reads before expiry = %d, want 0", got) } now = now.Add(time.Second) - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := store.reads(); got != 4 { t.Fatalf("store reads at expiry = %d, want 4", got) } @@ -500,13 +519,13 @@ func TestDispatcherIndexWithUnreadableInstallationIsNotKept(t *testing.T) { ctx := context.Background() store := newIndexFixture() store.install(&Installation{ID: 5, PluginID: "silo.delta", Enabled: true}, - eventConsumer(5, "watcher", "library.media_added"), + eventConsumer(5, "watcher", "catalog.library.changed"), ) store.capabilitiesErr = map[int]error{5: errors.New("connection reset")} recorder := &deliveryRecorder{} d := NewEventDispatcher(newFakeBus(), nil, store, recorder, newMemoryDeliveryStore(), 4) - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) if got := recorder.take(); len(got) != 1 || got[0].installationID != 1 { t.Fatalf("deliveries with installation 5 unreadable = %+v, want installation 1 only", got) } @@ -514,7 +533,7 @@ func TestDispatcherIndexWithUnreadableInstallationIsNotKept(t *testing.T) { store.mu.Lock() store.capabilitiesErr = nil store.mu.Unlock() - d.dispatchBusEvent(ctx, mediaAdded()) + d.dispatchEnvelope(ctx, mediaAdded()) var ids []int for _, delivered := range recorder.take() { ids = append(ids, delivered.installationID) @@ -554,3 +573,51 @@ func TestLifecycleChangeIsAnnouncedBeforeSlowHooks(t *testing.T) { t.Fatalf("lifecycle order = %v, want %v", order, want) } } + +// TestDispatcherDeliversAdminAndPersonalEventsOnlyWhenApproved covers event +// gating: a subscription to an admin or user_data event receives nothing until +// the installation's grant approves that class, and an approval on another +// replica reaches this one through cache.EventPluginsChanged. Public and plugin +// events need no approval. +func TestDispatcherDeliversAdminAndPersonalEventsOnlyWhenApproved(t *testing.T) { + ctx := t.Context() + bus := newFakeBus() + store := &countingDispatchStore{} + store.install(&Installation{ID: 1, PluginID: "silo.inbox", Enabled: true}, + eventConsumer(1, "events", "notification.created", "scan.completed", "catalog.library.changed", "plugin.silo.other.ping"), + ) + store.approve(1) + recorder := &deliveryRecorder{} + d := NewEventDispatcher(bus, nil, store, recorder, newMemoryDeliveryStore(), 4) + if err := d.Start(ctx); err != nil { + t.Fatalf("start dispatcher: %v", err) + } + t.Cleanup(d.Stop) + + notification := events.Envelope{Event: "notification.created", EventID: "n1", UserID: 7, ProfileID: "p1", + Data: json.RawMessage(`{"id":"d1","type":"episode.available","profile_id":"p1","created_at":"2026-11-04T10:00:00Z"}`)} + delivered := func() []string { + t.Helper() + for _, env := range []events.Envelope{notification, scanCompleted(), mediaAdded(), catalogEnvelope("plugin.silo.other.ping", `{}`)} { + d.dispatchEnvelope(ctx, env) + } + var names []string + for _, got := range recorder.take() { + names = append(names, got.eventName) + } + slices.Sort(names) + return names + } + + if got, want := delivered(), []string{"catalog.library.changed", "plugin.silo.other.ping"}; !slices.Equal(got, want) { + t.Fatalf("deliveries without approval = %v, want %v", got, want) + } + + store.approve(1, "user_data") + if err := bus.Publish(ctx, cache.ChannelAdmin, cache.Event{Type: cache.EventPluginsChanged}); err != nil { + t.Fatalf("publish plugins_changed: %v", err) + } + if got, want := delivered(), []string{"catalog.library.changed", "notification.created", "plugin.silo.other.ping"}; !slices.Equal(got, want) { + t.Fatalf("deliveries after approving user_data = %v, want %v", got, want) + } +} diff --git a/internal/plugins/event_dispatcher_test.go b/internal/plugins/event_dispatcher_test.go index 1026cc7c42..132f2f14f3 100644 --- a/internal/plugins/event_dispatcher_test.go +++ b/internal/plugins/event_dispatcher_test.go @@ -10,6 +10,7 @@ import ( "time" pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + "github.com/oklog/ulid/v2" "github.com/Silo-Server/silo-server/internal/cache" "github.com/Silo-Server/silo-server/internal/events" @@ -124,14 +125,18 @@ func (s *memoryDeliveryStore) busy() bool { return false } -// dispatchBusEvent runs event through d the way the API server that -// published it does, then delivers everything due and waits for it. -func (d *EventDispatcher) dispatchBusEvent(ctx context.Context, event cache.Event) { - d.store(ctx, busEvent(event)) - d.deliverDue(ctx) +// catalogEnvelope is a catalog event as this server's hub hands it over. +func catalogEnvelope(name, data string) events.Envelope { + return events.Envelope{Event: name, EventID: ulid.Make().String(), Data: json.RawMessage(data)} +} + +// scanCompleted is a scan.completed event with a minimal payload. +func scanCompleted() events.Envelope { + return catalogEnvelope("scan.completed", `{"id":"scan-1","library_id":7,"status":"completed"}`) } -// dispatchEnvelope is dispatchBusEvent for an envelope published on d's hub. +// dispatchEnvelope runs env through d the way the API server that published +// it does, then delivers everything due and waits for it. func (d *EventDispatcher) dispatchEnvelope(ctx context.Context, env events.Envelope) { d.store(ctx, hubEvent(env)) d.deliverDue(ctx) @@ -185,6 +190,9 @@ func (b *fakeBus) Close() error { return nil } type fakeInstallationStore struct { installations []*Installation capabilities map[int][]*Capability + // approved is each installation's approved event access; nil approves + // every class for every installation. + approved map[int][]string } func (s *fakeInstallationStore) ListEnabled(_ context.Context) ([]*Installation, error) { @@ -193,6 +201,22 @@ func (s *fakeInstallationStore) ListEnabled(_ context.Context) ([]*Installation, func (s *fakeInstallationStore) ListCapabilities(_ context.Context, id int) ([]*Capability, error) { return s.capabilities[id], nil } +func (s *fakeInstallationStore) ApprovedEventAccess(context.Context) (map[int][]string, error) { + return approvedOrAll(s.approved, s.installations), nil +} + +// approvedOrAll returns approved, or every access class for every +// installation when approved is nil. +func approvedOrAll(approved map[int][]string, installations []*Installation) map[int][]string { + if approved != nil { + return approved + } + all := make(map[int][]string, len(installations)) + for _, installation := range installations { + all[installation.ID] = []string{"admin", "user_data"} + } + return all +} type recordingClient struct { mu sync.Mutex @@ -257,13 +281,11 @@ func newFixture(t *testing.T, subs []string, want int) (cache.EventBus, *events. if err := d.Start(ctx); err != nil { t.Fatalf("start dispatcher: %v", err) } - observed := cache.NewObservedEventBus(bus) - observed.ObservePublishes(d.ObservePublish) t.Cleanup(func() { cancel() d.Stop() }) - return observed, hub, client + return bus, hub, client } func waitFor(t *testing.T, c *recordingClient) { @@ -285,34 +307,6 @@ func waitFor(t *testing.T, c *recordingClient) { } } -func TestDispatcher_BusEvent_DecodesJSONPayloadIntoFields(t *testing.T) { - bus, _, client := newFixture(t, []string{"library.media_added"}, 1) - - body, _ := json.Marshal(map[string]any{ - "libraryId": "lib-1", - "mediaType": "movie", - "mediaId": "media-xyz", - "tmdbId": 603, - }) - _ = bus.Publish(context.Background(), cache.ChannelCatalog, cache.Event{ - Type: "library.media_added", - Payload: string(body), - }) - - waitFor(t, client) - got := client.get() - if len(got) != 1 { - t.Fatalf("got %d events", len(got)) - } - p := got[0].GetPayload().AsMap() - if p["libraryId"] != "lib-1" { - t.Errorf("libraryId: got %v want lib-1; full payload=%v", p["libraryId"], p) - } - if _, wrapped := p["payload"]; wrapped { - t.Error("payload should not be wrapped under \"payload\" key") - } -} - func TestDispatcher_HubPluginEvent_ReachesConsumer(t *testing.T) { const eventName = "plugin.silo.arrproxy.submitted" _, hub, client := newFixture(t, []string{eventName}, 1) @@ -339,3 +333,31 @@ func TestDispatcher_HubPluginEvent_ReachesConsumer(t *testing.T) { t.Errorf("requestId: got %v want 01J; full payload=%v", p["requestId"], p) } } + +// A catalog event reaches plugins in its public shape: fields the host adds +// for its own clients are dropped, IDs are strings, and a notification names +// its account, since profile IDs repeat across accounts. +func TestDispatcher_NotificationReachesConsumerInItsPublicShape(t *testing.T) { + _, hub, client := newFixture(t, []string{"notification.created"}, 1) + + if err := hub.Publish(context.Background(), events.Envelope{ + Channel: events.ChannelNotifications, + Event: "notification.created", + Data: json.RawMessage(`{"id":"d1","type":"episode.available","profile_id":"p1","library_id":3,"series_title":"Severance","poster_thumbhash":"abc","read_at":null,"created_at":"2026-11-04T10:00:00Z"}`), + UserID: 7, + ProfileID: "p1", + }); err != nil { + t.Fatalf("publish: %v", err) + } + + waitFor(t, client) + payload := client.get()[0].GetPayload().AsMap() + if payload["user_id"] != "7" || payload["profile_id"] != "p1" || payload["library_id"] != "3" || payload["series_title"] != "Severance" { + t.Fatalf("payload = %v, want the account, profile, library and title, IDs as strings", payload) + } + for _, internal := range []string{"poster_thumbhash", "read_at"} { + if _, leaked := payload[internal]; leaked { + t.Errorf("payload carries %q, which isn't in the event catalog: %v", internal, payload) + } + } +} diff --git a/internal/plugins/export_test.go b/internal/plugins/export_test.go new file mode 100644 index 0000000000..59368ee576 --- /dev/null +++ b/internal/plugins/export_test.go @@ -0,0 +1,13 @@ +package plugins + +import "github.com/Silo-Server/silo-server/internal/events" + +// PublicPayloadJSON is what the dispatcher stores for env: the payload in its +// catalog shape. The external contract test runs producers through it. +func PublicPayloadJSON(env events.Envelope) ([]byte, error) { + payload, err := publicPayload(env) + if err != nil || payload == nil { + return nil, err + } + return payload.MarshalJSON() +} diff --git a/internal/plugins/installation.go b/internal/plugins/installation.go index 6d518ad1e6..93361fcf31 100644 --- a/internal/plugins/installation.go +++ b/internal/plugins/installation.go @@ -50,6 +50,9 @@ type Installation struct { CreatedAt time.Time UpdatedAt time.Time RuntimeGeneration int64 `json:"-"` + // HostAPIScopes is the manifest's host_api_scopes: the API key scopes + // the plugin asks for, whether or not this server knows or granted them. + HostAPIScopes []string `json:"-"` } // IsBuiltin reports whether this is the reserved builtin-host installation. @@ -83,6 +86,8 @@ type CreateInstallationInput struct { Enabled bool UpdatePolicy string Capabilities []Capability + // HostAPIScopes is the manifest's host_api_scopes. + HostAPIScopes []string } type UpdateInstallationInput struct { @@ -92,6 +97,8 @@ type UpdateInstallationInput struct { UpdatePolicy *string AvailableVersion *string Capabilities []Capability + // HostAPIScopes replaces the manifest's host_api_scopes when non-nil. + HostAPIScopes []string // Restart durably requests a new process on every resident host. Restart bool // SetRepository records RepositoryID as where the installed package now @@ -127,7 +134,7 @@ func (s *InstallationStore) WithTx(tx pgx.Tx) *InstallationStore { return &InstallationStore{pool: tx} } -const installationColumns = `id, repository_id, plugin_id, version, install_path, enabled, kind, update_policy, available_version, created_at, updated_at, runtime_generation` +const installationColumns = `id, repository_id, plugin_id, version, install_path, enabled, kind, update_policy, available_version, created_at, updated_at, runtime_generation, host_api_scopes` const capabilityColumns = `plugin_installation_id, capability_type, capability_id, metadata, created_at, updated_at` const archiveColumns = `plugin_installation_id, manifest_json, checksum, archive_bytes, created_at, updated_at` @@ -147,6 +154,7 @@ func scanInstallation(row pgx.Row) (*Installation, error) { &installation.CreatedAt, &installation.UpdatedAt, &installation.RuntimeGeneration, + &installation.HostAPIScopes, ); err != nil { if errors.Is(err, pgx.ErrNoRows) { return nil, ErrInstallationNotFound @@ -215,8 +223,8 @@ func (s *InstallationStore) Create(ctx context.Context, input CreateInstallation if updatePolicy == "" { updatePolicy = "auto" } - query := `INSERT INTO plugin_installations (repository_id, plugin_id, version, install_path, enabled, update_policy) - VALUES ($1, $2, $3, $4, $5, $6) + query := `INSERT INTO plugin_installations (repository_id, plugin_id, version, install_path, enabled, update_policy, host_api_scopes) + VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING ` + installationColumns installation, err := scanInstallation(tx.QueryRow( ctx, @@ -227,6 +235,7 @@ func (s *InstallationStore) Create(ctx context.Context, input CreateInstallation input.InstallPath, input.Enabled, updatePolicy, + nonNilStrings(input.HostAPIScopes), )) if err != nil { return nil, fmt.Errorf("creating plugin installation: %w", err) @@ -235,6 +244,10 @@ func (s *InstallationStore) Create(ctx context.Context, input CreateInstallation if err := s.replaceCapabilities(ctx, tx, installation.ID, input.Capabilities); err != nil { return nil, err } + // Installing a plugin is consent to the events it subscribes to. + if err := ensurePermissionGrant(ctx, tx, installation.ID, capabilityPointers(input.Capabilities)); err != nil { + return nil, err + } if err := tx.Commit(ctx); err != nil { return nil, fmt.Errorf("commit create installation transaction: %w", err) @@ -243,8 +256,12 @@ func (s *InstallationStore) Create(ctx context.Context, input CreateInstallation } func (s *InstallationStore) GetByID(ctx context.Context, id int) (*Installation, error) { + return getInstallation(ctx, s.pool, id) +} + +func getInstallation(ctx context.Context, q pgQuerier, id int) (*Installation, error) { query := `SELECT ` + installationColumns + ` FROM plugin_installations WHERE id = $1` - return scanInstallation(s.pool.QueryRow(ctx, query, id)) + return scanInstallation(q.QueryRow(ctx, query, id)) } func (s *InstallationStore) List(ctx context.Context) ([]*Installation, error) { @@ -325,13 +342,25 @@ func (s *InstallationStore) Update(ctx context.Context, id int, input UpdateInst if installation.IsBuiltin() { return ErrBuiltinInstallationImmutable } + return retryOnGrantChange(func() error { return s.update(ctx, id, input) }) +} +// update is one attempt at Update in its own transaction. +func (s *InstallationStore) update(ctx context.Context, id int, input UpdateInstallationInput) error { tx, err := s.pool.Begin(ctx) if err != nil { return fmt.Errorf("begin update installation transaction: %w", err) } defer tx.Rollback(ctx) + if input.HostAPIScopes != nil { + // Before the installation row: an uninstall locks the key and the + // grant first, then deletes the installation. + if err := narrowHostAPIKey(ctx, tx, id, input.HostAPIScopes); err != nil { + return err + } + } + var setClauses []string var args []any argIndex := 1 @@ -369,6 +398,11 @@ func (s *InstallationStore) Update(ctx context.Context, id int, input UpdateInst args = append(args, input.RepositoryID) argIndex++ } + if input.HostAPIScopes != nil { + setClauses = append(setClauses, fmt.Sprintf("host_api_scopes = $%d", argIndex)) + args = append(args, input.HostAPIScopes) + argIndex++ + } if len(setClauses) > 0 { setClauses = append(setClauses, "updated_at = NOW()") @@ -391,6 +425,11 @@ func (s *InstallationStore) Update(ctx context.Context, id int, input UpdateInst if err := s.replaceCapabilities(ctx, tx, id, input.Capabilities); err != nil { return err } + // A replacement keeps an existing grant as it is, so an upgrade that + // asks for more waits for an administrator. + if err := ensurePermissionGrant(ctx, tx, id, capabilityPointers(input.Capabilities)); err != nil { + return err + } } if err := tx.Commit(ctx); err != nil { @@ -436,10 +475,14 @@ func (s *InstallationStore) ListEnabledWithCapabilityTypes(ctx context.Context, } func (s *InstallationStore) ListCapabilities(ctx context.Context, installationID int) ([]*Capability, error) { + return listCapabilities(ctx, s.pool, installationID) +} + +func listCapabilities(ctx context.Context, q pgQuerier, installationID int) ([]*Capability, error) { query := `SELECT ` + capabilityColumns + ` FROM plugin_capabilities WHERE plugin_installation_id = $1 ORDER BY capability_type ASC, capability_id ASC` - rows, err := s.pool.Query(ctx, query, installationID) + rows, err := q.Query(ctx, query, installationID) if err != nil { return nil, fmt.Errorf("listing plugin capabilities: %w", err) } @@ -508,7 +551,22 @@ func (s *InstallationStore) GetArchive(ctx context.Context, installationID int) return scanArchive(s.pool.QueryRow(ctx, query, installationID)) } +// Delete removes the installation, its rows and its files. It deletes the +// host API key the installation's grant names directly, without an audit +// entry; an administrator's uninstall goes through +// PermissionService.DeleteInstallation, which audits that deletion. func (s *InstallationStore) Delete(ctx context.Context, id int) error { + return s.delete(ctx, id, nil) +} + +// hostAPIKeyRevoker deletes an installation's host API key through the +// issuer, acting as actorID, so the deletion is audited. +type hostAPIKeyRevoker struct { + keys HostAPIKeyIssuer + actorID int +} + +func (s *InstallationStore) delete(ctx context.Context, id int, revoker *hostAPIKeyRevoker) error { installation, err := s.GetByID(ctx, id) if err != nil { return err @@ -520,13 +578,17 @@ func (s *InstallationStore) Delete(ctx context.Context, id int) error { return ErrBuiltinInstallationImmutable } - tag, err := s.pool.Exec(ctx, `DELETE FROM plugin_installations WHERE id = $1`, id) - if err != nil { - return fmt.Errorf("deleting plugin installation: %w", err) - } - if tag.RowsAffected() == 0 { - return ErrInstallationNotFound + // The host API key issued to the plugin goes with it, in the same + // transaction, so no scoped credential outlives its plugin. + var committed func() + if err := retryOnGrantChange(func() error { + var err error + committed, err = s.deleteInstallationRows(ctx, id, revoker) + return err + }); err != nil { + return err } + committed() if err := removeInstallationFiles(ctx, installation); err != nil { return fmt.Errorf("removing plugin installation files: %w", err) @@ -535,6 +597,53 @@ func (s *InstallationStore) Delete(ctx context.Context, id int) error { return nil } +// deleteInstallationRows deletes the installation and the host API key its +// grant names in one transaction, and returns the hook to run once it has +// committed. Locking the key and then the grant (lockPermissionGrant) means +// an approval that lands meanwhile either commits first, and its key is the +// one deleted, or finds the installation gone and rolls back the key it +// minted. +func (s *InstallationStore) deleteInstallationRows(ctx context.Context, id int, revoker *hostAPIKeyRevoker) (func(), error) { + tx, err := s.pool.Begin(ctx) + if err != nil { + return nil, fmt.Errorf("begin delete installation transaction: %w", err) + } + defer func() { _ = tx.Rollback(context.WithoutCancel(ctx)) }() + if revoker != nil { + // Accounts before the key and the grant, the order RevokeTx and + // every other key deletion lock them in. + if err := revoker.keys.LockAccounts(ctx, tx, revoker.actorID); err != nil { + return nil, err + } + } + grant, err := lockPermissionGrant(ctx, tx, id) + if err != nil { + return nil, err + } + committed := func() {} + if grant != nil && grant.APIKeyID != nil { + if revoker != nil { + committed, err = revoker.keys.RevokeTx(ctx, tx, *grant.APIKeyID) + } else { + _, err = tx.Exec(ctx, `DELETE FROM api_keys WHERE id = $1`, *grant.APIKeyID) + } + if err != nil { + return nil, fmt.Errorf("deleting plugin host API key: %w", err) + } + } + tag, err := tx.Exec(ctx, `DELETE FROM plugin_installations WHERE id = $1`, id) + if err != nil { + return nil, fmt.Errorf("deleting plugin installation: %w", err) + } + if tag.RowsAffected() == 0 { + return nil, ErrInstallationNotFound + } + if err := tx.Commit(ctx); err != nil { + return nil, fmt.Errorf("commit delete installation transaction: %w", err) + } + return committed, nil +} + func (s *InstallationStore) replaceCapabilities( ctx context.Context, tx pgx.Tx, diff --git a/internal/plugins/installer.go b/internal/plugins/installer.go index 463f809f95..ad511724b3 100644 --- a/internal/plugins/installer.go +++ b/internal/plugins/installer.go @@ -304,6 +304,7 @@ func (i *Installer) replaceBinary( Enabled: &enabled, AvailableVersion: &availableVersion, Capabilities: capabilities, + HostAPIScopes: nonNilStrings(manifest.GetHostApiScopes()), SetRepository: true, RepositoryID: repositoryID, }); err != nil { @@ -321,6 +322,7 @@ func (i *Installer) replaceBinary( updated.InstallPath = binaryPath updated.Enabled = enabled updated.RepositoryID = repositoryID + updated.HostAPIScopes = nonNilStrings(manifest.GetHostApiScopes()) return &InstallResult{ Installation: &updated, @@ -393,6 +395,7 @@ func (i *Installer) replaceArchive( Enabled: &enabled, AvailableVersion: &availableVersion, Capabilities: capabilities, + HostAPIScopes: nonNilStrings(manifest.GetHostApiScopes()), SetRepository: true, RepositoryID: repositoryID, }); err != nil { @@ -410,6 +413,7 @@ func (i *Installer) replaceArchive( updated.InstallPath = binaryPath updated.Enabled = enabled updated.RepositoryID = repositoryID + updated.HostAPIScopes = nonNilStrings(manifest.GetHostApiScopes()) return &InstallResult{ Installation: &updated, @@ -465,11 +469,12 @@ func (i *Installer) installBinary(ctx context.Context, binaryData []byte, checks } createInput := CreateInstallationInput{ - PluginID: manifest.GetPluginId(), - Version: manifest.GetVersion(), - InstallPath: binaryPath, - Enabled: false, - Capabilities: capabilities, + PluginID: manifest.GetPluginId(), + Version: manifest.GetVersion(), + InstallPath: binaryPath, + Enabled: false, + Capabilities: capabilities, + HostAPIScopes: manifest.GetHostApiScopes(), } if repositoryID != nil { createInput.RepositoryID = *repositoryID @@ -558,11 +563,12 @@ func (i *Installer) installArchive(ctx context.Context, data []byte, req Install } createInput := CreateInstallationInput{ - PluginID: manifest.GetPluginId(), - Version: manifest.GetVersion(), - InstallPath: binaryPath, - Enabled: false, - Capabilities: capabilities, + PluginID: manifest.GetPluginId(), + Version: manifest.GetVersion(), + InstallPath: binaryPath, + Enabled: false, + Capabilities: capabilities, + HostAPIScopes: manifest.GetHostApiScopes(), } if repositoryID != nil { createInput.RepositoryID = *repositoryID diff --git a/internal/plugins/permissions.go b/internal/plugins/permissions.go new file mode 100644 index 0000000000..7ac2730630 --- /dev/null +++ b/internal/plugins/permissions.go @@ -0,0 +1,748 @@ +package plugins + +import ( + "context" + "errors" + "fmt" + "log/slog" + "slices" + "strconv" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgconn" + + "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/capability" + publicevents "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/events" + + "github.com/Silo-Server/silo-server/internal/pluginhost" + "github.com/Silo-Server/silo-server/internal/secret" +) + +// RequiredPermissions is what an installation asks an administrator to +// approve, derived from its stored capabilities and host_api_scopes. +type RequiredPermissions struct { + // EventAccess is the non-public access classes (admin, user_data) of the + // catalog events its event_consumer.v1 capabilities subscribe to. + EventAccess []string + // RequestedScopes is the manifest's host_api_scopes. + RequestedScopes []string + // RequiredScopes is the requested scopes this server can issue. + RequiredScopes []string + // UnsupportedScopes is the requested scopes this server doesn't know. + // They are never granted. + UnsupportedScopes []string +} + +// DeriveRequiredPermissions derives what an installation with these +// capabilities and host_api_scopes needs approved. knownScopes is the +// server's API key scope catalog. Every list is sorted and unique. +func DeriveRequiredPermissions(capabilities []*Capability, hostAPIScopes, knownScopes []string) RequiredPermissions { + requested := sortedUnique(hostAPIScopes) + out := RequiredPermissions{ + EventAccess: requiredEventAccess(capabilities), + RequestedScopes: requested, + RequiredScopes: []string{}, + UnsupportedScopes: []string{}, + } + for _, scope := range requested { + if slices.Contains(knownScopes, scope) { + out.RequiredScopes = append(out.RequiredScopes, scope) + } else { + out.UnsupportedScopes = append(out.UnsupportedScopes, scope) + } + } + return out +} + +// requiredEventAccess returns the non-public access classes of the catalog +// events the event_consumer.v1 capabilities subscribe to, sorted and unique. +// Names outside the catalog are never delivered, so they ask for nothing. +func requiredEventAccess(capabilities []*Capability) []string { + classes := []string{} + for _, record := range capabilities { + if record == nil || record.Type != capability.EventConsumer { + continue + } + for _, name := range subscriptionsOf(record) { + access, ok := publicevents.AccessOf(name) + if ok && access != publicevents.AccessPublic { + classes = append(classes, string(access)) + } + } + } + return sortedUnique(classes) +} + +// eventAccessApproved reports whether an event of this access class may be +// delivered to an installation whose grant approves approved. Public and +// plugin events need no approval. +func eventAccessApproved(access publicevents.Access, approved []string) bool { + return access == publicevents.AccessPublic || slices.Contains(approved, string(access)) +} + +// PermissionGrant is what an administrator approved for one installation. +type PermissionGrant struct { + InstallationID int + ApprovedEventAccess []string + ApprovedHostAPIScopes []string + // ApprovedByUserID and ApprovedAt are nil for a grant no administrator + // approved explicitly: the event access recorded when the plugin was + // installed, or carried over from before grants existed. + ApprovedByUserID *int + ApprovedAt *time.Time + // APIKeyID is nil when no key is issued, including after the key was + // revoked on the API keys page or went with its owner's account. + APIKeyID *int64 + APIKeyOwnerUserID *int + APIKeyScopes []string + UpdatedAt time.Time + + apiKeyCiphertext *string + // keyOwnerAdmin reports whether the key's account is still an enabled + // administrator. A key acts as its owner, so one whose owner was demoted + // or disabled can't do what was approved. + keyOwnerAdmin bool + // keyUnreadable marks a stored key this server can't decrypt, such as + // one sealed under an earlier SECRET_KEY. + keyUnreadable bool +} + +// HostAPIKeyUsable reports whether the grant's key can act for the plugin: +// it exists, this server can open it, and its owner is still an enabled +// administrator. An approval replaces a key that isn't usable. +func (g *PermissionGrant) HostAPIKeyUsable() bool { + return g != nil && g.APIKeyID != nil && !g.keyUnreadable && g.keyOwnerAdmin +} + +// EffectiveHostAPIScopes is the scopes the installation can use now: the +// approved scopes while their key is usable, and none otherwise. +func (g *PermissionGrant) EffectiveHostAPIScopes() []string { + if !g.HostAPIKeyUsable() { + return []string{} + } + return nonNilStrings(g.ApprovedHostAPIScopes) +} + +func (g *PermissionGrant) approvedEventAccess() []string { + if g == nil { + return []string{} + } + return nonNilStrings(g.ApprovedEventAccess) +} + +// PermissionsPending reports whether required asks for anything grant +// doesn't approve: an event access class, or a host API scope its usable key +// doesn't carry. +func PermissionsPending(required RequiredPermissions, grant *PermissionGrant) bool { + return !isSubset(required.EventAccess, grant.approvedEventAccess()) || + !isSubset(required.RequiredScopes, grant.EffectiveHostAPIScopes()) +} + +// pgExecer is the statement surface of a pool or transaction. +type pgExecer interface { + Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error) +} + +// ensurePermissionGrant records the installation's current event access as +// approved, with no host API scopes, unless it already has a grant. It runs +// with every capability write, so installing a plugin is consent to the +// events it subscribes to, and a replacement never widens an existing grant. +func ensurePermissionGrant(ctx context.Context, q pgExecer, installationID int, capabilities []*Capability) error { + if _, err := q.Exec(ctx, `INSERT INTO plugin_permission_grants (plugin_installation_id, approved_event_access) + VALUES ($1, $2) ON CONFLICT (plugin_installation_id) DO NOTHING`, + installationID, requiredEventAccess(capabilities)); err != nil { + return fmt.Errorf("recording plugin permission grant: %w", err) + } + return nil +} + +// narrowHostAPIKey keeps a replacement from leaving the plugin a key wider +// than its new manifest asks for. When the key the grant names carries a +// scope outside scopes, it deletes the key and clears the approved scopes in +// tx: the installation is keyless, and pending while it still asks for +// scopes, until an administrator approves again. A replacement that keeps or +// widens the scopes leaves the key alone, and a wider requirement waits for +// approval. The key's deletion is not audited; no administrator acts here. +func narrowHostAPIKey(ctx context.Context, tx pgx.Tx, installationID int, scopes []string) error { + grant, err := lockPermissionGrant(ctx, tx, installationID) + if err != nil { + return err + } + if grant == nil || grant.APIKeyID == nil || isSubset(grant.APIKeyScopes, scopes) { + return nil + } + if _, err := tx.Exec(ctx, `DELETE FROM api_keys WHERE id = $1`, *grant.APIKeyID); err != nil { + return fmt.Errorf("deleting the narrowed plugin host API key: %w", err) + } + if _, err := tx.Exec(ctx, `UPDATE plugin_permission_grants + SET approved_host_api_scopes = '{}', api_key_id = NULL, api_key_ciphertext = NULL, updated_at = NOW() + WHERE plugin_installation_id = $1`, installationID); err != nil { + return fmt.Errorf("clearing the narrowed plugin host API scopes: %w", err) + } + slog.InfoContext(ctx, "plugin replacement asks for fewer host API scopes; its key was deleted until an administrator approves again", + "component", "plugins", "installation_id", installationID) + return nil +} + +// EnsurePermissionGrants gives every installation without a grant one that +// approves the event access its capabilities ask for now. Installations from +// before grants existed keep the events they already received. The server +// runs it at boot, before the catalog auto-update can replace a plugin, so an +// update never reaches an installation that has no grant to hold it back. +// The reserved builtin row is skipped. It returns how many grants it wrote. +func (s *InstallationStore) EnsurePermissionGrants(ctx context.Context) (int, error) { + rows, err := s.pool.Query(ctx, `SELECT i.id FROM plugin_installations i + WHERE i.kind <> $1 AND NOT EXISTS ( + SELECT 1 FROM plugin_permission_grants g WHERE g.plugin_installation_id = i.id) + ORDER BY i.id`, KindBuiltin) + if err != nil { + return 0, fmt.Errorf("listing plugin installations without permission grants: %w", err) + } + ids, err := pgx.CollectRows(rows, pgx.RowTo[int]) + if err != nil { + return 0, fmt.Errorf("listing plugin installations without permission grants: %w", err) + } + written := 0 + for _, id := range ids { + capabilities, err := s.ListCapabilities(ctx, id) + if err != nil { + return written, err + } + tag, err := s.pool.Exec(ctx, `INSERT INTO plugin_permission_grants (plugin_installation_id, approved_event_access) + SELECT id, $2 FROM plugin_installations WHERE id = $1 + ON CONFLICT (plugin_installation_id) DO NOTHING`, id, requiredEventAccess(capabilities)) + if err != nil { + return written, fmt.Errorf("recording plugin permission grant: %w", err) + } + written += int(tag.RowsAffected()) + } + return written, nil +} + +// permissionGrantSelect reads grants with their key's owner and scopes. The +// owner counts as an administrator only with the admin role on an enabled +// account (models.RoleAdmin), what the admin routes require of a key. +const permissionGrantSelect = `SELECT g.plugin_installation_id, g.approved_event_access, g.approved_host_api_scopes, + g.approved_by_user_id, g.approved_at, g.api_key_id, g.api_key_ciphertext, g.updated_at, + k.user_id, COALESCE(k.scopes, '{}'::text[]), COALESCE(u.role = 'admin' AND u.enabled, false) + FROM plugin_permission_grants g + LEFT JOIN api_keys k ON k.id = g.api_key_id + LEFT JOIN users u ON u.id = k.user_id` + +func scanPermissionGrant(row pgx.Row) (*PermissionGrant, error) { + var grant PermissionGrant + if err := row.Scan(&grant.InstallationID, &grant.ApprovedEventAccess, &grant.ApprovedHostAPIScopes, + &grant.ApprovedByUserID, &grant.ApprovedAt, &grant.APIKeyID, &grant.apiKeyCiphertext, &grant.UpdatedAt, + &grant.APIKeyOwnerUserID, &grant.APIKeyScopes, &grant.keyOwnerAdmin); err != nil { + return nil, err + } + return &grant, nil +} + +// lockPermissionGrant locks, in tx, the key the installation's grant names +// and then the grant, and returns the grant (nil when it has none). Every +// API key deletion locks the key before the grant that names it, since the +// key's ON DELETE SET NULL writes the grant, so this order can't deadlock +// with one. errPermissionGrantChanged means the grant named another key once +// locked; the caller rolls back and starts again (retryOnGrantChange). +func lockPermissionGrant(ctx context.Context, tx pgx.Tx, installationID int) (*PermissionGrant, error) { + var named *int64 + err := tx.QueryRow(ctx, `SELECT api_key_id FROM plugin_permission_grants WHERE plugin_installation_id = $1`, installationID).Scan(&named) + if err != nil && !errors.Is(err, pgx.ErrNoRows) { + return nil, fmt.Errorf("reading plugin permission grant: %w", err) + } + if named != nil { + // A key deleted meanwhile has no row to lock; the grant then names + // none, and the comparison below starts again. + if _, err := tx.Exec(ctx, `SELECT 1 FROM api_keys WHERE id = $1 FOR UPDATE`, *named); err != nil { + return nil, fmt.Errorf("locking plugin host API key: %w", err) + } + } + grant, err := scanPermissionGrant(tx.QueryRow(ctx, permissionGrantSelect+` WHERE g.plugin_installation_id = $1 FOR UPDATE OF g`, installationID)) + if err != nil && !errors.Is(err, pgx.ErrNoRows) { + return nil, fmt.Errorf("locking plugin permission grant: %w", err) + } + var locked *int64 + if grant != nil { + locked = grant.APIKeyID + } + if !sameKeyID(named, locked) { + return nil, errPermissionGrantChanged + } + return grant, nil +} + +func sameKeyID(a, b *int64) bool { + return (a == nil && b == nil) || (a != nil && b != nil && *a == *b) +} + +// grantLockAttempts bounds how often an approval or uninstall starts again +// because the grant's key changed under it. Each restart means another +// writer committed, so running out takes a sustained stream of them. +const grantLockAttempts = 5 + +// retryOnGrantChange runs one transaction attempt until it doesn't return +// errPermissionGrantChanged, at most grantLockAttempts times. +func retryOnGrantChange(attempt func() error) error { + var err error + for range grantLockAttempts { + if err = attempt(); !errors.Is(err, errPermissionGrantChanged) { + return err + } + } + return err +} + +// PermissionGrant returns the installation's grant, or nil when it has none. +func (s *InstallationStore) PermissionGrant(ctx context.Context, installationID int) (*PermissionGrant, error) { + grant, err := scanPermissionGrant(s.pool.QueryRow(ctx, permissionGrantSelect+` WHERE g.plugin_installation_id = $1`, installationID)) + if errors.Is(err, pgx.ErrNoRows) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("reading plugin permission grant: %w", err) + } + return grant, nil +} + +// ListPermissionGrants returns every grant keyed by installation. +func (s *InstallationStore) ListPermissionGrants(ctx context.Context) (map[int]*PermissionGrant, error) { + rows, err := s.pool.Query(ctx, permissionGrantSelect) + if err != nil { + return nil, fmt.Errorf("listing plugin permission grants: %w", err) + } + defer rows.Close() + grants := map[int]*PermissionGrant{} + for rows.Next() { + grant, err := scanPermissionGrant(rows) + if err != nil { + return nil, fmt.Errorf("scanning plugin permission grant: %w", err) + } + grants[grant.InstallationID] = grant + } + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("listing plugin permission grants: %w", err) + } + return grants, nil +} + +// ApprovedEventAccess returns the event access classes each installation's +// grant approves. An installation without a grant receives only public and +// plugin events. +func (s *InstallationStore) ApprovedEventAccess(ctx context.Context) (map[int][]string, error) { + rows, err := s.pool.Query(ctx, `SELECT plugin_installation_id, approved_event_access FROM plugin_permission_grants`) + if err != nil { + return nil, fmt.Errorf("listing approved plugin event access: %w", err) + } + defer rows.Close() + approved := map[int][]string{} + for rows.Next() { + var id int + var access []string + if err := rows.Scan(&id, &access); err != nil { + return nil, fmt.Errorf("scanning approved plugin event access: %w", err) + } + approved[id] = access + } + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("listing approved plugin event access: %w", err) + } + return approved, nil +} + +// permissionApproval is one explicit approval to store. +type permissionApproval struct { + installationID int + eventAccess []string + hostAPIScopes []string + approvedBy int + // apiKeyID and apiKeyCiphertext name the key to keep; nil for none. + apiKeyID *int64 + apiKeyCiphertext *string + // previousAPIKeyID is the key the locked grant named. The write lands + // only while it still does, which matters only when there was no grant + // row to lock and a concurrent install inserted one. + previousAPIKeyID *int64 +} + +// errPermissionGrantChanged means the grant's key changed while an approval +// or uninstall held no lock on it. +var errPermissionGrantChanged = errors.New("plugin permission grant changed") + +func savePermissionApproval(ctx context.Context, tx pgx.Tx, a permissionApproval) error { + tag, err := tx.Exec(ctx, `INSERT INTO plugin_permission_grants AS g + (plugin_installation_id, approved_event_access, approved_host_api_scopes, approved_by_user_id, approved_at, api_key_id, api_key_ciphertext, updated_at) + VALUES ($1, $2, $3, $4, NOW(), $5, $6, NOW()) + ON CONFLICT (plugin_installation_id) DO UPDATE SET + approved_event_access = EXCLUDED.approved_event_access, + approved_host_api_scopes = EXCLUDED.approved_host_api_scopes, + approved_by_user_id = EXCLUDED.approved_by_user_id, + approved_at = EXCLUDED.approved_at, + api_key_id = EXCLUDED.api_key_id, + api_key_ciphertext = EXCLUDED.api_key_ciphertext, + updated_at = EXCLUDED.updated_at + WHERE g.api_key_id IS NOT DISTINCT FROM $7`, + a.installationID, nonNilStrings(a.eventAccess), nonNilStrings(a.hostAPIScopes), a.approvedBy, + a.apiKeyID, a.apiKeyCiphertext, a.previousAPIKeyID) + if err != nil { + var pgErr *pgconn.PgError + if errors.As(err, &pgErr) && pgErr.Code == "23503" { + // The installation was uninstalled meanwhile. + return ErrInstallationNotFound + } + return fmt.Errorf("saving plugin permission approval: %w", err) + } + if tag.RowsAffected() == 0 { + return errPermissionGrantChanged + } + return nil +} + +// hostAPIKeyAAD binds a stored host API key to its installation and key row, +// so a ciphertext moved to another grant, or kept after its key was +// replaced, does not open. +func hostAPIKeyAAD(installationID int, apiKeyID int64) string { + return secret.RowAAD("plugin_permission_grants", "api_key_ciphertext", + strconv.Itoa(installationID)+":"+strconv.FormatInt(apiKeyID, 10)) +} + +// HostAPIKeyIssuer mints and deletes the API keys issued to plugins inside +// the caller's transaction, so a key and the grant that names it commit or +// roll back together. The auth package implements it; plugins can't import +// auth. Each mutation returns committed, which the caller runs only after +// its transaction commits (it publishes the audit entry). +type HostAPIKeyIssuer interface { + // KnownScopes is the server's API key scope catalog. + KnownScopes() []string + // LockAccounts takes in tx the account locks IssueTx and RevokeTx take + // for actorID. A caller runs it before it locks a key or a grant, so its + // locks follow the accounts, key, grant order of every key deletion. + LockAccounts(ctx context.Context, tx pgx.Tx, actorID int) error + // IssueTx mints a key with exactly scopes on actorID's own account, + // acting as actorID. + IssueTx(ctx context.Context, tx pgx.Tx, actorID int, label string, scopes []string) (id int64, token string, committed func(), err error) + // RevokeTx deletes a key. A key that is already gone is not an error. + RevokeTx(ctx context.Context, tx pgx.Tx, id int64) (committed func(), err error) +} + +// PluginPermissions is one installation's required and approved permissions. +type PluginPermissions struct { + InstallationID int + Required RequiredPermissions + // Grant is nil for an installation that has none. + Grant *PermissionGrant + Pending bool +} + +// PermissionService approves what plugins receive and may call, issues the +// scoped host API key an approval carries, and answers plugins asking for it. +type PermissionService struct { + installations *InstallationStore + cipher *secret.Cipher + keys HostAPIKeyIssuer + // onChange runs after an approval so every API server rebuilds its event + // subscriber index. It is Service.OnLifecycleChange, which announces the + // change and restarts nothing. + onChange func(context.Context) +} + +// NewPermissionService creates the service. onChange may be nil. +func NewPermissionService(installations *InstallationStore, cipher *secret.Cipher, keys HostAPIKeyIssuer, onChange func(context.Context)) *PermissionService { + return &PermissionService{installations: installations, cipher: cipher, keys: keys, onChange: onChange} +} + +// pgQuerier is the read surface of a pool or transaction. +type pgQuerier interface { + Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) + QueryRow(ctx context.Context, sql string, args ...any) pgx.Row +} + +// required loads an installation an administrator may act on and what it +// asks for now, through q. +// Errors: ErrInstallationNotFound, ErrBuiltinInstallationImmutable. +func (p *PermissionService) required(ctx context.Context, q pgQuerier, installationID int) (*Installation, RequiredPermissions, error) { + installation, err := getInstallation(ctx, q, installationID) + if err != nil { + return nil, RequiredPermissions{}, err + } + if installation.IsBuiltin() { + return nil, RequiredPermissions{}, ErrBuiltinInstallationImmutable + } + capabilities, err := listCapabilities(ctx, q, installationID) + if err != nil { + return nil, RequiredPermissions{}, err + } + return installation, DeriveRequiredPermissions(capabilities, installation.HostAPIScopes, p.keys.KnownScopes()), nil +} + +func (p *PermissionService) pluginPermissions(installationID int, required RequiredPermissions, grant *PermissionGrant) *PluginPermissions { + p.checkKey(grant) + return &PluginPermissions{InstallationID: installationID, Required: required, Grant: grant, Pending: PermissionsPending(required, grant)} +} + +// Permissions returns the installation's required and approved permissions. +// Errors: ErrInstallationNotFound, ErrBuiltinInstallationImmutable. +func (p *PermissionService) Permissions(ctx context.Context, installationID int) (*PluginPermissions, error) { + _, required, err := p.required(ctx, p.installations.pool, installationID) + if err != nil { + return nil, err + } + grant, err := p.installations.PermissionGrant(ctx, installationID) + if err != nil { + return nil, err + } + return p.pluginPermissions(installationID, required, grant), nil +} + +// checkKey marks a grant whose stored key doesn't open, so the installation +// shows as pending and an approval replaces the key. +func (p *PermissionService) checkKey(grant *PermissionGrant) { + if grant != nil && grant.APIKeyID != nil { + grant.keyUnreadable = !p.opens(grant) + } +} + +// PendingByInstallation reports, for every installation that isn't builtin, +// whether it asks for permissions its grant doesn't approve. +func (p *PermissionService) PendingByInstallation(ctx context.Context) (map[int]bool, error) { + installations, err := p.installations.List(ctx) + if err != nil { + return nil, err + } + consumers, err := ListCapabilitiesOfType(ctx, p.installations.pool, capability.EventConsumer) + if err != nil { + return nil, err + } + byInstallation := map[int][]*Capability{} + for _, consumer := range consumers { + byInstallation[consumer.InstallationID] = append(byInstallation[consumer.InstallationID], consumer) + } + grants, err := p.installations.ListPermissionGrants(ctx) + if err != nil { + return nil, err + } + known := p.keys.KnownScopes() + pending := make(map[int]bool, len(installations)) + for _, installation := range installations { + if installation.IsBuiltin() { + continue + } + required := DeriveRequiredPermissions(byInstallation[installation.ID], installation.HostAPIScopes, known) + pending[installation.ID] = p.pluginPermissions(installation.ID, required, grants[installation.ID]).Pending + } + return pending, nil +} + +// ApprovalCheck vets an approval inside its transaction, against the +// permissions as they stand once the grant is locked. An error aborts the +// approval and Approve returns it unchanged. +type ApprovalCheck func(current *PluginPermissions) error + +// Approve approves everything the installation asks for now, as actorID. +// check, when non-nil, runs inside the approval's transaction; the API uses +// it to refuse an approval of anything other than what the administrator +// read. +// +// When the installation asks for host API scopes and has no usable key with +// exactly those, a key is minted on actorID's account. Minting it, pointing +// the grant at it, and deleting the key it replaces commit in one +// transaction, as does deleting the key when no scopes are asked for, so the +// grant always names the one live key issued to the plugin. Repeating an +// approval keeps a usable key. +// Errors: ErrInstallationNotFound, ErrBuiltinInstallationImmutable, and +// whatever check returns. +func (p *PermissionService) Approve(ctx context.Context, actorID, installationID int, check ApprovalCheck) (*PluginPermissions, error) { + var committed []func() + err := retryOnGrantChange(func() error { + var err error + committed, err = p.approve(ctx, actorID, installationID, check) + return err + }) + if err != nil { + return nil, err + } + for _, run := range committed { + run() + } + p.changed(ctx) + return p.Permissions(ctx, installationID) +} + +// approve is one attempt at Approve in its own transaction. It returns the +// hooks to run once that transaction has committed. +func (p *PermissionService) approve(ctx context.Context, actorID, installationID int, check ApprovalCheck) ([]func(), error) { + tx, err := p.installations.pool.Begin(ctx) + if err != nil { + return nil, fmt.Errorf("beginning plugin permission approval: %w", err) + } + defer func() { + cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second) + defer cancel() + _ = tx.Rollback(cleanupCtx) + }() + + // Accounts, then the grant's key, then the grant: the order every key + // deletion locks them in. + if err := p.keys.LockAccounts(ctx, tx, actorID); err != nil { + return nil, err + } + grant, err := lockPermissionGrant(ctx, tx, installationID) + if err != nil { + return nil, err + } + installation, required, err := p.required(ctx, tx, installationID) + if err != nil { + return nil, err + } + // Built even without a check: it marks a stored key that doesn't open, + // which decides whether the key is kept. + current := p.pluginPermissions(installationID, required, grant) + if check != nil { + if err := check(current); err != nil { + return nil, err + } + } + + approval := permissionApproval{ + installationID: installationID, + eventAccess: required.EventAccess, + hostAPIScopes: required.RequiredScopes, + approvedBy: actorID, + } + if grant != nil { + approval.previousAPIKeyID = grant.APIKeyID + } + keep := grant.HostAPIKeyUsable() && len(required.RequiredScopes) > 0 && + slices.Equal(sortedUnique(grant.APIKeyScopes), required.RequiredScopes) + var committed []func() + switch { + case keep: + approval.apiKeyID, approval.apiKeyCiphertext = grant.APIKeyID, grant.apiKeyCiphertext + case len(required.RequiredScopes) > 0: + if p.cipher == nil { + return nil, errors.New("plugin host API keys need the server data cipher") + } + id, token, issued, err := p.keys.IssueTx(ctx, tx, actorID, "Plugin: "+installation.PluginID, required.RequiredScopes) + if err != nil { + return nil, fmt.Errorf("issuing plugin host API key: %w", err) + } + sealed, err := p.cipher.Encrypt(token, hostAPIKeyAAD(installationID, id)) + if err != nil { + return nil, fmt.Errorf("sealing plugin host API key: %w", err) + } + approval.apiKeyID, approval.apiKeyCiphertext = &id, &sealed + committed = append(committed, issued) + } + if err := savePermissionApproval(ctx, tx, approval); err != nil { + return nil, err + } + if approval.previousAPIKeyID != nil && !keep { + // The grant no longer names it, so its ON DELETE SET NULL writes + // nothing. + revoked, err := p.keys.RevokeTx(ctx, tx, *approval.previousAPIKeyID) + if err != nil { + return nil, fmt.Errorf("revoking the replaced plugin host API key: %w", err) + } + committed = append(committed, revoked) + } + if err := tx.Commit(ctx); err != nil { + return nil, fmt.Errorf("committing plugin permission approval: %w", err) + } + return committed, nil +} + +// DeleteInstallation uninstalls the plugin as InstallationStore.Delete does, +// deleting its host API key through the issuer, as actorID, so the key's +// deletion is audited like one on the API keys page. +// Errors: ErrInstallationNotFound, ErrBuiltinInstallationImmutable. +func (p *PermissionService) DeleteInstallation(ctx context.Context, actorID, installationID int) error { + return p.installations.delete(ctx, installationID, &hostAPIKeyRevoker{keys: p.keys, actorID: actorID}) +} + +// opens reports whether the grant's stored key still decrypts. One sealed +// under an earlier SECRET_KEY doesn't, and an approval replaces it. +func (p *PermissionService) opens(grant *PermissionGrant) bool { + if p.cipher == nil || grant.APIKeyID == nil || grant.apiKeyCiphertext == nil { + return false + } + _, err := p.cipher.Decrypt(*grant.apiKeyCiphertext, hostAPIKeyAAD(grant.InstallationID, *grant.APIKeyID)) + return err == nil +} + +func (p *PermissionService) changed(ctx context.Context) { + if p.onChange != nil { + p.onChange(ctx) + } +} + +// HostAPICredential returns the host API key issued to the installation. It +// is the pluginhost.HostAPICredentialSource of the API host; installationID +// comes from the host, never from the plugin. +func (p *PermissionService) HostAPICredential(ctx context.Context, installationID int) (pluginhost.HostAPICredential, error) { + if installationID <= 0 { + return pluginhost.HostAPICredential{}, fmt.Errorf("%w: a test run of a plugin has no host API key", pluginhost.ErrHostAPINotGranted) + } + installation, err := p.installations.GetByID(ctx, installationID) + if err != nil { + return pluginhost.HostAPICredential{}, err + } + grant, err := p.installations.PermissionGrant(ctx, installationID) + if err != nil { + return pluginhost.HostAPICredential{}, err + } + if grant == nil || grant.APIKeyID == nil || grant.apiKeyCiphertext == nil { + reason := "an administrator hasn't approved this plugin's host API scopes" + switch { + case len(installation.HostAPIScopes) == 0: + reason = "the plugin's manifest declares no host_api_scopes" + case grant != nil && len(grant.ApprovedHostAPIScopes) > 0: + reason = "this plugin's host API key was revoked; an administrator must approve its permissions again" + } + return pluginhost.HostAPICredential{}, fmt.Errorf("%w: %s", pluginhost.ErrHostAPINotGranted, reason) + } + if !grant.keyOwnerAdmin { + return pluginhost.HostAPICredential{}, fmt.Errorf("%w: this plugin's host API key acts as an account that is no longer an enabled administrator; an administrator must approve its permissions again", pluginhost.ErrHostAPINotGranted) + } + if p.cipher == nil { + return pluginhost.HostAPICredential{}, errors.New("plugin host API keys need the server data cipher") + } + token, err := p.cipher.Decrypt(*grant.apiKeyCiphertext, hostAPIKeyAAD(installationID, *grant.APIKeyID)) + if err != nil { + // Sealed under another SECRET_KEY, or not this installation's. An + // approval issues a key this server can open. + slog.WarnContext(ctx, "plugin host API key does not open", "component", "plugins", "installation_id", installationID, "error", err) + return pluginhost.HostAPICredential{}, fmt.Errorf("%w: this plugin's host API key can't be read on this server; an administrator must approve its permissions again", pluginhost.ErrHostAPINotGranted) + } + return pluginhost.HostAPICredential{Token: token, Scopes: sortedUnique(grant.APIKeyScopes)}, nil +} + +func capabilityPointers(capabilities []Capability) []*Capability { + out := make([]*Capability, len(capabilities)) + for i := range capabilities { + out[i] = &capabilities[i] + } + return out +} + +func nonNilStrings(values []string) []string { + if values == nil { + return []string{} + } + return values +} + +func sortedUnique(values []string) []string { + out := slices.Clone(nonNilStrings(values)) + slices.Sort(out) + return slices.Compact(out) +} + +func isSubset(values, of []string) bool { + for _, value := range values { + if !slices.Contains(of, value) { + return false + } + } + return true +} diff --git a/internal/plugins/permissions_db_test.go b/internal/plugins/permissions_db_test.go new file mode 100644 index 0000000000..9c6b0e2ffe --- /dev/null +++ b/internal/plugins/permissions_db_test.go @@ -0,0 +1,497 @@ +package plugins_test + +import ( + "bytes" + "context" + "errors" + "fmt" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "reflect" + "slices" + "strconv" + "testing" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgxpool" + + "github.com/Silo-Server/silo-server/internal/auditmutation" + "github.com/Silo-Server/silo-server/internal/auth" + "github.com/Silo-Server/silo-server/internal/clientip" + "github.com/Silo-Server/silo-server/internal/pluginhost" + "github.com/Silo-Server/silo-server/internal/plugins" + "github.com/Silo-Server/silo-server/internal/secret" +) + +func subscriber(events ...string) plugins.Capability { + subscriptions := make([]any, 0, len(events)) + for _, event := range events { + subscriptions = append(subscriptions, event) + } + return plugins.Capability{Type: "event_consumer.v1", ID: "events", Metadata: map[string]any{"subscriptions": subscriptions}} +} + +// TestPluginPermissionGrantsPostgres covers the plugin permission grant and +// its host API key against Postgres: installing approves the events the +// plugin subscribes to and a replacement never widens that; the boot pass +// carries existing installations over; an approval mints a key acting as the +// approving admin, keeps it on a repeat, rotates it when the scopes change +// (create, save, then revoke); a replacement that narrows or drops the +// scopes deletes the key at once; a key revoked on the API keys page, one that no longer opens, or one whose owner +// lost the admin role leaves the plugin pending and the next approval +// replaces it; an approval checks what it approves inside its transaction, +// so an update landing after the read is refused; a failure before the +// approval commits leaves the previous key, still named by the grant, as the +// only one; a stored key opens only for its own installation; and +// uninstalling deletes the key with the installation and audits it. +func TestPluginPermissionGrantsPostgres(t *testing.T) { + f := newPermissionsFixture(t) + t.Run("installing approves subscribed events and a replacement never widens them", f.installApprovesEventsAndReplaceNeverWidens) + t.Run("boot pass carries over installations without a grant", f.bootPassCarriesOverInstallations) + t.Run("approval issues, keeps and rotates the host API key", f.approvalIssuesKeepsAndRotatesKey) + t.Run("an update between reading and approving is refused", f.updateBetweenReadAndApprovalIsRefused) + t.Run("a key whose owner lost the admin role is pending and replaced", f.demotedOwnersKeyIsPendingAndReplaced) + t.Run("a failure before the approval commits leaves only the previous key", f.failedRevokeLeavesOnlyThePreviousKey) + t.Run("a revoked key leaves the plugin pending and narrowed scopes revoke it", f.revokedKeyIsPendingAndDroppedScopesRevoke) + t.Run("a stored key opens only for its own installation", f.storedKeyOpensOnlyForItsInstallation) + t.Run("uninstalling deletes the host API key with the installation", f.uninstallDeletesKey) +} + +type permissionsFixture struct { + pool *pgxpool.Pool + store *plugins.InstallationStore + apiKeys *auth.APIKeyRepository + cipher *secret.Cipher + permissions *plugins.PermissionService + changes int + stamp string +} + +func newPermissionsFixture(t *testing.T) *permissionsFixture { + t.Helper() + dsn := os.Getenv("SILO_TEST_DATABASE_URL") + if dsn == "" { + t.Skip("SILO_TEST_DATABASE_URL is not set") + } + pool, err := pgxpool.New(context.Background(), dsn) + if err != nil { + t.Fatalf("connect test database: %v", err) + } + t.Cleanup(pool.Close) + cipher, err := secret.New(bytes.Repeat([]byte{7}, secret.MinMasterKeyLen)) + if err != nil { + t.Fatal(err) + } + f := &permissionsFixture{ + pool: pool, + store: plugins.NewInstallationStore(pool), + apiKeys: auth.NewAPIKeyRepository(pool), + cipher: cipher, + stamp: time.Now().UTC().Format("20060102150405.000000000"), + } + f.permissions = plugins.NewPermissionService(f.store, cipher, auth.PluginHostAPIKeys{Keys: f.apiKeys}, func(context.Context) { f.changes++ }) + return f +} + +func (f *permissionsFixture) admin(t *testing.T, name string) int { + t.Helper() + var id int + username := "plugin-permissions-" + name + "-" + f.stamp + if err := f.pool.QueryRow(t.Context(), `INSERT INTO users (username, email, password_hash, role) VALUES ($1, $2, 'x', 'admin') RETURNING id`, + username, username+"@example.test").Scan(&id); err != nil { + t.Fatalf("seed admin: %v", err) + } + t.Cleanup(func() { _, _ = f.pool.Exec(context.Background(), `DELETE FROM users WHERE id = $1`, id) }) + return id +} + +func (f *permissionsFixture) install(t *testing.T, name string, scopes []string, capabilities ...plugins.Capability) *plugins.Installation { + t.Helper() + installation, err := f.store.Create(t.Context(), plugins.CreateInstallationInput{ + PluginID: "silo.test.permissions." + name + "-" + f.stamp, Version: "1.0.0", + InstallPath: filepath.Join(t.TempDir(), "plugin"), Enabled: true, UpdatePolicy: "manual", + Capabilities: capabilities, HostAPIScopes: scopes, + }) + if err != nil { + t.Fatalf("create installation: %v", err) + } + t.Cleanup(func() { + _, _ = f.pool.Exec(context.Background(), `DELETE FROM plugin_installations WHERE id = $1`, installation.ID) + }) + return installation +} + +// replace rewrites an installation's capabilities and scopes, as an upgrade does. +func (f *permissionsFixture) replace(t *testing.T, id int, scopes []string, capabilities ...plugins.Capability) { + t.Helper() + if err := f.store.Update(t.Context(), id, plugins.UpdateInstallationInput{Capabilities: capabilities, HostAPIScopes: scopes}); err != nil { + t.Fatalf("replace installation: %v", err) + } +} + +func (f *permissionsFixture) read(t *testing.T, id int) *plugins.PluginPermissions { + t.Helper() + got, err := f.permissions.Permissions(t.Context(), id) + if err != nil { + t.Fatalf("read permissions: %v", err) + } + return got +} + +func (f *permissionsFixture) approve(t *testing.T, actor, id int) *plugins.PluginPermissions { + t.Helper() + got, err := f.permissions.Approve(t.Context(), actor, id, nil) + if err != nil { + t.Fatalf("approve: %v", err) + } + return got +} + +func (f *permissionsFixture) keyExists(t *testing.T, id int64) bool { + t.Helper() + var exists bool + if err := f.pool.QueryRow(t.Context(), `SELECT EXISTS (SELECT 1 FROM api_keys WHERE id = $1)`, id).Scan(&exists); err != nil { + t.Fatal(err) + } + return exists +} + +// pluginKeys lists the IDs of the plugin's host API keys on any account. +func (f *permissionsFixture) pluginKeys(t *testing.T, installation *plugins.Installation) []int64 { + t.Helper() + rows, err := f.pool.Query(t.Context(), `SELECT id FROM api_keys WHERE label = $1 ORDER BY id`, "Plugin: "+installation.PluginID) + if err != nil { + t.Fatal(err) + } + ids, err := pgx.CollectRows(rows, pgx.RowTo[int64]) + if err != nil { + t.Fatal(err) + } + return ids +} + +// failingRevoke is the real issuer with RevokeTx failing, as a crash or a +// lost connection between pointing the grant at a new key and deleting the +// old one would. +type failingRevoke struct{ plugins.HostAPIKeyIssuer } + +var errInjectedRevoke = errors.New("injected revoke failure") + +func (failingRevoke) RevokeTx(context.Context, pgx.Tx, int64) (func(), error) { + return nil, errInjectedRevoke +} + +func (f *permissionsFixture) exec(t *testing.T, sql string, args ...any) { + t.Helper() + if _, err := f.pool.Exec(t.Context(), sql, args...); err != nil { + t.Fatal(err) + } +} + +func (f *permissionsFixture) installApprovesEventsAndReplaceNeverWidens(t *testing.T) { + installation := f.install(t, "widen", nil, subscriber("scan.completed", "catalog.library.changed")) + got := f.read(t, installation.ID) + if got.Pending || !slices.Equal(got.Grant.ApprovedEventAccess, []string{"admin"}) || got.Grant.ApprovedAt != nil { + t.Fatalf("after install: pending=%v grant=%+v", got.Pending, got.Grant) + } + + f.replace(t, installation.ID, []string{auth.ScopeAdminMonitorRead}, subscriber("scan.completed", "notification.created")) + got = f.read(t, installation.ID) + if !got.Pending || !slices.Equal(got.Grant.ApprovedEventAccess, []string{"admin"}) { + t.Fatalf("after an upgrade asking for more: pending=%v grant=%+v", got.Pending, got.Grant) + } + approved, err := f.store.ApprovedEventAccess(t.Context()) + if err != nil { + t.Fatal(err) + } + if !slices.Equal(approved[installation.ID], []string{"admin"}) { + t.Fatalf("dispatcher sees %v, want [admin] until an administrator approves", approved[installation.ID]) + } +} + +func (f *permissionsFixture) bootPassCarriesOverInstallations(t *testing.T) { + installation := f.install(t, "boot", nil, subscriber("notification.created", "session.started")) + f.exec(t, `DELETE FROM plugin_permission_grants WHERE plugin_installation_id = $1`, installation.ID) + if got := f.read(t, installation.ID); got.Grant != nil || !got.Pending { + t.Fatalf("without a grant: pending=%v grant=%+v", got.Pending, got.Grant) + } + if _, err := f.store.EnsurePermissionGrants(t.Context()); err != nil { + t.Fatal(err) + } + got := f.read(t, installation.ID) + if got.Pending || !slices.Equal(got.Grant.ApprovedEventAccess, []string{"admin", "user_data"}) { + t.Fatalf("after the boot pass: pending=%v grant=%+v", got.Pending, got.Grant) + } + f.exec(t, `UPDATE plugin_permission_grants SET approved_event_access = '{}' WHERE plugin_installation_id = $1`, installation.ID) + if _, err := f.store.EnsurePermissionGrants(t.Context()); err != nil { + t.Fatal(err) + } + if got := f.read(t, installation.ID); len(got.Grant.ApprovedEventAccess) != 0 { + t.Fatalf("a second boot pass rewrote an existing grant: %+v", got.Grant) + } +} + +func (f *permissionsFixture) approvalIssuesKeepsAndRotatesKey(t *testing.T) { + ctx := t.Context() + first, second := f.admin(t, "first"), f.admin(t, "second") + installation := f.install(t, "keys", []string{auth.ScopeAdminMonitorRead, "admin:not-a-scope"}, subscriber("session.started")) + if _, err := f.permissions.HostAPICredential(ctx, installation.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) { + t.Fatalf("credential before approval: %v, want ErrHostAPINotGranted", err) + } + if !f.read(t, installation.ID).Pending { + t.Fatalf("an installation asking for scopes isn't pending before approval") + } + + approved := f.approve(t, first, installation.ID) + if approved.Pending || approved.Grant.APIKeyID == nil || *approved.Grant.APIKeyOwnerUserID != first || + !slices.Equal(approved.Grant.APIKeyScopes, []string{auth.ScopeAdminMonitorRead}) || *approved.Grant.ApprovedByUserID != first { + t.Fatalf("after approval: %+v", approved.Grant) + } + if !slices.Equal(approved.Required.UnsupportedScopes, []string{"admin:not-a-scope"}) { + t.Fatalf("unsupported scopes = %v", approved.Required.UnsupportedScopes) + } + issued := *approved.Grant.APIKeyID + credential, err := f.permissions.HostAPICredential(ctx, installation.ID) + if err != nil { + t.Fatalf("credential after approval: %v", err) + } + key, err := f.apiKeys.GetByKey(ctx, credential.Token) + if err != nil || key.ID != issued || key.UserID != first || !slices.Equal(credential.Scopes, []string{auth.ScopeAdminMonitorRead}) { + t.Fatalf("credential = %+v (key %+v, %v), want the issued key acting as the approving admin", credential, key, err) + } + if f.changes == 0 { + t.Fatalf("an approval did not announce a lifecycle change") + } + + // The approval's check sees exactly what a read showed while nothing + // changed in between: the API's validator is a digest of it. + seen := f.read(t, installation.ID) + again, err := f.permissions.Approve(ctx, second, installation.ID, func(current *plugins.PluginPermissions) error { + if !reflect.DeepEqual(current, seen) { + return fmt.Errorf("the approval saw %+v, the read %+v", current, seen) + } + return nil + }) + if err != nil { + t.Fatal(err) + } + if *again.Grant.APIKeyID != issued || !f.keyExists(t, issued) { + t.Fatalf("a repeat approval replaced the key: %+v", again.Grant) + } + + f.replace(t, installation.ID, []string{auth.ScopeAdminMonitorRead, auth.ScopeAdminSessionsControl}, subscriber("session.started")) + if got := f.read(t, installation.ID); !got.Pending || *got.Grant.APIKeyID != issued { + t.Fatalf("an upgrade asking for another scope: pending=%v grant=%+v", got.Pending, got.Grant) + } + if still, err := f.permissions.HostAPICredential(ctx, installation.ID); err != nil || still.Token != credential.Token { + t.Fatalf("the plugin lost its approved key while the upgrade is pending: %v", err) + } + rotated := f.approve(t, second, installation.ID) + if rotated.Pending || *rotated.Grant.APIKeyID == issued || *rotated.Grant.APIKeyOwnerUserID != second || f.keyExists(t, issued) { + t.Fatalf("rotation: grant=%+v, old key exists=%v", rotated.Grant, f.keyExists(t, issued)) + } +} + +func (f *permissionsFixture) updateBetweenReadAndApprovalIsRefused(t *testing.T) { + ctx := t.Context() + approver := f.admin(t, "stale") + installation := f.install(t, "stale", []string{auth.ScopeAdminMonitorRead}, subscriber("session.started")) + seen := f.read(t, installation.ID) + // An automatic update lands after the administrator read the panel. + f.replace(t, installation.ID, []string{auth.ScopeAdminUsers}, subscriber("session.started", "notification.created")) + + errStale := errors.New("not what the administrator read") + var checked *plugins.PluginPermissions + _, err := f.permissions.Approve(ctx, approver, installation.ID, func(current *plugins.PluginPermissions) error { + checked = current + if !slices.Equal(current.Required.RequiredScopes, seen.Required.RequiredScopes) || + !slices.Equal(current.Required.EventAccess, seen.Required.EventAccess) { + return errStale + } + return nil + }) + if !errors.Is(err, errStale) { + t.Fatalf("approving after an update: %v, want the check's error", err) + } + if checked == nil || !slices.Equal(checked.Required.RequiredScopes, []string{auth.ScopeAdminUsers}) { + t.Fatalf("the check saw %+v, want the updated requirements", checked) + } + got := f.read(t, installation.ID) + if !got.Pending || got.Grant.APIKeyID != nil || got.Grant.ApprovedAt != nil || len(f.pluginKeys(t, installation)) != 0 { + t.Fatalf("a refused approval changed the grant: %+v, keys %v", got.Grant, f.pluginKeys(t, installation)) + } + if !slices.Equal(got.Grant.ApprovedEventAccess, []string{"admin"}) { + t.Fatalf("a refused approval widened event access: %v", got.Grant.ApprovedEventAccess) + } +} + +func (f *permissionsFixture) demotedOwnersKeyIsPendingAndReplaced(t *testing.T) { + ctx := t.Context() + first, second := f.admin(t, "demoted"), f.admin(t, "successor") + installation := f.install(t, "demoted", []string{auth.ScopeAdminMonitorRead}) + issued := *f.approve(t, first, installation.ID).Grant.APIKeyID + + f.exec(t, `UPDATE users SET role = 'user' WHERE id = $1`, first) + got := f.read(t, installation.ID) + if !got.Pending || got.Grant.HostAPIKeyUsable() || len(got.Grant.EffectiveHostAPIScopes()) != 0 || *got.Grant.APIKeyID != issued { + t.Fatalf("after demoting the key's owner: pending=%v grant=%+v", got.Pending, got.Grant) + } + if _, err := f.permissions.HostAPICredential(ctx, installation.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) { + t.Fatalf("credential of a demoted owner's key: %v, want ErrHostAPINotGranted", err) + } + pending, err := f.permissions.PendingByInstallation(ctx) + if err != nil || !pending[installation.ID] { + t.Fatalf("PendingByInstallation = %v, %v; want pending", pending[installation.ID], err) + } + + replaced := f.approve(t, second, installation.ID) + if replaced.Pending || *replaced.Grant.APIKeyID == issued || *replaced.Grant.APIKeyOwnerUserID != second || f.keyExists(t, issued) { + t.Fatalf("re-approval kept the demoted owner's key: grant=%+v, old key exists=%v", replaced.Grant, f.keyExists(t, issued)) + } + + // A disabled owner is no administrator either. + f.exec(t, `UPDATE users SET enabled = false WHERE id = $1`, second) + if got := f.read(t, installation.ID); !got.Pending || got.Grant.HostAPIKeyUsable() { + t.Fatalf("after disabling the key's owner: pending=%v grant=%+v", got.Pending, got.Grant) + } +} + +func (f *permissionsFixture) failedRevokeLeavesOnlyThePreviousKey(t *testing.T) { + ctx := t.Context() + approver := f.admin(t, "crash") + installation := f.install(t, "crash", []string{auth.ScopeAdminMonitorRead}) + issued := *f.approve(t, approver, installation.ID).Grant.APIKeyID + failing := plugins.NewPermissionService(f.store, f.cipher, failingRevoke{auth.PluginHostAPIKeys{Keys: f.apiKeys}}, nil) + + // Rotation: the new key is minted and the grant points at it before the + // old key's deletion fails. + f.replace(t, installation.ID, []string{auth.ScopeAdminMonitorRead, auth.ScopeAdminSessionsControl}) + if _, err := failing.Approve(ctx, approver, installation.ID, nil); !errors.Is(err, errInjectedRevoke) { + t.Fatalf("rotation with a failing revoke: %v, want the injected failure", err) + } + got := f.read(t, installation.ID) + if keys := f.pluginKeys(t, installation); !slices.Equal(keys, []int64{issued}) || got.Grant.APIKeyID == nil || *got.Grant.APIKeyID != issued { + t.Fatalf("after a failed rotation: keys %v, grant %+v; want only the previous key, still named by the grant", keys, got.Grant) + } + if credential, err := f.permissions.HostAPICredential(ctx, installation.ID); err != nil || !slices.Equal(credential.Scopes, []string{auth.ScopeAdminMonitorRead}) { + t.Fatalf("the plugin lost its key to a failed rotation: %+v, %v", credential, err) + } + + if err := f.store.Delete(ctx, installation.ID); err != nil { + t.Fatal(err) + } + if keys := f.pluginKeys(t, installation); len(keys) != 0 { + t.Fatalf("keys outlived the uninstall: %v", keys) + } +} + +func (f *permissionsFixture) revokedKeyIsPendingAndDroppedScopesRevoke(t *testing.T) { + ctx := t.Context() + approver := f.admin(t, "revoke") + installation := f.install(t, "revoke", []string{auth.ScopeAdminMonitorRead}, subscriber("session.started")) + issued := *f.approve(t, approver, installation.ID).Grant.APIKeyID + + // Revoked on the API keys page: the plugin is pending again. + if err := f.apiKeys.DeleteByAdminConditional(ctx, issued, auth.APIKeyPrecondition{Any: true}); err != nil { + t.Fatal(err) + } + if got := f.read(t, installation.ID); !got.Pending || got.Grant.APIKeyID != nil { + t.Fatalf("after revoking the key: pending=%v grant=%+v", got.Pending, got.Grant) + } + if _, err := f.permissions.HostAPICredential(ctx, installation.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) { + t.Fatalf("credential after revocation: %v, want ErrHostAPINotGranted", err) + } + reissued := f.approve(t, approver, installation.ID) + if reissued.Grant.APIKeyID == nil { + t.Fatalf("approval after revocation issued no key: %+v", reissued.Grant) + } + + // A replacement that asks for fewer scopes deletes the wider key at once, + // without waiting for an approval; the plugin is pending for what it + // still asks for. + f.replace(t, installation.ID, []string{auth.ScopeAdminMonitorRead, auth.ScopeAdminSessionsControl}, subscriber("session.started")) + wide := *f.approve(t, approver, installation.ID).Grant.APIKeyID + f.replace(t, installation.ID, []string{auth.ScopeAdminMonitorRead}, subscriber("session.started")) + narrowed := f.read(t, installation.ID) + if !narrowed.Pending || narrowed.Grant.APIKeyID != nil || len(narrowed.Grant.ApprovedHostAPIScopes) != 0 || f.keyExists(t, wide) { + t.Fatalf("after a narrowing replacement: pending=%v grant=%+v, wide key exists=%v", narrowed.Pending, narrowed.Grant, f.keyExists(t, wide)) + } + if _, err := f.permissions.HostAPICredential(ctx, installation.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) { + t.Fatalf("credential after a narrowing replacement: %v, want ErrHostAPINotGranted", err) + } + // Dropping every scope leaves it keyless and not pending. + kept := *f.approve(t, approver, installation.ID).Grant.APIKeyID + f.replace(t, installation.ID, []string{}, subscriber("session.started")) + dropped := f.read(t, installation.ID) + if dropped.Pending || dropped.Grant.APIKeyID != nil || f.keyExists(t, kept) { + t.Fatalf("a replacement asking for no scopes kept its key: pending=%v grant=%+v", dropped.Pending, dropped.Grant) + } +} + +func (f *permissionsFixture) storedKeyOpensOnlyForItsInstallation(t *testing.T) { + ctx := t.Context() + approver := f.admin(t, "transplant") + owner := f.install(t, "owner", []string{auth.ScopeAdminMonitorRead}) + other := f.install(t, "other", []string{auth.ScopeAdminMonitorRead}) + f.approve(t, approver, owner.ID) + if _, err := f.permissions.HostAPICredential(ctx, other.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) { + t.Fatalf("another installation's credential: %v, want ErrHostAPINotGranted", err) + } + // A database writer copying the grant's key onto another row gains + // nothing: the ciphertext is bound to its installation. + const copyKey = `UPDATE plugin_permission_grants o SET api_key_id = g.api_key_id, api_key_ciphertext = g.api_key_ciphertext + FROM plugin_permission_grants g WHERE g.plugin_installation_id = $1 AND o.plugin_installation_id = $2` + f.exec(t, copyKey, owner.ID, other.ID) + if credential, err := f.permissions.HostAPICredential(ctx, other.ID); !errors.Is(err, pluginhost.ErrHostAPINotGranted) || credential.Token != "" { + t.Fatalf("a transplanted key opened for another installation: %v", err) + } + f.exec(t, `UPDATE plugin_permission_grants SET api_key_id = NULL, api_key_ciphertext = NULL WHERE plugin_installation_id = $1`, other.ID) + + // A key that no longer opens, as after a SECRET_KEY change, shows as + // pending and the next approval replaces it. + unreadable := *f.approve(t, approver, other.ID).Grant.APIKeyID + f.exec(t, `UPDATE plugin_permission_grants o SET api_key_ciphertext = g.api_key_ciphertext + FROM plugin_permission_grants g WHERE g.plugin_installation_id = $1 AND o.plugin_installation_id = $2`, owner.ID, other.ID) + if !f.read(t, other.ID).Pending { + t.Fatalf("an installation whose key doesn't open isn't pending") + } + replaced := f.approve(t, approver, other.ID) + if *replaced.Grant.APIKeyID == unreadable || f.keyExists(t, unreadable) || replaced.Pending { + t.Fatalf("approval kept a key that doesn't open: %+v", replaced.Grant) + } + if _, err := f.permissions.HostAPICredential(ctx, other.ID); err != nil { + t.Fatalf("credential after replacing the unreadable key: %v", err) + } +} + +func (f *permissionsFixture) uninstallDeletesKey(t *testing.T) { + approver := f.admin(t, "uninstall") + installation := f.install(t, "uninstall", []string{auth.ScopeAdminMonitorRead}) + keyID := *f.approve(t, approver, installation.ID).Grant.APIKeyID + t.Cleanup(func() { + _, _ = f.pool.Exec(context.Background(), `DELETE FROM activity_log WHERE target_type = $1 AND target_id = $2`, + auditmutation.TargetAPIKey, strconv.FormatInt(keyID, 10)) + }) + lc := &auditmutation.LogContext{Request: httptest.NewRequest(http.MethodDelete, + fmt.Sprintf("/api/v2/admin/plugins/installations/%d", installation.ID), nil), Started: time.Now(), UserID: &approver} + var ctx context.Context + capture := http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) { ctx = r.Context() }) //nolint:fatcontext // captures the one request context the middleware builds + clientip.Middleware(clientip.NewResolver(nil))(capture).ServeHTTP(httptest.NewRecorder(), lc.Request.WithContext(auditmutation.SetLogContext(t.Context(), lc))) + if err := f.permissions.DeleteInstallation(ctx, approver, installation.ID); err != nil { + t.Fatal(err) + } + if f.keyExists(t, keyID) { + t.Fatalf("the host API key outlived its plugin") + } + if !slices.ContainsFunc(lc.Committed, func(e auditmutation.Entry) bool { + return e.Action == auditmutation.ActionAPIKeyDeleted && e.TargetID == strconv.FormatInt(keyID, 10) + }) { + t.Fatalf("uninstalling audited %+v, want the host API key's deletion", lc.Committed) + } + if _, err := f.permissions.Approve(t.Context(), approver, installation.ID, nil); !errors.Is(err, plugins.ErrInstallationNotFound) { + t.Fatalf("approving an uninstalled plugin: %v, want ErrInstallationNotFound", err) + } +} diff --git a/internal/plugins/permissions_test.go b/internal/plugins/permissions_test.go new file mode 100644 index 0000000000..9c4bf70630 --- /dev/null +++ b/internal/plugins/permissions_test.go @@ -0,0 +1,95 @@ +package plugins + +import ( + "reflect" + "testing" +) + +func TestDeriveRequiredPermissions(t *testing.T) { + known := []string{"admin:monitor:read", "admin:sessions:control", "libraries:read"} + tests := []struct { + name string + capabilities []*Capability + scopes []string + want RequiredPermissions + grant *PermissionGrant + wantPending bool + }{ + { + name: "public and plugin events ask for nothing", + capabilities: []*Capability{eventConsumer(1, "events", "catalog.library.changed", "catalog.item.changed", "plugin.silo.other.ping")}, + want: RequiredPermissions{EventAccess: []string{}, RequestedScopes: []string{}, RequiredScopes: []string{}, UnsupportedScopes: []string{}}, + wantPending: false, + }, + { + name: "admin and user_data classes, sorted and unique across capabilities", + capabilities: []*Capability{ + eventConsumer(1, "a", "notification.created", "session.started"), + eventConsumer(1, "b", "scan.completed", "session.stopped"), + }, + want: RequiredPermissions{EventAccess: []string{"admin", "user_data"}, RequestedScopes: []string{}, RequiredScopes: []string{}, UnsupportedScopes: []string{}}, + grant: &PermissionGrant{ApprovedEventAccess: []string{"admin"}}, + wantPending: true, + }, + { + name: "an installation without a grant is pending for admin events", + capabilities: []*Capability{eventConsumer(1, "events", "job.failed")}, + want: RequiredPermissions{EventAccess: []string{"admin"}, RequestedScopes: []string{}, RequiredScopes: []string{}, UnsupportedScopes: []string{}}, + wantPending: true, + }, + { + name: "names outside the catalog and other capability types ask for nothing", + capabilities: []*Capability{ + eventConsumer(1, "events", "user_state.changed", "library.scan.completed"), + {Type: "scheduled_task.v1", ID: "sync", Metadata: map[string]any{"subscriptions": []any{"session.started"}}}, + }, + want: RequiredPermissions{EventAccess: []string{}, RequestedScopes: []string{}, RequiredScopes: []string{}, UnsupportedScopes: []string{}}, + }, + { + name: "unknown scopes are reported and never required", + capabilities: []*Capability{eventConsumer(1, "events", "session.started")}, + scopes: []string{"admin:monitor:read", "admin:everything", "admin:monitor:read", "libraries:read"}, + want: RequiredPermissions{ + EventAccess: []string{"admin"}, + RequestedScopes: []string{"admin:everything", "admin:monitor:read", "libraries:read"}, + RequiredScopes: []string{"admin:monitor:read", "libraries:read"}, + UnsupportedScopes: []string{"admin:everything"}, + }, + grant: &PermissionGrant{ApprovedEventAccess: []string{"admin"}, ApprovedHostAPIScopes: []string{"admin:monitor:read", "libraries:read"}, + APIKeyID: new(int64(9)), keyOwnerAdmin: true}, + wantPending: false, + }, + { + name: "approved scopes whose key's owner is no longer an enabled admin are pending again", + scopes: []string{"admin:monitor:read"}, + want: RequiredPermissions{EventAccess: []string{}, RequestedScopes: []string{"admin:monitor:read"}, RequiredScopes: []string{"admin:monitor:read"}, UnsupportedScopes: []string{}}, + grant: &PermissionGrant{ApprovedHostAPIScopes: []string{"admin:monitor:read"}, + APIKeyID: new(int64(9)), keyOwnerAdmin: false}, + wantPending: true, + }, + { + name: "approved scopes whose key was revoked are pending again", + scopes: []string{"admin:monitor:read"}, + want: RequiredPermissions{EventAccess: []string{}, RequestedScopes: []string{"admin:monitor:read"}, RequiredScopes: []string{"admin:monitor:read"}, UnsupportedScopes: []string{}}, + grant: &PermissionGrant{ApprovedHostAPIScopes: []string{"admin:monitor:read"}}, + wantPending: true, + }, + { + name: "only unknown scopes leave nothing pending", + scopes: []string{"admin:everything"}, + want: RequiredPermissions{EventAccess: []string{}, RequestedScopes: []string{"admin:everything"}, RequiredScopes: []string{}, UnsupportedScopes: []string{"admin:everything"}}, + wantPending: false, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := DeriveRequiredPermissions(tt.capabilities, tt.scopes, known) + if !reflect.DeepEqual(got, tt.want) { + t.Fatalf("DeriveRequiredPermissions = %+v, want %+v", got, tt.want) + } + if pending := PermissionsPending(got, tt.grant); pending != tt.wantPending { + t.Fatalf("PermissionsPending = %v, want %v", pending, tt.wantPending) + } + }) + } +} diff --git a/internal/plugins/service.go b/internal/plugins/service.go index 4486ccc0a1..0b5d9fadf6 100644 --- a/internal/plugins/service.go +++ b/internal/plugins/service.go @@ -105,6 +105,10 @@ type Service struct { networkAccessStatus NetworkAccessStatusSink networkAccessNodes NetworkAccessNodes + // permissions approves what plugins receive and may call; see + // SetPermissions. + permissions *PermissionService + // installationCache memoizes plugin_installations rows keyed by ID so the // hot plugin-RPC path (ensureClient -> loadInstallation) and the metadata // chain enabled-check answer from memory instead of a per-call DB read. It @@ -137,6 +141,23 @@ func (s *Service) SetEventDispatcher(d *EventDispatcher) { } } +// SetPermissions wires the plugin permission service the admin API reads +// and approves through. +func (s *Service) SetPermissions(p *PermissionService) { + if s != nil { + s.permissions = p + } +} + +// Permissions returns the plugin permission service, or nil when none is +// wired. +func (s *Service) Permissions() *PermissionService { + if s == nil { + return nil + } + return s.permissions +} + // AddLifecycleHook registers a callback invoked after plugin install, enable, // disable, uninstall, preload, or runtime-configuration changes. func (s *Service) AddLifecycleHook(hook func(context.Context)) { diff --git a/migrations/sql/20261104202747_add_plugin_permission_grants.sql b/migrations/sql/20261104202747_add_plugin_permission_grants.sql new file mode 100644 index 0000000000..9cbde0b2cb --- /dev/null +++ b/migrations/sql/20261104202747_add_plugin_permission_grants.sql @@ -0,0 +1,30 @@ +-- +goose Up +-- host_api_scopes is the API key scopes the installed manifest asks for. The +-- manifest itself is not stored in a column, so the installer writes this +-- wherever it writes plugin_capabilities. +ALTER TABLE public.plugin_installations + ADD COLUMN host_api_scopes text[] NOT NULL DEFAULT '{}'; + +-- What an administrator approved for one installation: the event access +-- classes it receives and the host API scopes its issued key carries. +-- api_key_id and api_key_ciphertext name that key; deleting the key (on the +-- API keys page, or with its owner's account) leaves the grant without one. +-- api_key_ciphertext is an enc:v1 envelope bound to the installation and key. +CREATE TABLE public.plugin_permission_grants ( + plugin_installation_id bigint PRIMARY KEY REFERENCES public.plugin_installations(id) ON DELETE CASCADE, + approved_event_access text[] NOT NULL DEFAULT '{}', + approved_host_api_scopes text[] NOT NULL DEFAULT '{}', + approved_by_user_id integer REFERENCES public.users(id) ON DELETE SET NULL, + approved_at timestamptz, + api_key_id bigint REFERENCES public.api_keys(id) ON DELETE SET NULL, + api_key_ciphertext text, + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE INDEX idx_plugin_permission_grants_api_key + ON public.plugin_permission_grants (api_key_id) + WHERE api_key_id IS NOT NULL; + +-- +goose Down +DROP TABLE IF EXISTS public.plugin_permission_grants; +ALTER TABLE public.plugin_installations DROP COLUMN IF EXISTS host_api_scopes; diff --git a/scripts/ci/db-contracts.txt b/scripts/ci/db-contracts.txt index bc7e863c31..daa0f2500a 100644 --- a/scripts/ci/db-contracts.txt +++ b/scripts/ci/db-contracts.txt @@ -516,6 +516,12 @@ # and only the latest claim records the outcome. ./internal/plugins TestEventDeliveryOutboxPostgres +# Plugin permissions: installing approves the events a plugin subscribes to, an +# upgrade never widens that, the boot pass carries existing installations over, +# an approval issues, keeps, rotates and revokes the host API key, a stored key +# opens only for its own installation, and uninstalling deletes the key. +./internal/plugins TestPluginPermissionGrantsPostgres + # A row whose plugin ID or version is "." or ".." never loads. Uninstall drops # the row and leaves its files, which can sit above the plugin root, and the # installation and user settings lists still answer with the row present. diff --git a/web/src/api/types.ts b/web/src/api/types.ts index 45eff2cff2..26798715ef 100644 --- a/web/src/api/types.ts +++ b/web/src/api/types.ts @@ -4085,6 +4085,8 @@ export interface PluginInstallation { repo_url?: string; presentation?: PluginPresentation; updates_paused: boolean; + /** True while the plugin asks for event access or API key scopes not yet approved. */ + permissions_pending?: boolean; legacy_metadata_import_types?: string[]; created_at?: string; updated_at?: string; diff --git a/web/src/api/v2/operations.ts b/web/src/api/v2/operations.ts index 56179028fd..273deb988b 100644 --- a/web/src/api/v2/operations.ts +++ b/web/src/api/v2/operations.ts @@ -224,6 +224,8 @@ export const v2Operations = { "GET /api/v2/admin/plugins/catalog-settings": "getAdminPluginCatalogSettings", "GET /api/v2/admin/plugins/catalog-status": "getAdminPluginCatalogStatus", "GET /api/v2/admin/plugins/installations": "listAdminPluginInstallations", + "GET /api/v2/admin/plugins/installations/{id}/permissions": + "getAdminPluginInstallationPermissions", "GET /api/v2/admin/plugins/repositories": "listAdminPluginRepositories", "GET /api/v2/admin/policy/decisions": "listAdminPolicyDecisions", "GET /api/v2/admin/policy/decisions/{id}": "getAdminPolicyDecision", @@ -920,6 +922,8 @@ export const v2Operations = { "PUT /api/v2/admin/plugins/installations/{id}": "updateAdminPluginInstallation", "PUT /api/v2/admin/plugins/installations/{id}/auth-binding": "updateAdminPluginAuthBinding", "PUT /api/v2/admin/plugins/installations/{id}/config": "updateAdminPluginInstallationConfig", + "PUT /api/v2/admin/plugins/installations/{id}/permissions/approval": + "approveAdminPluginInstallationPermissions", "PUT /api/v2/admin/plugins/installations/{id}/task-bindings/{capability_id}": "updateAdminPluginTaskBinding", "PUT /api/v2/admin/plugins/repositories/{id}": "updateAdminPluginRepository", diff --git a/web/src/api/v2/schema.ts b/web/src/api/v2/schema.ts index d86958f59f..a732e3f713 100644 --- a/web/src/api/v2/schema.ts +++ b/web/src/api/v2/schema.ts @@ -3961,6 +3961,40 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v2/admin/plugins/installations/{id}/permissions": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Read what one installation asks to receive and call, and what an administrator approved: the event access classes its subscriptions need, the host API scopes its manifest requests, and the host API key issued for them. The key itself is never returned. The ETag validates the whole representation; approving requires it. The reserved builtin row is 409. */ + get: operations["getAdminPluginInstallationPermissions"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/v2/admin/plugins/installations/{id}/permissions/approval": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + /** Approve everything the installation asks for now, as the acting administrator. If-Match must carry the ETag of the permissions read the administrator approved; the server compares it with the permissions inside the approval's transaction, so a plugin update that asks for more, or another approval, landing in between is 412 with the current ETag and changes nothing. When the installation requests host API scopes this server knows and has no usable key with exactly those, a key acting as the acting administrator is issued and the previous key revoked in the same transaction; when it requests none, its key is revoked. The event subscriber index rebuilds on every server; the plugin is not restarted. */ + put: operations["approveAdminPluginInstallationPermissions"]; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v2/admin/plugins/installations/{id}/restart": { parameters: { query?: never; @@ -19881,6 +19915,12 @@ export interface components { message: string; success: boolean; }; + AdminPluginEventAccess: { + /** @description Access classes an administrator approved. The plugin receives events of these classes and of no others that need approval. */ + approved: ("admin" | "user_data")[]; + /** @description Access classes of the events the plugin subscribes to that need approval: admin (server operations such as playback activity, scans and jobs) and user_data (one profile's personal data, such as its notifications). Public and plugin events need none. The vocabulary is open: ignore a class you don't know. */ + required: ("admin" | "user_data")[]; + }; AdminPluginForm: { fields: components["schemas"]["AdminPluginFormField"][]; sections: components["schemas"]["AdminPluginFormSection"][]; @@ -19927,6 +19967,32 @@ export interface components { min_length: number; pattern?: string; }; + AdminPluginHostAPIKey: { + /** + * @description The key on the API keys page, where it can be revoked; omitted while none is issued + * @example 1 + */ + id?: string; + /** @description True while a host API key is issued to the plugin */ + issued: boolean; + /** + * @description The account the key acts as: the administrator whose approval issued it. It stops working if that account loses the admin role or is disabled, and is deleted with the account. Omitted while none is issued + * @example 1 + */ + owner_user_id?: string; + /** @description True while the issued key can act for the plugin. False when none is issued, when the account it acts as is no longer an enabled administrator, or when this server can't read it (it was stored under another SECRET_KEY). An unusable key grants nothing: the plugin is pending and an approval issues a replacement */ + usable: boolean; + }; + AdminPluginHostAPIScopes: { + /** @description Scopes the plugin's usable host API key carries; empty while none is usable, including after the key was revoked or its account lost the admin role */ + approved: string[]; + /** @description The manifest's host_api_scopes */ + requested: string[]; + /** @description The requested scopes this server can issue */ + required: string[]; + /** @description The requested scopes this server doesn't know; they are never granted */ + unsupported: string[]; + }; AdminPluginInstallation: { assets: components["schemas"]["PluginAsset"][]; auth_bindings: components["schemas"]["AdminPluginAuthBinding"][]; @@ -19950,6 +20016,8 @@ export interface components { metadata: { [key: string]: unknown; }; + /** @description True while the installation asks for event access or host API scopes an administrator hasn't approved; see getAdminPluginInstallationPermissions */ + permissions_pending: boolean; plugin_id: string; presentation?: components["schemas"]["AdminPluginPresentation"]; /** Format: uri-reference */ @@ -19995,6 +20063,28 @@ export interface components { repository_id?: string; version?: string; }; + AdminPluginPermissions: { + /** + * Format: date-time + * @description The last explicit approval; omitted when none was given, such as when event access was approved by installing the plugin + */ + approved_at?: string; + /** + * @description The administrator who gave the last explicit approval; omitted when none was given or the account was deleted + * @example 1 + */ + approved_by_user_id?: string; + event_access: components["schemas"]["AdminPluginEventAccess"]; + host_api_key: components["schemas"]["AdminPluginHostAPIKey"]; + host_api_scopes: components["schemas"]["AdminPluginHostAPIScopes"]; + /** + * @description Opaque identifier + * @example 1 + */ + installation_id: string; + /** @description True while the plugin asks for event access or host API scopes that aren't approved. It keeps what was approved before until an administrator approves the rest */ + pending: boolean; + }; AdminPluginPresentation: { /** Format: uri-reference */ changelog_url: string; @@ -72030,6 +72120,293 @@ export interface operations { }; }; }; + getAdminPluginInstallationPermissions: { + parameters: { + query?: never; + header?: { + /** @description Optional first precondition, evaluated before If-None-Match: a tag that does not match the current representation is 412 precondition_failed. */ + "If-Match"?: string; + "If-None-Match"?: string; + /** @description Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted. */ + "X-Profile-Id"?: string; + /** @description Verification proof for a PIN-locked profile, issued by POST /api/v2/profiles/{id}/verify-pin; required only when the declared profile is locked */ + "X-Profile-Token"?: string; + }; + path: { + /** @description Opaque identifier */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + /** @description The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read. */ + ETag?: string; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["AdminPluginPermissions"]; + }; + }; + /** @description The representation named by If-None-Match is current; no body. */ + 304: { + headers: { + /** @description The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read. */ + ETag?: string; + [name: string]: unknown; + }; + content?: never; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Unauthorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Forbidden */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Not Found */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Not Acceptable */ + 406: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Conflict */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Precondition Failed */ + 412: { + headers: { + /** @description The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read. */ + ETag?: string; + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Unprocessable Entity */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Too Many Requests */ + 429: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Service Unavailable */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + }; + }; + approveAdminPluginInstallationPermissions: { + parameters: { + query?: never; + header: { + /** @description The resource's current ETag, or "*" to overwrite deliberately. A missing field is 428 precondition_required; a stale tag is 412 precondition_failed with the current ETag. */ + "If-Match": string; + /** @description Optional second precondition, evaluated after If-Match succeeds: "*" or any tag matching the current representation is 412 precondition_failed with the current ETag. */ + "If-None-Match"?: string; + /** @description Optional. When present, it must name the authenticated account's primary profile; an absent header is accepted. */ + "X-Profile-Id"?: string; + /** @description Verification proof for a PIN-locked profile, issued by POST /api/v2/profiles/{id}/verify-pin; required only when the declared profile is locked */ + "X-Profile-Token"?: string; + }; + path: { + /** @description Opaque identifier */ + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + /** @description The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read. */ + ETag?: string; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["AdminPluginPermissions"]; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Unauthorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Forbidden */ + 403: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Not Found */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Not Acceptable */ + 406: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Conflict */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Precondition Failed */ + 412: { + headers: { + /** @description The strong, opaque validator of the representation; send it back in If-Match on a guarded mutation or If-None-Match on a conditional read. */ + ETag?: string; + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Unprocessable Entity */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Precondition Required */ + 428: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Too Many Requests */ + 429: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + /** @description Service Unavailable */ + 503: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["Problem"]; + }; + }; + }; + }; restartAdminPluginInstallation: { parameters: { query?: never; diff --git a/web/src/components/admin/plugins/PluginPermissionsPanel.tsx b/web/src/components/admin/plugins/PluginPermissionsPanel.tsx new file mode 100644 index 0000000000..443020920b --- /dev/null +++ b/web/src/components/admin/plugins/PluginPermissionsPanel.tsx @@ -0,0 +1,184 @@ +import { Check, CircleAlert } from "lucide-react"; + +import ViewTransitionLink from "@/components/ViewTransitionLink"; +import { Badge } from "@/components/ui/badge"; +import { Button } from "@/components/ui/button"; +import { + useAdminPluginPermissions, + useApprovePluginPermissions, + type PluginPermissions, +} from "@/hooks/queries/admin/plugins"; + +import { DetailPanel } from "./PluginDetailSections"; + +export const PLUGIN_PERMISSIONS_PANEL_ID = "plugin-permissions"; + +const EVENT_ACCESS: Record = { + admin: { + label: "Admin activity", + detail: + "Playback sessions, library scans and admin jobs, including the accounts, devices and network addresses they name.", + }, + user_data: { + label: "Profiles' personal data", + detail: "The notifications Silo adds to each profile's inbox.", + }, +}; + +function sameScopes(a: string[], b: string[]): boolean { + return a.length === b.length && a.every((scope) => b.includes(scope)); +} + +/** Whether a key with exactly the required scopes is already issued. */ +function keyMatches(permissions: PluginPermissions): boolean { + const scopes = permissions.host_api_scopes; + return permissions.host_api_key.issued && sameScopes(scopes.approved, scopes.required); +} + +/** The approval can change something: the plugin asks for more, or its key carries other scopes. */ +function approvalAvailable(permissions: PluginPermissions): boolean { + return permissions.pending || (permissions.host_api_key.issued && !keyMatches(permissions)); +} + +function ApprovalState({ approved }: { approved: boolean }) { + return approved ? ( + + + ) : ( + + + ); +} + +/** + * What an installed plugin receives and may call on this server, with an + * Approve button while it asks for more than an administrator approved. + * Renders nothing for a plugin that asks for nothing. + */ +export function PluginPermissionsPanel({ installationId }: { installationId: number }) { + const query = useAdminPluginPermissions(installationId); + const approve = useApprovePluginPermissions(); + const permissions = query.data; + + if (query.isError) { + return ( + + ); + } + if (!permissions) return null; + + const events = permissions.event_access; + const scopes = permissions.host_api_scopes; + const key = permissions.host_api_key; + if (events.required.length === 0 && scopes.requested.length === 0 && !key.issued) return null; + + const canApprove = approvalAvailable(permissions); + const issuesKey = canApprove && scopes.required.length > 0 && !keyMatches(permissions); + + return ( + + Needs approval + + ) : null + } + description={ + permissions.pending + ? "This plugin asks for more than you've approved. Until you approve, it keeps only what was approved before." + : "What this plugin receives from Silo and what it can call on this server." + } + > +
    + {events.required.map((access) => { + const known = EVENT_ACCESS[access]; + return ( +
  • +
    +

    {known?.label ?? access}

    + {known ?

    {known.detail}

    : null} +
    + +
  • + ); + })} + {scopes.required.length > 0 || key.issued ? ( +
  • +
    +

    API access

    +

    + An API key with these scopes, which acts as the administrator who approved it. It + appears on the{" "} + + API keys page + + , where you can revoke it. +

    +
    +
      + {[...new Set([...scopes.required, ...scopes.approved])].map((scope) => ( +
    • + {scope} + {scopes.required.includes(scope) ? ( + + ) : ( + + No longer requested + + )} +
    • + ))} +
    + {key.issued && !key.usable ? ( +

    + The plugin's API key no longer works: the account it acts as is no longer an enabled + administrator, or this server can't read it. Approving issues a new key. +

    + ) : null} +
  • + ) : null} +
+ + {scopes.unsupported.length > 0 ? ( +

+ This server doesn't offer{" "} + {scopes.unsupported.map((scope, index) => ( + + {index > 0 ? ", " : null} + {scope} + + ))} + , so the plugin won't get {scopes.unsupported.length === 1 ? "it" : "them"}. +

+ ) : null} + + {canApprove ? ( +
+ + {issuesKey ? ( + + Approving issues an API key that acts as your account. + + ) : null} +
+ ) : null} +
+ ); +} diff --git a/web/src/components/admin/plugins/PluginTile.tsx b/web/src/components/admin/plugins/PluginTile.tsx index 1f13d0f28f..2fcf4cbe98 100644 --- a/web/src/components/admin/plugins/PluginTile.tsx +++ b/web/src/components/admin/plugins/PluginTile.tsx @@ -1,6 +1,6 @@ import { useRef, useState } from "react"; import type { ReactNode, Ref } from "react"; -import { Check, Download } from "lucide-react"; +import { Check, Download, ShieldAlert } from "lucide-react"; import { useLocation } from "react-router"; import type { PluginCatalogEntry, PluginInstallation } from "@/api/types"; @@ -141,7 +141,12 @@ export function InstalledPluginTile({ {pluginSummary(presentation, capabilities)} - {updateVersion ? ( + {installation.permissions_pending ? ( + + + ) : updateVersion ? (