markus41/federation

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

1. 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
   

2. Define security policy in .claude/policies/plugins.yaml

3. Sync registry caches:

   /mp:registry sync
   

Installing Plugins

1. Resolve plugin across registries (highest priority first)
2. Check policy engine for allow/deny decision
3. Install from the resolved source
4. Update the lockfile:

   /mp:lock generate
   

CI/CD Integration

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

Policy Enforcement

1. Define rules in .claude/policies/plugins.yaml
2. Audit installed plugins: /mp:policy enforce
3. 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