Federation Trust Policy Administration

This guide covers managing trust policies between federated organizations, monitoring sync health, and GDPR deletion workflows. All federation endpoints require Enterprise Edition with the dvcs_federation_enabled feature flag.

Prerequisites

• SkillMeat Enterprise Edition
• Feature flag: dvcs_federation_enabled=true
• Bearer token authentication (Authorization: Bearer <token>)
• DNS-compatible organization slug (peer org identifier)
• SHA-256 certificate fingerprint of peer organization (64 hex characters)

See Federation Setup Guide for initial configuration.

Trust Level Reference

Trust levels define how your organization treats inbound artifacts from a peer. Each policy applies to a single peer organization.

Level	Behavior	Sync	Signature Check	Use Case
none	Blocked — no sync occurs	No	Skipped	Revoke an existing relationship
verified	Certificate verified, allowed types only	Yes	Required	Conservative trust; verify peer credentials
full	Full mutual trust, all types synced	Yes	Optional	Trusted partners; subject to allowed_artifact_types filter

Note: Setting trust_level to none writes an immutable audit log entry with the previous trust level and who revoked it.

Creating a Trust Policy

Create a policy to establish trust with a peer organization. Use the /federation/trust-policies endpoint.

Minimal Example (verified trust, all artifact types):

curl -X POST http://localhost:8080/api/v1/federation/trust-policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trusted_org_slug": "acme-corp",
    "trust_level": "verified",
    "allowed_artifact_types": null,
    "signature_requirement": "required",
    "sync_interval_seconds": 3600,
    "trusted_cert_fingerprint": "a1b2c3d4e5f6...a1b2c3d4 (64 hex chars)",
    "expires_at": null,
    "allowed_regions": null
  }'

Response (201 Created):

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "org_id": "your-org",
  "trusted_org_slug": "acme-corp",
  "trust_level": "verified",
  "allowed_artifact_types": null,
  "signature_requirement": "required",
  "sync_interval_seconds": 3600,
  "trusted_cert_fingerprint": "a1b2c3d4e5f6...a1b2c3d4",
  "expires_at": null,
  "allowed_regions": null,
  "created_at": "2026-04-13T10:00:00Z",
  "updated_at": "2026-04-13T10:00:00Z"
}

Common Scenarios:

• Restricted types (skills only): Set allowed_artifact_types: ["skill"]
• Regional lock (US only): Set allowed_regions: ["us-east-1", "us-west-2"]
• No auto-sync (manual only): Set sync_interval_seconds: 0
• Expiring policy (60-day trial): Set expires_at to a date 60 days from now

Error: Policy Already Exists

409 Conflict — a policy for this (org, peer) pair already exists. Update it instead or delete and recreate.

Updating Trust Levels

Partially update a policy to change trust level, sync settings, or allowed types.

Example: Escalate from verified to full trust

curl -X PATCH http://localhost:8080/api/v1/federation/trust-policies/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_level": "full",
    "signature_requirement": "optional"
  }'

What changes when you update trust_level:

• none → verified/full: Sync resumes according to policy schedule
• verified/full → none: Sync stops immediately; audit log entry written with revocation reason; existing artifacts retained

Sync behavior after update:

Updates take effect on the next sync cycle (every sync_interval_seconds). To apply changes immediately, trigger a manual sync via POST /federation/sync.

Revoking a Federation Relationship

Set trust_level to none to revoke trust while keeping the policy record for audit purposes.

Example: Revoke an untrustworthy peer

curl -X PATCH http://localhost:8080/api/v1/federation/trust-policies/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trust_level": "none"
  }'

What happens:

• Sync stops immediately
• No new artifacts pulled
• Existing artifacts remain in your collection
• Immutable audit log entry: trust_policy.revoked with previous trust level and admin identity
• Policy record remains (can be queried for compliance)

Revoke vs. Delete:

Operation	Effect	Use Case
Set trust_level to none	Stops sync; keeps audit trail; policy remains queryable	Standard revocation; compliance requirement
DELETE policy	Removes policy completely; audit entries remain	Cleanup; complete relationship termination

Monitoring Federation Health

Use the sync status endpoint to monitor policy execution and certificate health.

Check sync status:

curl -X GET http://localhost:8080/api/v1/federation/sync/status \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "total_policies": 5,
  "active_policies": 4,
  "sync_results": [
    {
      "policy_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "trusted_org_slug": "acme-corp",
      "last_sync_at": "2026-04-13T10:15:30Z",
      "next_sync_at": "2026-04-13T11:15:30Z",
      "status": "success",
      "artifacts_synced": 12,
      "errors": null
    }
  ],
  "cert_expiry_warnings": [
    {
      "trusted_org_slug": "acme-corp",
      "days_until_expiry": 25,
      "expires_at": "2026-05-08T00:00:00Z"
    }
  ]
}

Key metrics:

• last_sync_at: When the last poll occurred
• next_sync_at: When the next automatic sync is scheduled
• status: success, partial, or failed
• artifacts_synced: Count of artifacts pulled in the last cycle
• cert_expiry_warnings: Certificates expiring in < 30 days

Audit Logging

The federation audit log records all policy changes and sync events for compliance.

Audit events:

• trust_policy.created — Policy created; includes trust_level, allowed types
• trust_policy.updated — Policy fields changed
• trust_policy.revoked — Trust_level changed to none; includes previous level and revoker identity
• artifact.synced — Artifact pulled from peer; includes FQAN and sync cycle ID
• sync_cycle.completed — Sync cycle finished; includes artifact count and errors

Query the audit log via the GraphQL API or export for SIEM integration.

GDPR Deletion Workflow

When a peer organization requests deletion of their artifacts (GDPR right to erasure), follow this workflow.

Phase 1: Publisher initiates deletion

The peer organization sends a signed GDPR deletion request to your /federation/delete-artifacts endpoint. This includes: - List of artifact FQANs (fully qualified artifact names) to delete - Signature proving the request is from the claimed organization - Trace ID for cross-org audit linkage

Phase 2: Subscriber receives and logs

Your system receives the deletion request and: 1. Validates the cryptographic signature against the peer's certificate 2. Writes a gdpr_deletion_initiated audit event 3. Deletes the specified artifacts from your collection 4. Queues a confirmation response

Phase 3: Confirm deletion

Send a signed confirmation back to the peer, proving deletion occurred:

curl -X POST https://peer-org.com/federation/delete-artifacts/confirm \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "5f3b8c2a-1d4e-4f6a-9b8c-2d5e6f7a8b9c",
    "artifacts_deleted": ["acme-corp/skill/frontend-design", "acme-corp/command/bulk-upload"],
    "deleted_at": "2026-04-13T10:30:00Z",
    "confirmed_by": "admin@your-org.com"
  }'

Audit trail (both sides):

• Publisher: gdpr_deletion_requested → gdpr_deletion_confirmed
• Subscriber: gdpr_deletion_received → gdpr_deletion_completed

All events are immutable and timestamped. Deletion cannot be undone.

API Operations Reference

Operation	Endpoint	Method	Notes
Create policy	/federation/trust-policies	POST	Returns 409 if policy exists
List policies	/federation/trust-policies	GET	Cursor pagination; default limit 50
Get policy	/federation/trust-policies/{id}	GET	Returns 404 if not found or belongs to different org
Update policy	/federation/trust-policies/{id}	PATCH	Only supplied fields are modified
Delete policy	/federation/trust-policies/{id}	DELETE	Returns 204; soft-deletes are not used
Trigger sync	/federation/sync	POST	Blocks up to 30 seconds; returns partial results on timeout
Sync status	/federation/sync/status	GET	Shows health, certificate warnings, next sync times

Validation Rules

• Org slug: Must match ^[a-z0-9]([a-z0-9-]{1,61}[a-z0-9])?$
• Consecutive hyphens: Not allowed in slug (-- rejected)
• Reserved slugs: local, user, marketplace, system, admin, root, skillmeat cannot be trusted
• Cert fingerprint: Exactly 64 hex characters, lowercase
• Sync interval: 0–86400 seconds (0 = disabled, default 3600)
• Expiry: Optional; if set, must be a future ISO 8601 datetime

Errors return 422 Unprocessable Entity with detail messages.

Troubleshooting

Q: Sync status shows "failed" — what went wrong?

A: Check the audit log for the sync cycle. Common causes: - Peer certificate changed (signature mismatch) - Peer certificate expired - Network timeout (peer unreachable) - Peer revoked your org's certificate

Contact the peer organization to verify their certificate has not changed.

Q: How do I disable sync without deleting the policy?

A: Set sync_interval_seconds to 0. The policy remains active but polling stops. Update to a positive value to re-enable.

Q: Can I restrict which artifact types are synced?

A: Yes. Set allowed_artifact_types to an array like ["skill", "command"]. null means all types are allowed. Update via PATCH to change filtering.

Q: What if a policy expires?

A: Sync automatically stops. Artifacts remain in your collection. Update expires_at to extend or set to null to remove expiry.

---

For more on federation architecture, see Federation Overview.