Federated Registry Protocol

Overview

The Federated Registry Protocol enables plugin resolution across multiple registries with configurable priority, security policies, conflict detection, and deterministic lockfiles. It transforms plugin management from a single-source package manager into an enterprise-grade multi-source orchestration system.

Architecture

                  +-----------------+
                  | RegistryClient  |  Fetches and caches registry indexes
                  +--------+--------+
                           |
                  +--------v--------+
                  | RegistryResolver|  Resolves plugins across registries
                  +--------+--------+
                           |
                  +--------v--------+
                  |  PolicyEngine   |  Evaluates allow/deny/require rules
                  +--------+--------+
                           |
                  +--------v--------+
                  | LockfileManager |  Deterministic version pinning
                  +-----------------+

Components

RegistryClient

Loads configuration from .claude/registries.json and fetches plugin indexes from multiple sources. Supports local filesystem directories and remote HTTP(S) URLs.

Key behaviors:

Caches registry data with configurable TTL (default: 1 hour)
Graceful degradation when registries are unavailable
Token and OIDC authentication support
Local directory scanning builds indexes from plugin manifests

RegistryResolver

Resolves plugin names across all configured registries in priority order (highest first).

Conflict detection:

Same plugin name in multiple registries is detected via SHA-256 content hash comparison
Resolution strategies: highest-priority (default), error, prompt
All conflicts are recorded for audit trail

PolicyEngine

Evaluates security rules from .claude/policies/plugins.yaml using short-circuit matching (first match wins).

Rule types:

allow — Permits the plugin
deny — Blocks the plugin with a reason
require — Warns when mandatory plugins are missing

Unless clause: Exempts matching plugins when ALL conditions are met (trust score threshold, signature verification).

LockfileManager

Produces plugin-lock.json for reproducible plugin environments.

Capabilities:

Generate lockfile from current resolved state
Detect drift between lockfile and installed plugins
Produce human-readable diffs for PR reviews
Install from lockfile for deterministic environments

Workflow

Setting Up Federation

Configure registries with priorities:

/mp:registry add local ./plugins --priority 100
/mp:registry add team https://plugins.team.dev/index.json --priority 75
/mp:registry add public https://marketplace.claude.dev/registry.json --priority 0

Define security policy in .claude/policies/plugins.yaml
Sync registry caches:
```
/mp:registry sync
```

Installing Plugins

Resolve plugin across registries (highest priority first)
Check policy engine for allow/deny decision
Install from the resolved source
Update the lockfile:
```
/mp:lock generate
```

CI/CD Integration

Commit plugin-lock.json to version control
In CI: mp:lock check to verify no drift
In deployment: mp:lock install for reproducible environment
In PRs: mp:lock diff to review plugin changes

Policy Enforcement

Define rules in .claude/policies/plugins.yaml
Audit installed plugins: /mp:policy enforce
Check individual plugins: /mp:policy check <name>

Configuration Files

File	Purpose
`.claude/registries.json`	Registry sources and federation settings
`.claude/policies/plugins.yaml`	Security policy rules
`plugin-lock.json`	Deterministic version lock
`config/registries.default.json`	Default registry configuration
`config/policies.default.yaml`	Default security policy

Commands

Command	Description
`/mp:registry add`	Add a registry source
`/mp:registry remove`	Remove a registry
`/mp:registry list`	Show configured registries
`/mp:registry sync`	Refresh all caches
`/mp:policy check`	Check a plugin against policy
`/mp:policy list`	Show policy rules
`/mp:policy enforce`	Audit installed plugins
`/mp:lock generate`	Create lockfile from current state
`/mp:lock check`	Verify plugins match lockfile
`/mp:lock diff`	Show changes since last lock
`/mp:lock install`	Install from lockfile

Source Code

Types: src/federation/types.ts
Engine: src/federation/registry.ts
Config: config/registries.default.json
Policy: config/policies.default.yaml

federation