browser/openspec/changes/implement-plugin-registry-and-manifest-validation/design.md

Context

The platform already has a basic GamePlugin resource in platform/ and an initial JSON Schema validator in plugins/. Those pieces are not yet enough for the plugin marketplace and server creation backlog because registration can still be assembled by hand instead of coming from a validated game management plugin manifest.

This change covers the first registry boundary between plugins/ and platform/: plugin authors validate manifest files in the plugin workspace, while the platform accepts a structured manifest registration payload, validates the same safety constraints in backend validators, stores only registry metadata, and exposes that metadata through the existing game plugin APIs.

Goals / Non-Goals

Goals:

• Define one concrete manifest contract for game management plugins.
• Reject unsafe manifest requests for raw run, host path, credential, socket, and raw AI key access.
• Register installed plugins from manifest metadata through platform DTO/service/API layers.
• Keep registry responses useful for plugin marketplace display without exposing raw paths, raw credentials, run internals, or AI provider keys.
• Add focused schema, validator, service, and API tests.

Non-Goals:

• Do not implement plugin page bridge runtime, plugin action execution, or SDK transport.
• Do not add billing, cloud host sales, provider marketplaces, or unrelated SaaS marketplace behavior.
• Do not make platform import TypeScript plugin validation code or plugin workspace files directly.
• Do not implement frontend plugin marketplace pages in this change.

Decisions

Decision 1: Use a copied manifest contract at the root boundary

plugins/ owns the JSON Schema and TypeScript validation helper. platform/ owns named DTOs and domain types that mirror the externally submitted manifest shape. The two roots are kept aligned by tests and OpenSpec requirements rather than direct imports.

Alternative considered: have platform read plugins/manifests/game-plugin.manifest.schema.json directly. Rejected because that would make the backend depend on the plugin workspace file layout and blur root ownership.

Decision 2: Platform registration converts manifests to existing registry metadata

The platform will add a manifest registration service/API path that converts a validated manifest into GamePlugin registry metadata. The existing create/list/detail endpoints remain available for low-level metadata tests and future migration, while the new manifest endpoint is the supported installation boundary for plugin manifests.

Alternative considered: replace GamePluginCreateRequest with the manifest shape. Rejected because existing server-management tests and API contracts already use the metadata resource directly.

Decision 3: Deny unsafe permissions by explicit allowlists and substring checks

Plugin manifests may declare scoped permissions such as server lifecycle, file, log, artifact, and platform-mediated AI permissions. They must not declare direct run sockets, raw host paths, raw credentials, raw AI keys, provider keys, or direct run credentials. plugins/ catches these during schema/test validation and platform/ repeats the safety validation before registry insertion.

Alternative considered: rely only on JSON Schema enum restrictions. Rejected because unsafe intent can appear in action paths, capability names, or future fields; backend validation still needs an explicit defense.

Decision 4: Registry metadata is marketplace-ready but not commerce-oriented

Registry responses include identity, version, server type/display name, manifest/schema references, required run capabilities, permissions, pages, and AI purposes. They intentionally exclude pricing, cloud host purchase flows, and provider marketplace concepts.

Alternative considered: add a richer marketplace catalog model now. Rejected because the repository scope is game server management, and later UI can derive its first catalog view from registry metadata.

Risks / Trade-offs

• [Risk] The plugin manifest contract may evolve when plugin bridge work starts. Mitigation: keep this change focused on registry metadata and add bridge-specific fields in the next OpenSpec change.
• [Risk] Duplicating contract shapes across TypeScript and Go can drift. Mitigation: tests cover the example manifest and platform manifest registration until a generated contract package is introduced.
• [Risk] Strict allowlists can reject useful future plugin capabilities. Mitigation: add new allowed capability/permission keys through explicit OpenSpec changes.

Migration Plan

1. Add plugin schema restrictions, fixtures, and validation tests while keeping the development example valid.
2. Add platform manifest DTO/domain conversion, validators, service registration, and API route tests.
3. Keep existing POST /api/v1/game-plugins metadata creation working for current tests.
4. Validate the change with plugin tests, platform tests, structure check, and strict OpenSpec validation.

Rollback during this phase is straightforward: remove the manifest registration route and schema/test additions before downstream plugin bridge work depends on them.

Open Questions

• Whether manifest contract generation should be added in the plugin bridge change or a later contract-generation change.
• Whether registry metadata should eventually support signed manifest artifacts before plugin publish/install workflows are implemented.