You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(plugins): approve plugin permissions and issue scoped host API keys - #3549
Parked. This draft won't merge for now. Admins who want a plugin to call the admin API will
create a scoped API key for it themselves, through a scope picker on the API keys page (a
separate pull request). Plugin permissions will be revisited later; this branch keeps the work
and its fixes until then.
Stacked on #3547. This pull request's own changes are the commits after the merges of feat/plugin-event-catalog.
Problem
Related issue: N/A
Validation tasks: none while parked. If revived, it changes #1191 C1, #1224 C1 and #1225 C1, C2.
Installing a plugin gives it admin activity and every profile's personal data whenever it
subscribes to those events, with no administrator consent. Plugins that call the admin API ask
administrators to paste a full-access API key into plugin settings.
This change makes an installation ask for permissions, records what an administrator approves, and
issues the plugin a key with only the approved scopes.
Approach
An installation's permissions come from what it declares: the admin and personal-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, and existing installations keep the
event classes they already subscribe to. An upgrade never widens a grant: new requirements stay
pending, and the plugin runs with its old grant until an administrator approves.
An upgrade that asks for fewer host API scopes than its key carries deletes the key in the
upgrade's own transaction and clears the approved scopes, so the plugin never keeps a key wider
than its manifest asks for. It is keyless, and pending while it still asks for scopes.
The event dispatcher indexes an admin or personal-data subscription only when the grant covers
that class. Approval runs the plugin lifecycle path, so every API server picks it up without a
plugin restart.
An approval applies only what the administrator read. The permissions read's ETag covers the
whole response, and the approval is a guarded PUT whose If-Match is compared inside the
approval's transaction; a plugin update, another approval or a revoked key in between is 412 and
writes nothing. The web panel then reloads and shows the new requirements.
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 until someone approves again.
Backups: a full restore keeps plugin permission grants from the live server, as it already does
for plugin configs and state, because it also keeps the live server's API keys. A grant whose
key the restore dropped keeps its approvals and waits for the plugin to be approved again; an
installation ID that now belongs to a different plugin loses that plugin's grant.
HostAPICredentials.GetHostAPICredential returns the key to the calling installation only.
Uninstalling deletes the key in the same transaction as the installation.
v2 admin API: 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; on the plugin list, a plugin waiting for
approval shows a badge and counts under "Needs attention".
Validation
On this head: build, make lint-changed, verify-apiv2-contract, verify-apiv2-openapi, verify-apiv2-web-types, verify-route-inventory, verify-migrations, verify-migration-ledger, and the tests of internal/plugins, internal/backup, internal/auth, internal/api/..., internal/apiv2/..., internal/events and internal/pluginhost against a freshly migrated Postgres: pass. The permissions database test
covers an upgrade that narrows the scopes and one that drops them.
An earlier head was checked on a test server and shared dev with a plugin asking for admin:monitor:read: no key before approval; approval without If-Match 428, with a stale tag
412, with the current tag 200, and a replay of the old tag 412; its key then read active
sessions (200) and was refused on API keys (403); uninstalling removed the key. That check
hasn't been repeated on this head.
New migration 20261104202747_add_plugin_permission_grants.sql; a startup pass records grants for
existing installations before the catalog auto-update runs.
Installations from before host_api_scopes was recorded ask for no scopes until their next
update or reinstall records them.
A narrowing upgrade deletes the plugin's key without an audit entry, because no administrator
acts; uninstalling and the API keys page still audit theirs.
Plugin keys appear on the API keys page under the approving administrator.
If a restore drops a plugin's grant, that plugin's key stays on the approving administrator's
account, unusable, until someone deletes it on the API keys page. Fixing that means changing
how a restore copies api_keys; it's noted under Limits in docs/architecture/plugin-permissions.md.
If revived and merged, re-check Plugin management / marketplace — Server #1224 C1: installing and updating a catalog plugin record
permission grants, and an update that asks for more stays pending while the plugin keeps its
old grant. Re-check API keys — Web admin #1191 C1: a plugin's approved key appears on the API keys page and can be
revoked there, which leaves the plugin pending. Re-check Plugin management / marketplace — Web admin #1225 C1 and C2: the plugin page shows
a Permissions section, the plugin list counts a plugin waiting for approval under "Needs
attention", and installed plugins waiting for approval show a badge on their tile and a banner
on their page, next to the tier labels.
Adversarial review: Codex (gpt-6.1-sol) reviewed the approval flow, key issuance and event gating
for privilege escalation and races. It found that an approval could apply requirements newer than
the ones shown, that a demoted administrator's key stayed valid, and that replacing a key could
leave the plugin without one; all three are fixed. A later four-agent review found that an
upgrade narrowing the scopes left the wider key working; that is fixed too.
Add plugin permission grants with admin approval and scoped host API keys
Adds a plugin permission system: installations record manifest-requested host API scopes, and a new permission-grants table stores approved event-access classes, host API scopes, and an associated host API key (migration).
Adds admin API endpoints (GET/PUT on installation permissions) with ETag-based conditional reads and guarded approval via If-Match (admin_plugin_permissions.go).
Non-public events (admin, user_data) are only delivered to installations whose grant approves that access class; EventDispatcher.buildIndex rebuilds on approval via the plugin-change cache event.
Plugins receive their approved host API credentials through a new GetHostAPICredential runtime RPC, which returns only the calling installation's token and scopes (runtime_host_server.go).
Uninstall now deletes the permission grant and its host API key in the same transaction, with grant-change retries and audited key deletion (installation.go); backup carry preserves grants and clears missing approver or key references (credentials.go).
Admin UI shows a permissions_pending badge on plugin tiles, a permissions review panel, and an approval mutation that sends the read ETag and surfaces 412 conflicts.
Behavioral Change: startup runs EnsurePermissionGrants before preloading enabled plugins and exits on failure; public and plugin events remain deliverable without approval, and failure to load approvals prevents a complete event index build.
… 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
The PR changes the web admin UI, but the Evidence section has no captures or published evidence link; “being published; the link follows shortly” does not show the change.
web/src/components/admin/plugins/PluginPermissionsPanel.tsx and web/src/pages/AdminPluginDetail.tsx: provide before-and-after captures of the permissions panel and pending banner on desktop and phone-width web. Include a short recording of the review-and-approve flow.
web/src/components/admin/plugins/PluginTile.tsx and web/src/lib/pluginStatus.ts: provide before-and-after desktop and phone-width captures of the plugin list showing the approval badge and attention status.
Automated check: Macroscope check run agent (gpt-6-luna). Evidence was not reviewed for correctness.
Plugin installations now track permission requirements and grants for restricted events and host API scopes. Administrators can review and approve those requirements through guarded API operations and a web panel. Grants control event delivery and scoped host API credentials.
Changes: Plugin Permission Approval
Layer / File(s)
Summary
Installation requirements and grant storage migrations/sql/*, internal/plugins/installation.go, internal/plugins/installer.go, cmd/silo/main.go
Installations persist manifest host API scopes. Installation creation and capability updates ensure grants, and startup backfills missing grants for existing installations.
Permission evaluation and transactional approval internal/plugins/permissions.go, internal/auth/api_key_*.go, internal/auth/plugin_host_api_keys.go, internal/plugins/permissions*_test.go
The permission service derives required access and pending status. Approval updates grants and issues, replaces, or revokes scoped API keys transactionally. The API-key repository supports caller-managed transactions and post-commit audit callbacks.
Runtime event and credential access internal/plugins/event_dispatcher*.go, internal/pluginhost/*, cmd/silo/main.go
Event indexing checks approved access for restricted events. The runtime host provides credentials for its bound installation through a separate RPC.
Administrator permission API and installation status internal/apiv2/admin_plugin_*.go, internal/api/handlers/admin_plugin_permissions.go, contracts/api/v2/openapi.json, internal/api/router.go, internal/api/testdata/*
The API adds conditional permission reads and ETag-guarded approval. Installation responses include permissions_pending. The OpenAPI contract also documents authentication-binding and plugin-configuration operations.
The web client reads permissions and submits approval with the returned ETag. Plugin tiles and detail pages identify pending permissions and show the review panel.
sequenceDiagram
participant Admin as Administrator
participant Web as PluginPermissionsPanel
participant API as Admin permissions API
participant PermissionService
participant Database
participant APIKeyIssuer
Admin->>Web: Review installation permissions
Web->>API: Read permissions
API->>PermissionService: Load permissions
PermissionService->>Database: Read requirements and grant
Database-->>PermissionService: Return current state
PermissionService-->>Web: Return permissions and ETag
Admin->>Web: Approve current requirements
Web->>API: Submit approval with If-Match
API->>PermissionService: Approve with ETag check
PermissionService->>Database: Validate state and update grant
PermissionService->>APIKeyIssuer: Issue or revoke scoped key when required
APIKeyIssuer-->>PermissionService: Return key result
PermissionService-->>API: Return updated permissions
API-->>Web: Return updated permissions and ETag
Plugin permission approval can be sent with a wildcard If-Match and skip the stale-permissions check, and uninstalling a plugin deletes its API key without an audit record. Both are narrow and need an authenticated administrator. Fix them before or shortly after merge.
Security architecture risk: Moderate · up to 06f65
The change improves least privilege, but approval integrity, revocation auditing, and downgrade cleanup retain material gaps. Administrator authorization and restricted key scopes limit exposure; credential-isolation evidence remains incomplete.
Retained concerns
Low · security · observed: The new approval endpoint accepts If-Match: * through the shared precondition evaluator, allowing an authorized administrator client to approve current requirements without supplying the permissions representation previously reviewed. This contradicts the stronger read-bound consent contract. The web panel avoids the wildcard, and administrator authorization still applies; no unauthenticated approval path was established.
Low · security · observed: The newly added uninstall cleanup directly deletes the grant's API key rather than using the audited key-revocation contract. The credential is revoked transactionally, but no api_key.deleted domain record is produced by this path, weakening credential-specific attribution and reconciliation. An uninstall request record is not equivalent to the omitted key-deletion record.
Medium · security · inferred: Reversing the new migration drops permission grants without revoking their issued API keys. A previously obtained bearer can therefore remain valid within its scopes after its installation ownership link is discarded. Returning to the base implementation also removes automatic uninstall revocation. This requires an operational downgrade and prior credential issuance; manual key revocation and account controls remain available.
Security review details
Security Blast Radius
observed — Bearer compromise exposes the issued scopes, potentially including server-wide monitoring, ordinary-account administration, or playback control, subject to owner authorization. The current scope allowlist does not admit plugin approval or key-management routes. Separately, malicious native-plugin execution already shares the server's OS, filesystem, and network authority; permissions do not reduce that pre-existing maximum scope.
Security Findings and Attack Paths
observed — The retained approval finding concerns consent integrity, not administrator authentication bypass: an administrator client can deliberately send the wildcard rather than a read-specific validator. The retained uninstall finding concerns missing credential-deletion audit detail, not continued validity of the normally deleted key.
inferred — The downgrade exposure requires an issued credential to have been obtained before grants are dropped. Its holder can continue using allowed API operations while the key and owner remain valid, because key authentication is independent of the discarded grant. This is a new credential-lifecycle recovery gap, not an expansion to unscoped authority.
Trust Boundaries and Controls
observed — The credential RPC ignores request-supplied identity and uses the installation ID fixed by the host. This controls request-level cross-installation selection. Transport authentication and cross-process broker isolation were not established by the inspected repository evidence, so the remaining proof gap cannot be treated as either an exploit or demonstrated isolation.
Resilience and Maintainability Implications
observed — Transaction failure before approval commit preserves the prior grant/key relationship and rolls back newly issued credentials. Revocation makes a cached bearer invalid rather than requiring plugin restart. These controls contain partial failure during normal operation, but do not address the separate migration-down ownership loss.
Hardening Proposals
proposed — Define a credential-safe downgrade transition that revokes issued keys before dropping their ownership records, or prevents reversal until explicit credential cleanup completes. Preserve the distinction between ordinary rollback of an approval transaction and operational reversal of the schema.
Pre-merge checks: 4 · 1
Failed checks: 1 inconclusive
Check name
Status
Explanation
Resolution
Docstring Coverage
Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…
Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed checks: 4 passed
Check name
Status
Explanation
Title check
The title "feat(plugins): approve plugin permissions and issue scoped host API keys" matches the main change. The changeset adds permission grants, guarded approval endpoints, and scoped host API key …
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description covers plugin permission approvals, scoped API keys, event access gating, and the admin UI changes.
Full details: Title check
Explanation
The title "feat(plugins): approve plugin permissions and issue scoped host API keys" matches the main change. The changeset adds permission grants, guarded approval endpoints, and scoped host API key issuance for plugin installations, and the title names both. The title is specific, concise, and in one sentence.
Full details: Docstring Coverage
Explanation
Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 45 functions across 38 files. (9 skipped: 8 unsupported, 1 too large.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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) {
The reason will be displayed to describe this comment to others. Learn more.
Expose capability discovery for plugin permission approval
The new permission-management API has no capability endpoint: a repository-wide search of the v2 route registrations and committed OpenAPI finds the installation-specific read and approval operations, but no discovery operation advertising this feature. Clients supporting servers both with and without this change therefore cannot discover approval support through the prescribed capability mechanism. Add a capability endpoint that reports whether permission management is configured. This violates the explicit requirement in AGENTS.md that new features expose a capability endpoint.
The reason will be displayed to describe this comment to others. Learn more.
Not adding one here. /api/v2 has no capability document for admin plugin management: these routes serve the web admin, which ships with the server, and no native client manages plugins. A client can tell a server has permissions from permissions_pending on installations and from the permissions route itself. A capability document for admin plugin features would be a new contract surface with one consumer, so I'd rather add it when a second consumer needs it. Leaving this open in case a maintainer disagrees.
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.", "")
Expose capability discovery for plugin permission approval
The new permission-management API has no capability endpoint: a repository-wide search of the v2 route registrations and committed OpenAPI finds the installation-specific read and approval operations, but no discovery operation advertising this feature. Clients supporting servers both with and without this change therefore cannot discover approval support through the prescribed capability mechanism. Add a capability endpoint that reports whether permission management is configured. This violates the explicit requirement in AGENTS.md that new features expose a capability endpoint.
ADD COLUMN host_api_scopes text[] NOT NULL DEFAULT '{}';
Backfill requested scopes for existing plugin installations
When upgrading a server with an already-installed plugin whose manifest declares host_api_scopes, this migration initializes its requested scopes to an empty array. Only the install/replace paths populate the column; EnsurePermissionGrants carries over event access without reading manifest scopes, and preloading does not populate them either. Consequently, the permissions API reports no requested API access, approval cannot issue a key, and GetHostAPICredential remains unavailable until the plugin is replaced or reinstalled. Backfill the requested scopes from the stored manifests, without automatically approving them.
coderabbitaiBot
added
api-v2
API v2 / Huma migration program (epic #135); long-running, stacked by phase
evidence-required
Needs before-and-after evidence before the Evidence check passes
go
Pull requests that update go code
javascript
Pull requests that update javascript code
needs-review
Needs maintainer review to resolve uncertain classification, scope, or changed evidence.
size/XXL
1000–2999 added + deleted lines (all files); change volume, not priority.
labels
Nov 5, 2026
Plugin management / marketplace — Server #1224 C1 (Server, build 1669 · 5ec82048): Installation and update now persist permission grants, and event delivery is gated by those grants; plugins requesting host API scopes may need approval before they can use that access.
Plugin management / marketplace — Web admin #1225 C1 (Web admin, build 1669 · 5ec82048): The new permissions panel, approval flow, pending badge and attention status change what administrators see and what a newly installed scoped plugin can do.
The PR must explain why these previously validated install/usable behaviors change; both C1 cases need re-validation after merge.
Minor change
Plugin management / marketplace — Web admin #1225 C2 (Web admin, build 1669 · 5ec82048): Installed plugin tiles or details may gain a permissions badge/panel. The catalog opt-in, tier labels and notices remain unchanged; re-check after merge.
The current Validation tasks: line omits #1224 C1 and #1225 C2.
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.
…publish request events off the request path
A catalog event whose payload failed projection was still queued, with an
empty payload, so plugins received it even though the log said it was
dropped. The dispatcher now drops it before it reaches the outbox.
Request events for plugins are published on a detached goroutine with their
own deadline, like the server-channel post beside them, so a request
transition never waits on the hub's Redis publish.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reconcile pass loaded fulfilled requests without resolving the
requester, so the request.fulfilled plugin event always went out with an
empty requester_name. Resolve the requester before the announcement, as
the other lifecycle transitions do, and keep the server-channel
"Request fulfilled" post unchanged: it still does not name the requester.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…alled
Uninstalling deleted the plugin's host API key with a raw DELETE, so the
audit log showed the key's creation at approval but never its deletion.
An administrator's uninstall now goes through
PermissionService.DeleteInstallation, which deletes the key with
HostAPIKeyIssuer.RevokeTx in the uninstall's transaction, after taking
the account locks first as every key deletion does, and publishes the
audit entry once the transaction commits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… grants
The migration starts every installation's host_api_scopes empty, and only
installing or replacing a plugin writes them. An installation whose stored
manifest already asked for scopes, installed by a server that ignored the
field, showed no requested API access after the upgrade, so it could never
be approved for a key until it was reinstalled.
When the boot pass writes an installation's first grant, it now also
records the host_api_scopes of its stored manifest, unapproved, so the
installation shows as pending until an administrator approves them. A
manifest that is missing or doesn't decode records none and doesn't block
startup.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…changes
The SDK commit merges the final heads of Silo-Server/silo-plugin-sdk
#57-#62: the event catalog, scoped host API keys, notification channels,
conditional instance state writes, default task schedules and host
viewer headers. Plugin event names now need a publisher and an event
name; every name the server uses already has both.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On the visible-change evidence note: the PR body's Evidence section now links the published page, https://evidence.siloserver.org/r/silo-server/pr-3549/, covering the web admin plugin list and plugin page at desktop and phone widths. The Evidence check passes.
Agreed on #1224 C1: installing and updating a catalog plugin now record permission grants, and an update that asks for more stays pending while the plugin keeps its old grant. The description's Validation tasks: line now reads changes #1224 C1; changes #1225 C1, with a re-check note under Risks. #1225 C2 isn't affected: catalog settings, the community opt-in and the tier labels don't change.
Thanks for adding #1224 C1. The Validation tasks: line still omits #1191 C1 and #1225 C2: plugin-issued keys now appear as revocable rows on the API Keys page, and installed-plugin tiles/details may show permission status.
Request lifecycle events for plugins were published on their own goroutines,
so an auto-approved request could reach plugins as request.approved before
request.submitted, and an event published after the plugin dispatcher
unsubscribed at shutdown was lost.
They now publish inline in the caller's goroutine, like the hub's other
callers. The hub hands the event to local subscribers, the plugin dispatcher
among them, before it publishes to Redis, so plugin delivery never waits on
Redis. The Redis publish ignores the caller's cancellation, since the
transition has already committed, and is bounded at five seconds.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agreed on both. The line now reads changes #1191 C1; changes #1224 C1; changes #1225 C1, C2, with re-check notes under Risks: an approved plugin key shows on the API keys page and can be revoked there, and a plugin waiting for approval shows a badge and banner beside the tier labels.
A full restore keeps the live server's API keys, so a plugin's grant now
comes from the live server too, for the installations the restored data
has. A grant names its key only where the carry kept that key; otherwise
it keeps its approvals without one, the plugin waits for approval, and
the restore reports it. An approver the backup lacks is cleared instead
of failing the restore on the foreign key.
The plugin release carry also copies the requested host API scopes, and
an installation whose id is another plugin here comes back off without
the other plugin's grant.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the jellycompat test compile fix from #3552 so the Go jobs
build again. The merge applied cleanly with no conflicts; regenerating
the OpenAPI document, route inventory, fixtures, and web types produced
no changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The base now merges current main (cbdf5fb). The merge had no
conflicts, and regenerating the OpenAPI document, route inventory,
fixtures, web types and route manifest changed nothing.
Empty contracts/api/v2/breaking-approvals.json. Main still carries two
listAdminBackups approvals from #3402, and the contract policy rejects
approvals that match no change whenever openapi.json differs from the
base. This branch's /api/v2 changes are additive (new permission
operations and a required permissions_pending response field), so none
needs an approval.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… plugin envelopes local
The SDK's event catalog now makes every identifier a JSON string and no
longer has the request.* events.
- Pin silo-plugin-sdk to the integration commit with those changes.
- The dispatcher converts a catalog payload's numeric id and *_id fields to
strings before projecting it, and drops a zero ID (a server-queued job has
no creator). The events socket keeps its numeric IDs.
- Remove the request.* publishers and the request-path changes that only
served them.
- The hub keeps ChannelPlugins envelopes on the publishing server: no client
receives that channel and other servers' dispatchers drop them.
- RuntimeHost.PublishEvent asks the hub whether a plugin event could have
subscribers before it encodes and publishes the envelope.
- The catalog contract test runs producer output through the dispatcher's
conversion and checks IDs arrive as strings.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…p the scope backfill
A replacement that asked for fewer host_api_scopes left the approved key in
place until an administrator approved again, so the plugin kept scopes its
new manifest no longer asks for. The replacement's transaction now locks the
grant's key and the grant before the installation row (the order uninstall
uses), and when the key carries a scope outside the new list it deletes the
key and clears the approved scopes. The installation is keyless, and pending
while it still asks for scopes.
Also remove the boot pass that recorded host_api_scopes from stored
manifests (reverts 037771a). Installations from before host_api_scopes
was recorded ask for none until their next update records them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Closing this draft. The API key scope picker (#3610) covers scoped access for plugins, and this branch has fallen behind the rebased event catalog work in #3547. The branch stays in place in case approval of sensitive events comes back as its own change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
api-v2API v2 / Huma migration program (epic #135); long-running, stacked by phaseenhancementNew feature or requestevidence-requiredNeeds before-and-after evidence before the Evidence check passesgoPull requests that update go codeimpact: securityAuth, privacy, or permission boundaryjavascriptPull requests that update javascript codeneeds-reviewNeeds maintainer review to resolve uncertain classification, scope, or changed evidence.priority: P2Limited scope, workaround exists, or polishsize/XXXL3000+ added + deleted lines (all files); change volume, not priority.stackedBase is another open PR; merge in stack order named in the body
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Parked. This draft won't merge for now. Admins who want a plugin to call the admin API will
create a scoped API key for it themselves, through a scope picker on the API keys page (a
separate pull request). Plugin permissions will be revisited later; this branch keeps the work
and its fixes until then.
Stacked on #3547. This pull request's own changes are the commits after the merges of
feat/plugin-event-catalog.Problem
Related issue: N/A
Validation tasks: none while parked. If revived, it changes #1191 C1, #1224 C1 and #1225 C1, C2.
Installing a plugin gives it admin activity and every profile's personal data whenever it
subscribes to those events, with no administrator consent. Plugins that call the admin API ask
administrators to paste a full-access API key into plugin settings.
This change makes an installation ask for permissions, records what an administrator approves, and
issues the plugin a key with only the approved scopes.
Approach
classes of the catalog events it subscribes to, and the manifest's
host_api_scopesthat the APIkey scope catalog knows.
plugin_permission_grantsrecords what an administrator approved.event classes they already subscribe to. An upgrade never widens a grant: new requirements stay
pending, and the plugin runs with its old grant until an administrator approves.
upgrade's own transaction and clears the approved scopes, so the plugin never keeps a key wider
than its manifest asks for. It is keyless, and pending while it still asks for scopes.
that class. Approval runs the plugin lifecycle path, so every API server picks it up without a
plugin restart.
ETagcovers thewhole response, and the approval is a guarded PUT whose
If-Matchis compared inside theapproval's transaction; a plugin update, another approval or a revoked key in between is 412 and
writes nothing. The web panel then reloads and shows the new requirements.
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 until someone approves again.
for plugin configs and state, because it also keeps the live server's API keys. A grant whose
key the restore dropped keeps its approvals and waits for the plugin to be approved again; an
installation ID that now belongs to a different plugin loses that plugin's grant.
HostAPICredentials.GetHostAPICredentialreturns the key to the calling installation only.Uninstalling deletes the key in the same transaction as the installation.
GET .../installations/{id}/permissions, a guardedPUT .../permissions/approval, andpermissions_pendingon installations. The web plugin pagegains a Permissions panel with an Approve button; on the plugin list, a plugin waiting for
approval shows a badge and counts under "Needs attention".
Validation
make lint-changed,verify-apiv2-contract,verify-apiv2-openapi,verify-apiv2-web-types,verify-route-inventory,verify-migrations,verify-migration-ledger, and the tests ofinternal/plugins,internal/backup,internal/auth,internal/api/...,internal/apiv2/...,internal/eventsandinternal/pluginhostagainst a freshly migrated Postgres: pass. The permissions database testcovers an upgrade that narrows the scopes and one that drops them.
admin:monitor:read: no key before approval; approval withoutIf-Match428, with a stale tag412, with the current tag 200, and a replay of the old tag 412; its key then read active
sessions (200) and was refused on API keys (403); uninstalling removed the key. That check
hasn't been repeated on this head.
Evidence
Evidence: https://evidence.siloserver.org/r/silo-server/pr-3549/
Surface and build: web admin plugin list and plugin page, desktop and phone widths, an earlier head
of this branch.
Risks
20261104202747_add_plugin_permission_grants.sql; a startup pass records grants forexisting installations before the catalog auto-update runs.
host_api_scopeswas recorded ask for no scopes until their nextupdate or reinstall records them.
acts; uninstalling and the API keys page still audit theirs.
account, unusable, until someone deletes it on the API keys page. Fixing that means changing
how a restore copies
api_keys; it's noted under Limits indocs/architecture/plugin-permissions.md.permission grants, and an update that asks for more stays pending while the plugin keeps its
old grant. Re-check API keys — Web admin #1191 C1: a plugin's approved key appears on the API keys page and can be
revoked there, which leaves the plugin pending. Re-check Plugin management / marketplace — Web admin #1225 C1 and C2: the plugin page shows
a Permissions section, the plugin list counts a plugin waiting for approval under "Needs
attention", and installed plugins waiting for approval show a badge on their tile and a banner
on their page, next to the tier labels.
v0.32.2-0.20261106014723-f52642897933, a pre-release of the SDKplugin notification changes (feat(runtimehost): issue plugins a scoped host API key silo-plugin-sdk#58, also parked, is the one this
needs).
Checklist
AI Disclosure
for privilege escalation and races. It found that an approval could apply requirements newer than
the ones shown, that a demoted administrator's key stayed valid, and that replacing a key could
leave the plugin without one; all three are fixed. A later four-agent review found that an
upgrade narrowing the scopes left the wider key working; that is fixed too.
🤖 Generated with Claude Code
Note
Add plugin permission grants with admin approval and scoped host API keys
GET/PUTon installation permissions) with ETag-based conditional reads and guarded approval viaIf-Match(admin_plugin_permissions.go).EventDispatcher.buildIndexrebuilds on approval via the plugin-change cache event.GetHostAPICredentialruntime RPC, which returns only the calling installation's token and scopes (runtime_host_server.go).permissions_pendingbadge on plugin tiles, a permissions review panel, and an approval mutation that sends the read ETag and surfaces 412 conflicts.EnsurePermissionGrantsbefore preloading enabled plugins and exits on failure; public and plugin events remain deliverable without approval, and failure to load approvals prevents a complete event index build.Macroscope summarized 6ff587b.