Federation Deployment Guide¶

This guide covers the setup and configuration of SkillMeat enterprise federation, enabling secure cross-organization artifact sharing with cryptographic trust verification.

Prerequisites¶

Before deploying federation:

SkillMeat Enterprise Edition installed and running
Python 3.9+ with the cryptography library (included with SkillMeat)
Organization identifier (slug) — DNS-compatible, 2-63 characters, e.g., acme-corp
Network connectivity to federation peers' HTTPS endpoints
Administrator access to configure environment variables and settings

For organizations with existing PKI infrastructure, bring-your-own CA is supported via cross-signing (see ADR-018).

Phase 1: Core Configuration¶

Step 1.1: Set Your Organization Slug¶

The organization slug uniquely identifies your deployment in the federation network:

export SKILLMEAT_ORG_SLUG="your-org-name"

Use lowercase alphanumeric characters and hyphens only. Examples: acme-corp, partner-labs, research-team.

Verify:

curl http://localhost:8080/api/v1/federation/status | jq '.org_slug'
# Should return: "your-org-name"

Step 1.2: Enable Federation¶

Federation is an enterprise-edition feature controlled by a feature flag:

export SKILLMEAT_EDITION="enterprise"
export SKILLMEAT_DVCS_FEDERATION_ENABLED="true"

Restart the API server:

# Stop current instance
pkill -f "uvicorn.*skillmeat"

# Start with new config
skillmeat web dev --api-only
# or for production:
# uvicorn skillmeat.api.server:app --workers 4 --host 0.0.0.0 --port 8080

Verify: The endpoint /api/v1/federation/trust-policies should now return 200 OK instead of 404 Not Found.

Step 1.3: Configure Sync Scheduler (Optional)¶

Federation runs a background sync job to pull artifact updates from trusted peers. Customize the timing:

# Check for new artifacts every 1800 seconds (30 minutes) — default is 3600 (1 hour)
export SKILLMEAT_DVCS_FEDERATION_SYNC_INTERVAL_SECONDS="1800"

# Process up to 100 artifact versions per sync cycle — default is 50
export SKILLMEAT_DVCS_FEDERATION_SYNC_BATCH_SIZE="100"

# Limit blob fetching to 1000 MB per cycle — default is 500 MB
export SKILLMEAT_DVCS_FEDERATION_MAX_BLOB_FETCH_MB="1000"

These values prevent runaway resource usage when syncing large numbers of artifacts. Adjust based on network bandwidth and storage capacity.

Phase 2: Establishing Trust Relationships¶

Trust relationships in federation are bilateral: Organization A must explicitly trust Organization B by creating a trust policy. This policy defines:

Which peer org is trusted
How strongly to trust them (none, verified, full)
What artifact types to accept
Whether signatures are required

Step 2.1: Create a Trust Policy¶

Use the API to create a trust policy for a federation peer:

curl -X POST "http://localhost:8080/api/v1/federation/trust-policies" \
  -H "Content-Type: application/json" \
  -d '{
    "trusted_org_slug": "partner-labs",
    "trust_level": "verified",
    "allowed_artifact_types": ["skill", "command", "workflow"],
    "signature_requirement": "required",
    "sync_interval_seconds": 3600,
    "trusted_cert_fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "expires_at": "2027-04-13T00:00:00Z",
    "allowed_regions": ["us-east-1", "eu-west-1"]
  }'

Response (201 Created):

{
  "id": "policy-uuid-here",
  "org_id": "your-org-name",
  "trusted_org_slug": "partner-labs",
  "trust_level": "verified",
  "allowed_artifact_types": ["skill", "command", "workflow"],
  "signature_requirement": "required",
  "sync_interval_seconds": 3600,
  "trusted_cert_fingerprint": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "expires_at": "2027-04-13T00:00:00Z",
  "allowed_regions": ["us-east-1", "eu-west-1"],
  "created_at": "2026-04-13T10:30:00Z",
  "updated_at": "2026-04-13T10:30:00Z"
}

Step 2.2: Understanding Trust Levels¶

Level	Description	Use Case
`none`	Blocks all artifacts from this peer	Revoke trust temporarily without deleting the policy
`verified`	Certificate must be valid and non-revoked	Standard production trust — cryptographic verification required
`full`	Mutual bidirectional trust	Integrated team deployments (rare; use `verified` for security)

Default to verified for new policies. Only use full when peer is tightly integrated and under the same administrative domain.

Step 2.3: Obtain Peer Certificate Fingerprints¶

To establish trust with a peer, you need their certificate's SHA-256 fingerprint. Request it from the peer administrator:

# Peer admin runs this to get their cert fingerprint:
openssl x509 -in /path/to/org-cert.pem -outform der | openssl dgst -sha256 -hex

# Output: (stdin)= a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Share this fingerprint through a secure, out-of-band channel (email, secure messaging, in-person). The peer will do the same for you.

Phase 3: Certificate Management¶

Step 3.1: Obtain Your Organization Certificate¶

Federation uses X.509 certificates to verify artifact signatures. Your certificate is issued by the SkillMeat root CA during enterprise enrollment.

Check certificate expiry:

curl -s "http://localhost:8080/api/v1/federation/status" | jq '.cert_expiry_warnings'

Step 3.2: Certificate Rotation¶

Certificates expire after 2 years. Rotation is handled automatically by SkillMeat, but monitor the health endpoint:

curl http://localhost:8080/health | jq '.federation'

Look for warnings 30 days before expiry. Contact support to request certificate renewal before expiry.

Step 3.3: Handle Certificate Revocation¶

If a peer org is compromised or you need to immediately block their artifacts:

Step A: Set trust level to none

curl -X PATCH "http://localhost:8080/api/v1/federation/trust-policies/{policy_id}" \
  -H "Content-Type: application/json" \
  -d '{"trust_level": "none"}'

Step B: Check the CRL (Certificate Revocation List)

SkillMeat automatically checks the CRL every hour. The check is configurable:

# Force immediate CRL refresh
curl -X POST "http://localhost:8080/api/v1/federation/crl-refresh"

# Verify CRL status
curl http://localhost:8080/api/v1/federation/status | jq '.crl'

If CRL fetch fails (network issue or peer unavailable), federation defaults to fail-closed — artifacts are rejected until CRL is validated. This is the secure default; for high-availability setups, configure a local CRL cache.

Phase 4: Sync and Monitoring¶

Step 4.1: Manual Sync¶

Trigger a sync cycle manually to pull updates from trusted peers:

curl -X POST "http://localhost:8080/api/v1/federation/sync" \
  -H "Content-Type: application/json" \
  -d '{"mode": "full"}'

Response:

{
  "cycle_id": "sync-123abc",
  "status": "completed",
  "peers_synced": 3,
  "artifacts_fetched": 47,
  "blobs_fetched": 152,
  "bytes_fetched": 5242880,
  "duration_seconds": 42.5,
  "skipped_peers": [
    {
      "org_slug": "inactive-org",
      "skipped": true,
      "reason": "trust_level is 'none' — sync disabled for this org"
    }
  ],
  "started_at": "2026-04-13T12:00:00Z",
  "completed_at": "2026-04-13T12:00:42Z"
}

Step 4.2: Monitor Sync Status¶

Check the status of the background sync scheduler:

curl http://localhost:8080/api/v1/federation/status | jq '.{sync_enabled, active_policies, total_federated_artifacts, last_sync_at}'

Expected output:

{
  "sync_enabled": true,
  "active_policies": 2,
  "total_federated_artifacts": 147,
  "last_sync_at": "2026-04-13T12:00:42Z"
}

Step 4.3: List Trust Policies¶

View all configured trust policies:

curl "http://localhost:8080/api/v1/federation/trust-policies?limit=50"

Troubleshooting¶

Sync Not Running¶

Symptom: sync_enabled is false or active_policies is 0.

Solutions: 1. Verify federation is enabled: SKILLMEAT_DVCS_FEDERATION_ENABLED=true 2. Verify edition is enterprise: SKILLMEAT_EDITION=enterprise 3. Create at least one trust policy with trust_level != "none" 4. Check server logs for errors: tail -f skillmeat-api.log | grep federation

Certificate Expiry Warnings¶

Symptom: Artifacts from a peer are rejected with "certificate expired" error.

Solutions: 1. Check peer's certificate status: Ask peer to run health check 2. Request certificate renewal from support@skillmeat.io 3. Temporarily lower trust_level to none and raise when renewed

CRL Fetch Failure¶

Symptom: Sync skipped with error "CRL fetch failed".

Solutions: 1. Verify network connectivity: curl https://crl.skillmeat.io/root-ca.crl 2. Check firewall rules allow outbound HTTPS to crl.skillmeat.io 3. Verify proxy settings if behind corporate firewall 4. For air-gapped deployments, configure local CRL cache (contact support)

Trust Level `none` Blocking Artifacts¶

Symptom: Artifacts from a peer aren't syncing.

Check:

curl "http://localhost:8080/api/v1/federation/trust-policies" | \
  jq '.policies[] | select(.trusted_org_slug == "peer-name") | .trust_level'

If it returns "none", the policy is intentionally blocking artifacts. Update it:

curl -X PATCH "http://localhost:8080/api/v1/federation/trust-policies/{policy_id}" \
  -H "Content-Type: application/json" \
  -d '{"trust_level": "verified"}'

Invalid Organization Slug¶

Symptom: Trust policy creation fails with 422 Validation Error.

Check: Slug must match ^[a-z0-9]([a-z0-9-]{1,61}[a-z0-9])?$ and not be reserved.

Reserved slugs: local, user, marketplace, system, admin, root, skillmeat

Fix: Use a different slug, e.g., acme-corp-labs instead of ACME-Corp-Labs.

Next Steps¶

Advanced Trust Policies: See the Trust Policy Administration Guide for regex-based artifact filtering and advanced scenarios.
PKI Architecture: See ADR-018 for the design decisions and security properties of the PKI model.
Bring-Your-Own-CA: For organizations with existing PKI, contact enterprise support to arrange cross-signing.

Support¶

For deployment issues or questions, contact: - Enterprise Support: support@skillmeat.io - Documentation: https://docs.skillmeat.io/federation - Community Forum: https://community.skillmeat.io/federation