federation

What this skill does

# 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`