COG-15: Cross-Venue Federation

Status:      Draft
Version:     0.1
Created:     2026-07-10
Authors:     Mike Anderson

Related specifications

This document specifies how requests, authority, and caller identity cross venue boundaries on the Covia Grid. It builds on the authentication catalogue of COG-3: Authentication Mechanisms (in particular the UCAN identity token, COG-3 §6) and the capability model of COG-13: Agent Capabilities (UCAN delegation, root authority, the venue/relay ability). It introduces no new trust primitive — federation composes the existing ones.

Purpose

A grid operation may target a remote venue: venue A (the relay) receives a request from a caller and forwards it to venue B (the target). Without care, such hops either drop the caller's authority (everything is anonymous) or — worse — assert it unverifiably (the relay claims "the caller is Alice" and the target has to take its word). This document specifies how authority and identity cross the hop verifiably: the target trusts signatures, never the relay.

Principles

• Authority travels only in the proof channel. UCAN tokens are carried in the request's ucans array — never in operation input, which is data (persisted in job records; a credential there would leak into durable history). Body-less observation requests (e.g. job status reads) carry the same tokens in the X-Covia-Ucans header, explicitly attached by the sender from its own proof state and verified identically at ingress — nothing ever relies on passive header propagation across hops.
• Tokens are self-describing. There are no mode flags or auth fields. What a token is — a grant, an identity proof, a relay instruction — follows from its issuer, audience, and attenuations. The verifier decides everything from the token itself.
• Zero trust in the relay. The target venue verifies every forwarded token against its own trust policy (signature at every chain hop, temporal bounds, attenuation, root authority — COG-13). A relay can neither forge authority nor widen it; the worst a malicious relay can do is drop tokens (deny service).
• Anonymous is the explicit default. A hop carrying no identity token and no relay delegation is anonymous — correct for public operations, fail-closed for everything else.

The Proof Channel

Requests carry UCAN tokens (JWT-encoded) in the ucans array of the invoke envelope:

{
  "operation": "v/ops/covia/read",
  "input": { "path": "did:key:zAlice.../w/shared/doc" },
  "ucans": [ "<jwt>", "<jwt>" ]
}

The receiving venue verifies each token's signature at ingress; unverifiable tokens are discarded. Delegation chains travel nested: a token's prf field carries its parent tokens as JWT strings, recursively verified — a single leaf JWT is a complete, self-contained chain.

Requests without a body — observing a job's status or result — carry the same JWTs, comma-separated, in the X-Covia-Ucans header. This is what lets a federated hop observe the remote job it created: the relayed identity token authenticates the requester at the target on the read, exactly as it did on the invoke. Verification is identical; only the carrier differs.

Caller Identity Across Venues

The caller's identity crosses a hop as an identity token (COG-3 §6): a UCAN the caller signs with their own key, audienced to the target venue, with an empty attenuation list.

• The empty att makes it pure identity — it grants nothing and cannot be dual-used.
• The audience binding makes it unusable at any venue other than the target.
• The target accepts it as the caller identity only on an unauthenticated transport; an Authorization header always wins.

The caller is then the principal at the target: jobs are owned by them, and forwarded grants audienced to them apply. The relay's only role was carrying the token.

Venue as Delegate: venue/relay

A caller MAY instead have the relay make the hop as itself, exercising authority the caller delegated to it. The instruction is a token:

Field	Value
iss	The caller (MUST be the relay's authenticated caller)
aud	The relay venue's DID
att	A capability with can: venue/relay (conventionally with: <callerDID>), plus the substantive grants the relay may exercise

The token is simultaneously the instruction and the authorisation — the relay honours it only when its issuer is the authenticated caller. This rule makes the confused deputy impossible by construction: a relay delegation minted by anyone else is not an instruction from this caller, so a third party presenting a stolen copy gets nothing.

At the target, the relay is the transport-authenticated caller and the forwarded chain (leaf audienced to the relay) is walked to its root — which must still satisfy the target's root-authority policy (COG-13): the resource owner, or an authority the target accepts.

Relay Obligations

A venue forwarding a request MUST:

1. Forward the caller's presented tokens in the hop's ucans array — filtered to those that could be admissible at the target. Tokens that are provably inert MUST be dropped: expired or unparseable tokens, and tokens audienced to an identity that is not the hop's principal (e.g. the caller's own grants when the relay hops as itself). Forwarding an inert token discloses the caller's unrelated grants for no benefit.
2. Never forward the inbound transport bearer. It is audienced to the relay and must not be replayable elsewhere.
3. Not assert identity. The relay never adds an unverifiable "caller is X" claim; identity crosses only as a caller-signed identity token, or the hop is anonymous.

Deeper filtering than rule 1 is deliberately not required: the relay cannot generally know which resources an operation on the target will touch, nor the target's DID before contact. Disclosure control therefore rests with the caller — present the tokens relevant to each request, not a wallet.

Verification at the Target

The target venue applies its standard verification to every forwarded token (COG-13): signature at every hop, temporal bounds, audience match against the acting principal, per-hop attenuation, and root authority — the chain root must be signed by the resource owner (self-sovereign) or by an authority the target accepts (its own grants; custodial attestation below). Nothing about a forwarded token is trusted because a venue relayed it.

Custodial Callers (Planned)

Work in Progress

This section describes planned behaviour for callers who hold no signing key (e.g. OAuth-authenticated users). It is not yet implemented.

A keyless caller cannot sign an identity token or delegation. Their controlling venue attests instead: it signs a statement that its user (<venueDID>:u:<user>) authenticated to it and that it forwards a grant on their behalf, audienced to the target. The target accepts the attestation only if its trust policy accepts the attesting venue (allowlist, organisational root, or DID-discovery based). Until then, custodial callers cross venues anonymously.

Security Considerations

• Replay: identity tokens are audience-bound and SHOULD be short-lived (minutes). A relay holding one cannot use it at any other venue.
• Confused deputy: the venue/relay issuer-is-the-caller rule is load-bearing; implementations MUST NOT honour relay delegations from any other issuer.
• Privacy: the admissibility filter (Relay Obligations, rule 1) bounds what a target learns about the caller's other relationships; per-request presentation bounds it further.
• Denial: a malicious relay can drop tokens or refuse to forward; it cannot escalate. Callers who cannot tolerate this should contact the target venue directly.