📐 Spec

Spec-04-Manifests

3 min readSpec contributor · Node operatorDraft · v0.9.0aN

What this spec defines

Organization and node manifests: the signed statement of entity authority, public signing keys, key identifiers, rotation events, validity bounds, and transparency-log evidence used by federation trust.

Extraction status

This file contains the ADR-010 prose extraction for manifest publication and verification. It intentionally does not define peer admission policy, replication authorization, or capability-token grants; those belong in Spec-05-Federation-Trust and Spec-06-Capability-Tokens.

Manifest purpose

A manifest is a signed statement of entity authority.

It lets a peer verify that a node or organization is authoritative for the entity URIs it claims and exposes the public key material needed to verify signatures issued by that authority. Manifests replace ad hoc key exchange — peers resolve a manifest during the federation handshake and use it to verify the sender's signatures and declared entity list.

Manifest shape

Manifest {
  manifest_version: integer
  entity_uri:       URI
  public_key:       base64url Ed25519 public key
  key_id:           string
  entities:         URI[]
  rotation_events:  RotationEvent[]
  issued_at:        ISO 8601 UTC
  expires_at:       ISO 8601 UTC
  signature:        base64url Ed25519 signature
}

RotationEvent {
  old_key_id: string
  new_key_id: string
  public_key: base64url Ed25519 public key
  rotated_at: ISO 8601 UTC
  signature:  base64url Ed25519 signature
}

Field

Role

Meaning

entity_uri

root authority

Root entity URI for the node or organization.

entities

explicit list

The specific entity URIs this manifest is authoritative for. Implementations MUST NOT treat an omitted entity as covered by implication unless another accepted spec explicitly defines a delegation rule.

key_id

fingerprint

SHOULD be a stable fingerprint of the active public key. Used for lookup, revocation, and audit evidence; not a substitute for signature verification.

rotation_events

key history

Lets peers verify changes in signing keys over time.

Canonical encoding

The manifest signature is computed over a canonical JSON representation of the manifest with the signature field omitted. Implementations MUST use a stable field order and byte representation so that peers can verify signatures independently.

Publication and resolution

Operation

Route

Authorization

Publish

PUT /v1/federation/manifest

The node MUST verify the uploaded manifest signature before persisting it. Publication by non-admin callers MUST be rejected.

Resolve

GET /v1/federation/manifest/{entity_uri_encoded}

Returns the full manifest object when the node has a valid manifest covering the requested entity. Missing manifests return 404 Not Found.

Route shape is owned by Spec-03-HTTP-API.

Transparency-log evidence

When a transparency-log backend is configured, the node SHOULD publish manifest events to the log and retain inclusion evidence. Transparency-log evidence lets peers audit manifest history independently of the runtime node.

This spec depends on transparency-log evidence for auditability, but does not require a specific production log service. The trust decision for which log to use belongs to deployment policy and federation-trust configuration.

Key rotation

A rotation event MUST bind the old key id, new key id, new public key, rotation time, and signature.

Peers MUST verify the rotation chain before accepting a new active key for an existing authority. Key rotation and peer trust windows are interpreted by Spec-05-Federation-Trust.

Expiry

Peers MUST reject expired manifests. Nodes SHOULD refresh manifests before expires_at to avoid federation interruptions. A manifest with an expiry far in the future can weaken rotation discipline, so deployments SHOULD choose bounded validity windows appropriate to their operator model.

Out of scope

This spec does not define:

Peer admission decisions

After manifest verification.

Capability-token shape

Signing or revocation.

Replication scope authorization

Production Sigstore/Rekor

Deployment requirements.