From a1dc0bdcd87b711426929b0c4b16c2113e130147 Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Wed, 4 Nov 2026 15:16:49 -0500 Subject: [PATCH 01/12] fix(plugins): deliver only catalog events to plugins, in their public shape Plugins received every hub envelope and every catalog, admin and playback bus event by name, with the host's internal payloads. Internal names and fields became an accidental plugin contract, and per-profile events such as user_state.changed reached any plugin that asked. Deliver only the events in the SDK's catalog and plugin events. Rewrite each payload into its catalog shape with events.Project, and add the account to notification.created, since profile IDs repeat across accounts. No catalog event travels on the Redis bus, so the bus observer and cache.ObservedEventBus go away. TestEventCatalogMatchesProducers projects what each producer publishes into the SDK payload type. Co-Authored-By: Claude Opus 5.5 --- cmd/silo/main.go | 5 +- docs/architecture/plugin-event-delivery.md | 69 +++++--- docs/architecture/redis-event-bus.md | 6 +- go.mod | 2 +- go.sum | 2 + internal/cache/observed_bus.go | 45 ----- internal/cache/observed_bus_test.go | 28 ---- .../plugins/event_catalog_contract_test.go | 155 ++++++++++++++++++ internal/plugins/event_dispatcher.go | 91 +++++----- .../plugins/event_dispatcher_delivery_test.go | 96 ++++++----- .../plugins/event_dispatcher_index_test.go | 67 ++++---- internal/plugins/event_dispatcher_test.go | 77 ++++----- 12 files changed, 364 insertions(+), 279 deletions(-) delete mode 100644 internal/cache/observed_bus.go delete mode 100644 internal/cache/observed_bus_test.go create mode 100644 internal/plugins/event_catalog_contract_test.go diff --git a/cmd/silo/main.go b/cmd/silo/main.go index 5d008d87f4..60e1f47845 100644 --- a/cmd/silo/main.go +++ b/cmd/silo/main.go @@ -1139,9 +1139,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: @@ -2113,7 +2111,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/docs/architecture/plugin-event-delivery.md b/docs/architecture/plugin-event-delivery.md index 99d69f1455..adee32d4e1 100644 --- a/docs/architecture/plugin-event-delivery.md +++ b/docs/architecture/plugin-event-delivery.md @@ -13,22 +13,36 @@ 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. + +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. + +Before an event is stored, `events.Project` rewrites its 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. `notification.created` also gets the +envelope's `user_id`, because profile IDs repeat across accounts. + +`TestEventCatalogMatchesProducers` projects what each producer publishes and +fails when a producer change drops 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`. ## Outbox @@ -64,6 +78,9 @@ 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. - 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 +97,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 +111,11 @@ 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 and unprojected payloads until they are replaced. ## 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/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/go.mod b/go.mod index 9998887bbd..00211ea02f 100644 --- a/go.mod +++ b/go.mod @@ -132,7 +132,7 @@ require ( ) require ( - github.com/Silo-Server/silo-plugin-sdk v0.31.0 + github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104200906-c24da309e4a1 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 1ca780bf55..78466539c3 100644 --- a/go.sum +++ b/go.sum @@ -10,6 +10,8 @@ github.com/SherClockHolmes/webpush-go v1.4.0 h1:ocnzNKWN23T9nvHi6IfyrQjkIc0oJWv1 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.20261104200906-c24da309e4a1 h1:gPAShJd40bM9GKjsQag/zYXo+HYmam8uWztgVaSk/Ek= +github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104200906-c24da309e4a1/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/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/plugins/event_catalog_contract_test.go b/internal/plugins/event_catalog_contract_test.go new file mode 100644 index 0000000000..2137197326 --- /dev/null +++ b/internal/plugins/event_catalog_contract_test.go @@ -0,0 +1,155 @@ +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" +) + +// TestEventCatalogMatchesProducers projects what each producer of a catalog +// event actually publishes into the SDK's public payload type, and checks a +// field the producer set survives. 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 + published := publishedByNotificationsHub(t) + + scan := func(status string) []byte { + return 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 := 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 := 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 := mustJSON(t, notifications.PayloadForRow(notifications.DeliveryRow{ + Delivery: notifications.Delivery{ID: "d1", Type: "episode.available", UserID: 7, ProfileID: "p1", CreatedAt: at}, + SeriesTitle: "Severance", SeasonNumber: &season, + })) + + cases := map[string]struct { + raw []byte + 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 { + return p.(*publicevents.ItemChanged).ContentID == "c1" && p.(*publicevents.ItemChanged).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}, + publicevents.JobCreated: {published[publicevents.JobFailed], jobCheck}, + 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.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.raw) == 0 { + t.Errorf("%s: the producer published nothing", definition.Name) + continue + } + projected, err := publicevents.Project(definition.Name, tc.raw) + 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" +} + +// publishedByNotificationsHub runs the catalog and job publishers that build +// their payloads internally and returns each envelope's data by event name. +func publishedByNotificationsHub(t *testing.T) map[string][]byte { + 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) + job := &models.AdminJob{ID: "j1", JobType: "library_refresh", Status: "failed", ErrorMessage: "boom", + RequestPayload: json.RawMessage(`{"library_id":7}`), RequestedAt: now, UpdatedAt: now} + if err := hub.PublishJob(ctx, notifications.TypeJobFailed, job); err != nil { + t.Fatal(err) + } + + out := map[string][]byte{} + for { + select { + case env := <-envelopes: + if _, seen := out[env.Event]; !seen { + out[env.Event] = env.Data + } + 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..168d71e399 100644 --- a/internal/plugins/event_dispatcher.go +++ b/internal/plugins/event_dispatcher.go @@ -9,10 +9,10 @@ import ( "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 +86,12 @@ 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). Each +// payload is rewritten into its catalog shape 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 @@ -207,8 +203,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) { @@ -263,20 +258,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 +267,36 @@ 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 { 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. A notification names only its profile, and profile IDs repeat +// across accounts, so the account the envelope is addressed to is added. +func publicPayload(env events.Envelope) *structpb.Struct { + raw := env.Data + if env.Event == publicevents.NotificationCreated && env.UserID > 0 { + var fields map[string]any + if err := json.Unmarshal(raw, &fields); err == nil && fields != nil { + fields["user_id"] = env.UserID + if withUser, err := json.Marshal(fields); err == nil { + raw = withUser + } + } + } + projected, err := publicevents.Project(env.Event, raw) + if err != nil { + slog.Warn("plugin event dispatcher: payload doesn't match the event catalog, event not delivered to plugins", "component", "plugins", "event_name", env.Event, "event_id", env.EventID, "error", err) + return nil } + return decodeRawJSON(projected) } // consumeHub reads until Stop unsubscribes, so envelopes published while the @@ -370,24 +366,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 @@ -507,6 +485,11 @@ 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. + if _, deliverable := publicevents.AccessOf(eventName); !deliverable { + 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..13baf92571 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 != float64(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,38 @@ 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) { +// 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() - 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.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) + 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 +289,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 +301,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 +329,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 +337,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 +355,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 +388,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..23bb465e9f 100644 --- a/internal/plugins/event_dispatcher_index_test.go +++ b/internal/plugins/event_dispatcher_index_test.go @@ -97,7 +97,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 +148,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 +165,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 +180,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 +195,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 +212,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 +249,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 +280,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 +348,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 +387,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 +408,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 +418,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 +438,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 +499,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 +513,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) diff --git a/internal/plugins/event_dispatcher_test.go b/internal/plugins/event_dispatcher_test.go index 1026cc7c42..a35c404db2 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) @@ -257,13 +262,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 +288,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 +314,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, 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","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"] != float64(7) || payload["profile_id"] != "p1" || payload["series_title"] != "Severance" { + t.Fatalf("payload = %v, want the account, profile and title", 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) + } + } +} From 9a32f459a73969708f8442ec277f78668f0f7794 Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Wed, 4 Nov 2026 15:49:22 -0500 Subject: [PATCH 02/12] feat(plugins): tell plugins about media request lifecycle events Plugins that alert administrators about new requests had no event to subscribe to: request lifecycle transitions only reached server channels and the requester's inbox. Publish request.submitted, request.approved, request.declined and request.fulfilled from the same calls that post to server channels, in the SDK catalog's RequestEvent shape, on the plugin channel with admin access. Co-Authored-By: Claude Opus 5.5 --- docs/architecture/plugin-event-delivery.md | 6 +++ go.mod | 2 +- go.sum | 6 +-- internal/notifications/request_events.go | 50 +++++++++++++++++++ internal/notifications/request_notifier.go | 6 +++ .../notifications/request_notifier_test.go | 2 + internal/notifications/system.go | 4 ++ .../plugins/event_catalog_contract_test.go | 35 ++++++++++--- internal/requests/follows_test.go | 4 ++ internal/requests/notify.go | 2 + internal/requests/notify_test.go | 5 +- 11 files changed, 108 insertions(+), 14 deletions(-) create mode 100644 internal/notifications/request_events.go diff --git a/docs/architecture/plugin-event-delivery.md b/docs/architecture/plugin-event-delivery.md index adee32d4e1..fc61a1e1f7 100644 --- a/docs/architecture/plugin-event-delivery.md +++ b/docs/architecture/plugin-event-delivery.md @@ -36,6 +36,12 @@ A field the host adds for its own clients therefore stays off the plugin contract until the SDK type adds it. `notification.created` also gets the envelope's `user_id`, because profile IDs repeat across accounts. +Request lifecycle events (`request.submitted`, `.approved`, `.declined`, +`.fulfilled`) exist only for plugins: `notifications.System` publishes them +on `ChannelPlugins`, which no websocket client receives, beside the +server-channel post for the same transition. Their event ID is derived from +the request and its last update, so a repeated call carries the same ID. + `TestEventCatalogMatchesProducers` projects what each producer publishes and fails when a producer change drops a catalog field, or when the SDK catalog gains an event without a producer case. diff --git a/go.mod b/go.mod index 00211ea02f..dd569be969 100644 --- a/go.mod +++ b/go.mod @@ -132,7 +132,7 @@ require ( ) require ( - github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104200906-c24da309e4a1 + github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104213721-6aed6cd5d07d 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 78466539c3..d277508902 100644 --- a/go.sum +++ b/go.sum @@ -8,10 +8,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.20261104200906-c24da309e4a1 h1:gPAShJd40bM9GKjsQag/zYXo+HYmam8uWztgVaSk/Ek= -github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104200906-c24da309e4a1/go.mod h1:+r4X2TAiB9Gk22sUj1gFWUj65lll1P1/dMS+Ncvy3Y0= +github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104213721-6aed6cd5d07d h1:0TmS3KhI9kbHfWaiQcYBZ6u4JNSx7NQlT5g6rmn6mt4= +github.com/Silo-Server/silo-plugin-sdk v0.32.2-0.20261104213721-6aed6cd5d07d/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/notifications/request_events.go b/internal/notifications/request_events.go new file mode 100644 index 0000000000..eeb5ddf3b6 --- /dev/null +++ b/internal/notifications/request_events.go @@ -0,0 +1,50 @@ +package notifications + +import ( + "context" + "fmt" + + publicevents "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/events" + + evt "github.com/Silo-Server/silo-server/internal/events" + "github.com/Silo-Server/silo-server/internal/requests" +) + +// RequestEventPayload renders a request in the plugin event catalog's +// RequestEvent shape: what plugins receive for a request lifecycle event. +func RequestEventPayload(req requests.Request) publicevents.RequestEvent { + return publicevents.RequestEvent{ + ID: req.ID, + MediaType: string(req.MediaType), + Title: req.Title, + Year: req.Year, + TMDBID: req.TMDBID, + TVDBID: req.TVDBID, + IMDbID: req.IMDbID, + PosterPath: req.PosterPath, + Status: string(req.Status), + RequestedByUserID: req.RequestedByUserID, + RequestedByProfileID: req.RequestedByProfileID, + RequesterName: req.RequesterUsername, + Reason: req.OutcomeReason, + LibraryContentID: req.LibraryContentID, + CreatedAt: req.CreatedAt, + } +} + +// publishRequestEvent tells plugins about a request lifecycle event. It is +// published on the plugin channel, which no websocket client receives. The +// event ID is derived from the request and its last update, so a repeated +// call for the same transition carries the same ID and a plugin can skip it. +// Best-effort, like the server-channel post beside it. +func (s *System) publishRequestEvent(ctx context.Context, event string, req requests.Request) { + if s == nil || s.events == nil { + return + } + if err := s.events.PublishJSON(ctx, evt.ChannelPlugins, event, RequestEventPayload(req), evt.PublishOptions{ + EventID: fmt.Sprintf("%s:%s:%d", event, req.ID, req.UpdatedAt.UnixNano()), + AdminOnly: true, + }); err != nil { + s.logger.WarnContext(ctx, "publish request event for plugins failed", "request_id", req.ID, "event", event, "error", err) + } +} diff --git a/internal/notifications/request_notifier.go b/internal/notifications/request_notifier.go index 07446432e4..463ddffed4 100644 --- a/internal/notifications/request_notifier.go +++ b/internal/notifications/request_notifier.go @@ -81,6 +81,7 @@ type RequestFulfillmentNotifier struct { // unexported methods keep *System its only production implementation. type fulfillmentBackend interface { PostServerChannelRequestEvent(ctx context.Context, event string, info RequestEventInfo) + publishRequestEvent(ctx context.Context, event string, req requests.Request) notificationsEnabled(ctx context.Context, userID int, profileID string) (bool, error) fulfilledDelivered(ctx context.Context, recipient requests.Follower, requestID string) (bool, error) dispatchFulfilled(ctx context.Context, delivery Delivery) error @@ -163,6 +164,7 @@ func (n *RequestFulfillmentNotifier) AnnounceFulfilled(ctx context.Context, req return } n.backend.PostServerChannelRequestEvent(ctx, ServerChannelEventRequestFulfilled, requestEventInfoFor(req)) + n.backend.publishRequestEvent(ctx, ServerChannelEventRequestFulfilled, req) } // notifyFulfilledProfile posts one request.fulfilled delivery to a profile @@ -204,6 +206,7 @@ const requestLifecycleDispatchTimeout = 30 * time.Second // the only production implementation. type requestLifecycleBackend interface { PostServerChannelRequestEvent(ctx context.Context, event string, info RequestEventInfo) + publishRequestEvent(ctx context.Context, event string, req requests.Request) dispatchRequestLifecycleDetached(ctx context.Context, req requests.Request, deliveryType string) } @@ -235,6 +238,7 @@ func NewRequestLifecycleNotifier(system *System) *RequestLifecycleNotifier { // personal confirmation would be noise. func (n *RequestLifecycleNotifier) RequestSubmitted(ctx context.Context, req requests.Request) { n.backend.PostServerChannelRequestEvent(ctx, ServerChannelEventRequestSubmitted, requestEventInfoFor(req)) + n.backend.publishRequestEvent(ctx, ServerChannelEventRequestSubmitted, req) } // RequestApproved implements requests.LifecycleNotifier. Every approval is @@ -247,6 +251,7 @@ func (n *RequestLifecycleNotifier) RequestApproved( origin requests.ApprovalOrigin, ) { n.backend.PostServerChannelRequestEvent(ctx, ServerChannelEventRequestApproved, requestEventInfoFor(req)) + n.backend.publishRequestEvent(ctx, ServerChannelEventRequestApproved, req) switch origin { case requests.ApprovalOriginAdmin: n.backend.dispatchRequestLifecycleDetached(ctx, req, DeliveryTypeRequestApproved) @@ -262,6 +267,7 @@ func (n *RequestLifecycleNotifier) RequestApproved( // RequestDeclined implements requests.LifecycleNotifier. func (n *RequestLifecycleNotifier) RequestDeclined(ctx context.Context, req requests.Request) { n.backend.PostServerChannelRequestEvent(ctx, ServerChannelEventRequestDeclined, requestEventInfoFor(req)) + n.backend.publishRequestEvent(ctx, ServerChannelEventRequestDeclined, req) n.backend.dispatchRequestLifecycleDetached(ctx, req, DeliveryTypeRequestDeclined) } diff --git a/internal/notifications/request_notifier_test.go b/internal/notifications/request_notifier_test.go index d90dfecf10..ecff9d1dc2 100644 --- a/internal/notifications/request_notifier_test.go +++ b/internal/notifications/request_notifier_test.go @@ -18,6 +18,8 @@ func (f *fakeFulfillmentBackend) PostServerChannelRequestEvent(context.Context, f.channelPost++ } +func (f *fakeFulfillmentBackend) publishRequestEvent(context.Context, string, requests.Request) {} + func (f *fakeFulfillmentBackend) notificationsEnabled(_ context.Context, _ int, profileID string) (bool, error) { return !f.disabled[profileID], nil } diff --git a/internal/notifications/system.go b/internal/notifications/system.go index d2931542d3..19286fd321 100644 --- a/internal/notifications/system.go +++ b/internal/notifications/system.go @@ -96,6 +96,9 @@ type System struct { // configured channel the same way. dispatcher Dispatcher + // events carries host events to plugins; nil without a hub. + events *evt.Hub + pool *pgxpool.Pool stores userstore.UserStoreProvider // scopes resolves a recipient's current access before a delivery that @@ -262,6 +265,7 @@ func NewSystem( pushSender: pushSenderInst, serverChannelWorker: serverChannelSweep, dispatcher: multiDispatcher, + events: hub, pool: pool, stores: stores, scopes: scopes, diff --git a/internal/plugins/event_catalog_contract_test.go b/internal/plugins/event_catalog_contract_test.go index 2137197326..47f8e613c5 100644 --- a/internal/plugins/event_catalog_contract_test.go +++ b/internal/plugins/event_catalog_contract_test.go @@ -13,6 +13,7 @@ import ( 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/requests" ) // TestEventCatalogMatchesProducers projects what each producer of a catalog @@ -35,6 +36,12 @@ func TestEventCatalogMatchesProducers(t *testing.T) { stopped := 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))}}) + year := 1995 + request := func(status requests.Status, reason string) []byte { + return mustJSON(t, notifications.RequestEventPayload(requests.Request{ID: "r1", MediaType: requests.MediaTypeMovie, TMDBID: 949, + Title: "Heat", Year: &year, Status: status, RequestedByUserID: 7, RequestedByProfileID: "p1", + RequesterUsername: "josh", OutcomeReason: reason, LibraryContentID: "movie-949", CreatedAt: at})) + } notification := mustJSON(t, notifications.PayloadForRow(notifications.DeliveryRow{ Delivery: notifications.Delivery{ID: "d1", Type: "episode.available", UserID: 7, ProfileID: "p1", CreatedAt: at}, SeriesTitle: "Severance", SeasonNumber: &season, @@ -57,14 +64,18 @@ func TestEventCatalogMatchesProducers(t *testing.T) { 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}, - publicevents.JobCreated: {published[publicevents.JobFailed], jobCheck}, - publicevents.JobCompleted: {published[publicevents.JobFailed], jobCheck}, - publicevents.JobFailed: {published[publicevents.JobFailed], jobCheck}, - publicevents.JobCancelled: {published[publicevents.JobFailed], jobCheck}, + publicevents.ScanStarted: {scan("running"), scanCheck}, + publicevents.ScanCompleted: {scan("completed"), scanCheck}, + publicevents.ScanFailed: {scan("failed"), scanCheck}, + publicevents.ScanCancelled: {scan("canceled"), scanCheck}, + publicevents.JobCreated: {published[publicevents.JobFailed], jobCheck}, + publicevents.JobCompleted: {published[publicevents.JobFailed], jobCheck}, + publicevents.JobFailed: {published[publicevents.JobFailed], jobCheck}, + publicevents.JobCancelled: {published[publicevents.JobFailed], jobCheck}, + publicevents.RequestSubmitted: {request(requests.StatusPending, ""), requestCheck("")}, + publicevents.RequestApproved: {request(requests.StatusApproved, ""), requestCheck("")}, + publicevents.RequestDeclined: {request(requests.StatusPending, "Already in the library"), requestCheck("Already in the library")}, + publicevents.RequestFulfilled: {request(requests.StatusCompleted, ""), requestCheck("")}, publicevents.NotificationCreated: {notification, func(p any) bool { n := p.(*publicevents.Notification) return n.ID == "d1" && n.SeriesTitle == "Severance" && n.SeasonNumber != nil && *n.SeasonNumber == 2 && n.CreatedAt.Equal(at) @@ -100,6 +111,14 @@ func sessionCheck(title string) func(any) bool { } } +func requestCheck(reason string) func(any) bool { + return func(p any) bool { + r := p.(*publicevents.RequestEvent) + return r.ID == "r1" && r.Title == "Heat" && r.Year != nil && *r.Year == 1995 && r.RequestedByUserID == 7 && + r.RequestedByProfileID == "p1" && r.Status != "" && r.Reason == reason && r.LibraryContentID == "movie-949" + } +} + func scanCheck(p any) bool { scan := p.(*publicevents.ScanEvent) return scan.LibraryID == 7 && scan.Result != nil && scan.Result.New == 3 && scan.StartedAt != nil diff --git a/internal/requests/follows_test.go b/internal/requests/follows_test.go index 81e859dcaa..33a4f64d25 100644 --- a/internal/requests/follows_test.go +++ b/internal/requests/follows_test.go @@ -201,6 +201,10 @@ func TestNotifyFulfilledAnnouncesOnceAfterTheStamp(t *testing.T) { if !slices.Equal(notifier.announced, []string{"req1"}) { t.Fatalf("announced = %v, want req1 once", notifier.announced) } + // Plugins learn which catalog item fulfilled the request from it. + if want := fakePresenceContentID(MediaTypeMovie, 42); !slices.Equal(notifier.announcedContent, []string{want}) { + t.Fatalf("announced content = %v, want %q", notifier.announcedContent, want) + } } func TestNotifyFulfilledKeepsFollowersWhenDispatchFails(t *testing.T) { diff --git a/internal/requests/notify.go b/internal/requests/notify.go index 1182a7562d..4711d360e3 100644 --- a/internal/requests/notify.go +++ b/internal/requests/notify.go @@ -140,6 +140,8 @@ func (s *Service) notifyFulfilledPending(ctx context.Context) { continue } req.Followers = followers + // The stored row doesn't carry the match; the announcement names it. + req.LibraryContentID = match.ContentID if err := s.notifier.NotifyFulfilled(ctx, *req, match.ContentID); err != nil { slog.WarnContext(ctx, "request fulfill-notify: dispatch failed", "component", "requests", "request_id", req.ID, "err", err) diff --git a/internal/requests/notify_test.go b/internal/requests/notify_test.go index 1739e0cf32..b3ae2b2d49 100644 --- a/internal/requests/notify_test.go +++ b/internal/requests/notify_test.go @@ -89,11 +89,14 @@ type fakeNotifier struct { contentIDs []string followers [][]Follower announced []string - err error + // announcedContent is the catalog item each announcement named. + announcedContent []string + err error } func (f *fakeNotifier) AnnounceFulfilled(_ context.Context, req Request) { f.announced = append(f.announced, req.ID) + f.announcedContent = append(f.announcedContent, req.LibraryContentID) } func (f *fakeNotifier) NotifyFulfilled(_ context.Context, req Request, contentID string) error { From 06f65c369ab2f13bd65182768564192b3500a755 Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Wed, 4 Nov 2026 17:20:03 -0500 Subject: [PATCH 03/12] feat(plugins): approve plugin permissions and issue scoped host API keys Plugins received admin activity and profiles' personal data with no administrator consent, and plugins that call the admin API asked administrators to paste a full-access API key into their settings. An installation now asks for permissions derived from what it declares: the admin and user_data access classes of the catalog events it subscribes to, and the manifest's host_api_scopes that the API key scope catalog knows. plugin_permission_grants records what an administrator approved. Installing a plugin approves the event access it asks for then, a boot pass carries existing installations over before the catalog auto-update runs, and an upgrade never widens a grant: new requirements stay pending until approved. The event dispatcher indexes an admin or user_data subscription only when the grant approves that class. An approval runs the lifecycle path, so every API server rebuilds its index without restarting the plugin. An approval applies only what the administrator read. The permissions read's ETag is a digest of the whole representation, and the approval is a guarded PUT whose If-Match is compared inside the approval's transaction, after the grant is locked; a plugin update, another approval or a revoked key in between is 412 and writes nothing. Approving host API scopes mints a key with exactly those scopes on the approving administrator's account, points the grant at it and deletes the previous key in one transaction, so the plugin always has a working key. A key whose owner is no longer an enabled administrator stops counting as approved and the installation reads as pending. HostAPICredentials.GetHostAPICredential returns the key to the calling installation with the internal base URL, and answers FAILED_PRECONDITION when nothing usable is approved. Uninstalling deletes the key in the same transaction as the installation, locking in the same order as key deletion. The v2 admin API adds a conditional GET .../installations/{id}/permissions, a guarded PUT .../permissions/approval and permissions_pending on installations; the web plugin page gains a Permissions panel with an Approve button and the plugin list a pending badge. Co-Authored-By: Claude Opus 5.5 --- cmd/silo/main.go | 22 +- contracts/api/v2/openapi.json | 795 +++++++++++++++--- docs/admin-api.md | 51 +- docs/architecture/plugin-event-delivery.md | 24 +- docs/architecture/plugin-permissions.md | 129 +++ docs/architecture/secret-encryption.md | 7 +- .../api/handlers/admin_plugin_permissions.go | 61 ++ internal/api/router.go | 1 + internal/api/testdata/media_routes.txt | 4 + internal/apiv2/admin_plugin_installations.go | 22 +- internal/apiv2/admin_plugin_lifecycle.go | 28 +- internal/apiv2/admin_plugin_permissions.go | 203 +++++ .../apiv2/admin_plugin_permissions_test.go | 93 ++ internal/apiv2/admin_plugin_uploads.go | 4 +- internal/apiv2/document.go | 1 + internal/apiv2/router.go | 1 + internal/auth/api_key_metadata.go | 41 +- internal/auth/api_key_repository.go | 80 +- internal/auth/plugin_host_api_keys.go | 58 ++ internal/contractledger/ledger_test.go | 28 +- internal/pluginhost/host.go | 12 +- internal/pluginhost/host_api_credential.go | 26 + .../pluginhost/host_api_credential_test.go | 86 ++ internal/pluginhost/runtime_host_server.go | 57 +- internal/plugins/event_dispatcher.go | 32 +- .../plugins/event_dispatcher_index_test.go | 68 ++ internal/plugins/event_dispatcher_test.go | 19 + internal/plugins/installation.go | 82 +- internal/plugins/installer.go | 26 +- internal/plugins/permissions.go | 712 ++++++++++++++++ internal/plugins/permissions_db_test.go | 472 +++++++++++ internal/plugins/permissions_test.go | 95 +++ internal/plugins/service.go | 21 + ...104202747_add_plugin_permission_grants.sql | 30 + scripts/ci/db-contracts.txt | 6 + web/src/api/types.ts | 2 + web/src/api/v2/operations.ts | 4 + web/src/api/v2/schema.ts | 377 +++++++++ .../admin/plugins/PluginPermissionsPanel.tsx | 184 ++++ .../components/admin/plugins/PluginTile.tsx | 9 +- .../queries/admin/pluginPermissions.test.ts | 76 ++ web/src/hooks/queries/admin/plugins.ts | 98 +++ web/src/hooks/queries/keys.ts | 3 + web/src/lib/pluginHelpers.test.ts | 6 + web/src/lib/pluginStatus.ts | 9 +- web/src/pages/AdminPluginDetail.test.tsx | 2 + web/src/pages/AdminPluginDetail.tsx | 23 + 47 files changed, 3987 insertions(+), 203 deletions(-) create mode 100644 docs/architecture/plugin-permissions.md create mode 100644 internal/api/handlers/admin_plugin_permissions.go create mode 100644 internal/apiv2/admin_plugin_permissions.go create mode 100644 internal/apiv2/admin_plugin_permissions_test.go create mode 100644 internal/auth/plugin_host_api_keys.go create mode 100644 internal/pluginhost/host_api_credential.go create mode 100644 internal/pluginhost/host_api_credential_test.go create mode 100644 internal/plugins/permissions.go create mode 100644 internal/plugins/permissions_db_test.go create mode 100644 internal/plugins/permissions_test.go create mode 100644 migrations/sql/20261104202747_add_plugin_permission_grants.sql create mode 100644 web/src/components/admin/plugins/PluginPermissionsPanel.tsx create mode 100644 web/src/hooks/queries/admin/pluginPermissions.test.ts diff --git a/cmd/silo/main.go b/cmd/silo/main.go index 60e1f47845..f93d69b95d 100644 --- a/cmd/silo/main.go +++ b/cmd/silo/main.go @@ -1862,6 +1862,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 { @@ -1935,9 +1940,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, @@ -1952,6 +1958,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. @@ -2044,6 +2051,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) } diff --git a/contracts/api/v2/openapi.json b/contracts/api/v2/openapi.json index 665c875f43..76234dba96 100644 --- a/contracts/api/v2/openapi.json +++ b/contracts/api/v2/openapi.json @@ -14513,6 +14513,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": { @@ -14689,6 +14721,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": { @@ -14783,6 +14889,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" }, @@ -14871,6 +14981,7 @@ "auth_bindings", "task_bindings", "runtime", + "permissions_pending", "created_at", "updated_at" ], @@ -14894,6 +15005,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": { @@ -102755,7 +102915,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": { @@ -102807,6 +103354,16 @@ }, "description": "Not Acceptable" }, + "408": { + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + }, + "description": "Request Timeout" + }, "409": { "content": { "application/problem+json": { @@ -102817,6 +103374,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": { @@ -102863,17 +103440,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.", @@ -102917,7 +103497,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginInstallationUpdate" + "$ref": "#/components/schemas/AdminPluginAuthBindingTestInputBody" } } }, @@ -102928,7 +103508,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginInstallation" + "$ref": "#/components/schemas/AuthConnectionTestResult" } } }, @@ -103070,19 +103650,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.", @@ -103126,7 +103706,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginAuthBindingWrite" + "$ref": "#/components/schemas/AdminPluginConfigWrite" } } }, @@ -103134,15 +103714,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": { @@ -103280,7 +103852,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" ], @@ -103290,10 +103862,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.", @@ -103337,7 +103908,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminPluginAuthBindingTestInputBody" + "$ref": "#/components/schemas/AdminPluginConfigWrite" } } }, @@ -103348,7 +103919,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthConnectionTestResult" + "$ref": "#/components/schemas/AdminPluginConnectionCheck" } } }, @@ -103490,7 +104061,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" ], @@ -103500,10 +104071,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", @@ -103540,21 +104119,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": { @@ -103606,16 +104208,6 @@ }, "description": "Not Acceptable" }, - "408": { - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/Problem" - } - } - }, - "description": "Request Timeout" - }, "409": { "content": { "application/problem+json": { @@ -103626,7 +104218,7 @@ }, "description": "Conflict" }, - "413": { + "412": { "content": { "application/problem+json": { "schema": { @@ -103634,17 +104226,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": { @@ -103692,20 +104282,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", @@ -103744,26 +104350,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": { @@ -103815,7 +104419,7 @@ }, "description": "Not Acceptable" }, - "408": { + "409": { "content": { "application/problem+json": { "schema": { @@ -103823,9 +104427,9 @@ } } }, - "description": "Request Timeout" + "description": "Conflict" }, - "409": { + "412": { "content": { "application/problem+json": { "schema": { @@ -103833,19 +104437,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": { @@ -103853,9 +104455,9 @@ } } }, - "description": "Unsupported Media Type" + "description": "Unprocessable Entity" }, - "422": { + "428": { "content": { "application/problem+json": { "schema": { @@ -103863,7 +104465,7 @@ } } }, - "description": "Unprocessable Entity" + "description": "Precondition Required" }, "429": { "content": { @@ -103901,13 +104503,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 6fbe8b9fe5..cd90cddbcb 100644 --- a/docs/admin-api.md +++ b/docs/admin-api.md @@ -3432,7 +3432,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 @@ -3519,6 +3520,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/plugin-event-delivery.md b/docs/architecture/plugin-event-delivery.md index fc61a1e1f7..68bc466264 100644 --- a/docs/architecture/plugin-event-delivery.md +++ b/docs/architecture/plugin-event-delivery.md @@ -50,6 +50,22 @@ 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 The producing server writes one `plugin_event_deliveries` row per @@ -87,6 +103,9 @@ published while the server drains its requests after its context ended. - 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. +- 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. @@ -118,7 +137,10 @@ published while the server drains its requests after its context ended. - 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 internal - event names and unprojected payloads until they are replaced. + event names and unprojected payloads, 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 diff --git a/docs/architecture/plugin-permissions.md b/docs/architecture/plugin-permissions.md new file mode 100644 index 0000000000..f824ce669d --- /dev/null +++ b/docs/architecture/plugin-permissions.md @@ -0,0 +1,129 @@ +# 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. +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 locks the grant's key and then the grant the same way and + deletes both with the installation 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. +- 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. + +## Limits + +- 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. diff --git a/docs/architecture/secret-encryption.md b/docs/architecture/secret-encryption.md index de0e6c4e16..454fe32802 100644 --- a/docs/architecture/secret-encryption.md +++ b/docs/architecture/secret-encryption.md @@ -154,7 +154,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/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 fcce2630f9..56a087f68a 100644 --- a/internal/api/router.go +++ b/internal/api/router.go @@ -3076,6 +3076,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 dea528752e..83551401f6 100644 --- a/internal/api/testdata/media_routes.txt +++ b/internal/api/testdata/media_routes.txt @@ -270,6 +270,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 @@ -1595,6 +1597,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 3dd4c02f1c..396bbe8fe1 100644 --- a/internal/apiv2/document.go +++ b/internal/apiv2/document.go @@ -612,6 +612,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 4a2aa5a632..0f2c682937 100644 --- a/internal/apiv2/router.go +++ b/internal/apiv2/router.go @@ -227,6 +227,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/contractledger/ledger_test.go b/internal/contractledger/ledger_test.go index d8bf95c05c..9141e61744 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 @@ -1064,11 +1065,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/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..6d8247ac98 100644 --- a/internal/pluginhost/runtime_host_server.go +++ b/internal/pluginhost/runtime_host_server.go @@ -107,9 +107,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 +130,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 +159,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 @@ -414,10 +419,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 +435,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_dispatcher.go b/internal/plugins/event_dispatcher.go index 168d71e399..c9d1a212b7 100644 --- a/internal/plugins/event_dispatcher.go +++ b/internal/plugins/event_dispatcher.go @@ -99,7 +99,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. @@ -137,6 +137,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 { @@ -160,7 +168,7 @@ type producedEvent struct { func NewEventDispatcher( bus cache.EventBus, hub *events.Hub, - installations taskInstallationStore, + installations eventInstallationStore, resolver eventConsumerResolver, deliveries eventDeliveryStore, concurrency int, @@ -185,7 +193,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) }, @@ -451,14 +459,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 @@ -486,8 +500,10 @@ func (d *EventDispatcher) buildIndex(ctx context.Context) (index map[string][]ev continue } // Only catalog and plugin events reach plugins; the host's - // internal event names are not a contract. - if _, deliverable := publicevents.AccessOf(eventName); !deliverable { + // 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{}{} diff --git a/internal/plugins/event_dispatcher_index_test.go b/internal/plugins/event_dispatcher_index_test.go index 23bb465e9f..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) { @@ -553,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 a35c404db2..85b6a63337 100644 --- a/internal/plugins/event_dispatcher_test.go +++ b/internal/plugins/event_dispatcher_test.go @@ -190,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) { @@ -198,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 diff --git a/internal/plugins/installation.go b/internal/plugins/installation.go index 28b5ce659d..04f8b35ed9 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 @@ -108,7 +115,7 @@ func NewInstallationStore(pool *pgxpool.Pool) *InstallationStore { return &InstallationStore{pool: pool} } -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` @@ -128,6 +135,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 @@ -196,8 +204,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, @@ -208,6 +216,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) @@ -216,6 +225,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) @@ -224,8 +237,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) { @@ -350,6 +367,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()") @@ -372,6 +394,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 { @@ -417,10 +444,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) } @@ -501,18 +532,49 @@ 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) + // The host API key issued to the plugin goes with it, in the same + // transaction, so no scoped credential outlives its plugin. + if err := retryOnGrantChange(func() error { return s.deleteInstallationRows(ctx, id) }); err != nil { + return err + } + + if err := removeInstallationFiles(ctx, installation); err != nil { + return fmt.Errorf("removing plugin installation files: %w", err) + } + + return nil +} + +// deleteInstallationRows deletes the installation and the host API key its +// grant names in one transaction. 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) error { + tx, err := s.pool.Begin(ctx) + if err != nil { + return fmt.Errorf("begin delete installation transaction: %w", err) + } + defer func() { _ = tx.Rollback(context.WithoutCancel(ctx)) }() + grant, err := lockPermissionGrant(ctx, tx, id) + if err != nil { + return err + } + if grant != nil && grant.APIKeyID != nil { + if _, err := tx.Exec(ctx, `DELETE FROM api_keys WHERE id = $1`, *grant.APIKeyID); err != nil { + return 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 fmt.Errorf("deleting plugin installation: %w", err) } if tag.RowsAffected() == 0 { return ErrInstallationNotFound } - - if err := removeInstallationFiles(ctx, installation); err != nil { - return fmt.Errorf("removing plugin installation files: %w", err) + if err := tx.Commit(ctx); err != nil { + return fmt.Errorf("commit delete installation transaction: %w", err) } - return nil } 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..c9bad9dc95 --- /dev/null +++ b/internal/plugins/permissions.go @@ -0,0 +1,712 @@ +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 +} + +// 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 +} + +// 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..0e5e88c832 --- /dev/null +++ b/internal/plugins/permissions_db_test.go @@ -0,0 +1,472 @@ +package plugins_test + +import ( + "bytes" + "context" + "errors" + "fmt" + "os" + "path/filepath" + "reflect" + "slices" + "testing" + "time" + + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgxpool" + + "github.com/Silo-Server/silo-server/internal/auth" + "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) and revokes it when none are asked for; 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. +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 dropped 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) + } + + // Dropping every scope: the grant stops naming the key before its + // deletion fails. + f.replace(t, installation.ID, []string{}) + if _, err := failing.Approve(ctx, approver, installation.ID, nil); !errors.Is(err, errInjectedRevoke) { + t.Fatalf("dropping scopes with a failing revoke: %v, want the injected failure", err) + } + if keys, got := f.pluginKeys(t, installation), f.read(t, installation.ID); !slices.Equal(keys, []int64{issued}) || *got.Grant.APIKeyID != issued { + t.Fatalf("after a failed revocation: keys %v, grant %+v; want the key still named by the grant", keys, got.Grant) + } + 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) + } + + f.replace(t, installation.ID, []string{}, subscriber("session.started")) + dropped := f.approve(t, approver, installation.ID) + if dropped.Grant.APIKeyID != nil || f.keyExists(t, *reissued.Grant.APIKeyID) { + t.Fatalf("approving a plugin that asks for no scopes kept its key: %+v", 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}) + approved := f.approve(t, approver, installation.ID) + if err := f.store.Delete(t.Context(), installation.ID); err != nil { + t.Fatal(err) + } + if f.keyExists(t, *approved.Grant.APIKeyID) { + t.Fatalf("the host API key outlived its plugin") + } + 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 d769989329..004d39ba8a 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 6a36e1faa7..8f606c9cac 100644 --- a/scripts/ci/db-contracts.txt +++ b/scripts/ci/db-contracts.txt @@ -507,6 +507,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 4399447273..38663d8ca3 100644 --- a/web/src/api/types.ts +++ b/web/src/api/types.ts @@ -4084,6 +4084,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 5f23f110ad..e853f0be77 100644 --- a/web/src/api/v2/operations.ts +++ b/web/src/api/v2/operations.ts @@ -213,6 +213,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", @@ -892,6 +894,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 e0c6c69359..1de1c7a494 100644 --- a/web/src/api/v2/schema.ts +++ b/web/src/api/v2/schema.ts @@ -3687,6 +3687,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; @@ -18459,6 +18493,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"][]; @@ -18505,6 +18545,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"][]; @@ -18528,6 +18594,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 */ @@ -18573,6 +18641,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; @@ -68199,6 +68289,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 ? (