Skip to content

feat(runtimehost): issue plugins a scoped host API key - #58

Closed
Quick104 wants to merge 3 commits into
mainfrom
feat/host-api-scopes
Closed

Quick104 wants to merge 3 commits into
mainfrom
feat/host-api-scopes

Conversation

@Quick104

@Quick104 Quick104 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Plugins that read the host's admin API (active sessions, users, libraries) ask administrators to
paste a full-access API key into plugin settings. The key carries every scope, outlives the plugin,
and is stored as an ordinary setting.

Approach

The manifest declares host_api_scopes. The host issues a key with exactly the scopes an
administrator approved, and HostAPICredentials.GetHostAPICredential returns it with the API base
URL. runtimehost.Client.HostAPICredential wraps the call; it returns ErrHostAPINotGranted when
nothing is approved and ErrHostAPIUnsupported on a host without the service.

The RPC is its own HostAPICredentials service on the runtime host connection, not a new method on
RuntimeHost: a new method on a released service changes its generated interfaces and breaks mocks
that don't embed the Unimplemented type (docs/compatibility.md).

The validator checks each scope's shape and rejects repeats; the scope vocabulary belongs to the
host. docs/permissions.md explains how a host derives an installation's permissions from its
subscriptions and scopes.

Compatibility and release

Additive: manifest field 14 and a new service. A host without the service answers UNIMPLEMENTED,
which the client reports as ErrHostAPIUnsupported. A plugin that declares host_api_scopes needs
a Silo server that includes Silo-Server/silo-server#2502: an older server refuses to install it
from a bare binary and won't start it from an archive, because it doesn't know the field (see
docs/compatibility.md).

Related changes

Validation

  • go test ./..., go vet ./... and every example build: pass.
  • gofmt -l . lists only pkg/pluginsdk/runtime/scan_source_test.go, which is unformatted on main
    and not touched here.
  • Regenerating the protobuf code with the repo's buf leaves it unchanged. make proto itself stops
    at its protoc check on this machine, though generation doesn't use protoc.
  • On a test server and on shared dev, a plugin asking for admin:monitor:read got no key until an
    administrator approved; its key then read active sessions (200) and was refused on API keys (403).

AI Disclosure

  • Harness: Claude Code, run from T3 Code
  • Tool(s): Claude Code (implementation); Codex CLI (independent review)
  • Model(s): claude-opus-5-5 (implementation); gpt-6.1-sol (review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: the same Codex (gpt-6.1-sol) review. It found that the first version added the
    RPC to RuntimeHost, which breaks existing implementers; it moved to its own service. It also
    fixed a docs example that returned a nil credential on its error paths.

🤖 Generated with Claude Code

Quick104 and others added 2 commits November 4, 2026 15:07
Plugins that read the host's admin API ask administrators to paste a
full-access API key. Let the manifest declare the API key scopes it needs
(host_api_scopes) instead: the host issues a key with exactly the approved
scopes, and GetHostAPICredential returns it with the API base URL.

The validator checks each scope's shape and rejects repeats. The scope
vocabulary is the host's and stays open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adding GetHostAPICredential to the released RuntimeHost service changed
its generated interfaces, so a host or plugin-side mock implementing them
without embedding the Unimplemented type stopped compiling. Move it to a
HostAPICredentials service that the host serves on the same connection,
as docs/compatibility.md asks for new RPCs; a host without it answers
UNIMPLEMENTED. Fix the permissions doc example, which used a nil
credential on its error paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 84 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 5ab19d42-cc04-45d4-b018-245cafcabb12
Commits

Reviewing files that changed from the base of the PR and between 484878a and 7ed9ecd.

Files ignored due to path filters: 3

  • pkg/pluginproto/silo/plugin/v1/common.pb.go is excluded by !**/*.pb.go
  • pkg/pluginproto/silo/plugin/v1/runtime_host.pb.go is excluded by !**/*.pb.go
  • pkg/pluginproto/silo/plugin/v1/runtime_host_grpc.pb.go is excluded by !**/*.pb.go
Files selected for processing: 12

  • README.md
  • docs/compatibility.md
  • docs/permissions.md
  • docs/runtime-host.md
  • pkg/pluginsdk/manifest/host_api_scopes.go
  • pkg/pluginsdk/manifest/host_api_scopes_test.go
  • pkg/pluginsdk/manifest/manifest.go
  • pkg/pluginsdk/runtimehost/client.go
  • pkg/pluginsdk/runtimehost/host_api.go
  • pkg/pluginsdk/runtimehost/host_api_test.go
  • proto/silo/plugin/v1/common.proto
  • proto/silo/plugin/v1/runtime_host.proto
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/XL 500–999 added + deleted lines (all files); change volume, not priority. label Nov 5, 2026
@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-05T16:24:00.222171Z 7ed9ecd New commits
🔒 Security Review ✅ Completed 2026-11-05T16:25:39.014121Z 7ed9ecd New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

The field comment said older hosts ignore host_api_scopes. Silo hosts built
before Silo-Server/silo-server#2502 parse a bare plugin binary's manifest
strictly and compare the installed manifest with the live one including
unknown fields, so they refuse to install or start a plugin that sets it.
Scope the comment to that and note it in docs/compatibility.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 3 Kody Rule(s) were not evaluated

These rules declare that they need repository context beyond this diff, and the review could not retrieve it, so they were not judged on this pull request:

  • Share optional authentication service resolution across interface types
  • Find the last complete-line boundary with bounded memory
  • Identify the actual first SDK release containing new Go APIs

@Quick104
Quick104 marked this pull request as draft November 6, 2026 01:48
@Quick104

Quick104 commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Parked as a draft. For now, an administrator can create a scoped API key on the API keys page and paste it into a plugin's settings. Plugin permissions and host-issued keys come back when plugins are isolated enough for approval to mean something. The host side, Silo-Server/silo-server#3549, is parked too.

@Quick104

Copy link
Copy Markdown
Contributor Author

Closing this draft. Administrators can now create scoped API keys in Silo (Silo-Server/silo-server#3610), which covers what this was for, and the branch conflicts with main (PluginManifest field 14 is now stay_running). The branch stays in place.

@Quick104 Quick104 closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update go code size/XL 500–999 added + deleted lines (all files); change volume, not priority. triaged High-confidence review completed; does not mean fixed, validated, or accepted for release.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant