Trip2g Federation Protocol — Adapter Implementation Guide

2.1 Channels accepted by the adapter

The peer MUST inspect Authorization: Bearer <value> and ?token=<value> query parameter. Hub uses the header.

2.2 Federation HMAC JWT (verbatim spec)

Federation tokens are HMAC-SHA256 JWTs. The peer treats any non-empty Bearer/?token= value as a JWT and validates it per the rules below. Anything that fails validation → anonymous Auth.

Header:

{"alg":"HS256","typ":"JWT","kid":"<kid>"}

Payload:

{
  "iss": "<hub-url>",
  "aud": "<peer-url>",
  "rid": "<request-uuid>",
  "iat": <unix-seconds>,
  "exp": <unix-seconds>
}

Signature: HMAC-SHA256(<base64url(header)>.<base64url(payload)>, secret_bytes), base64url-encoded without padding.

Validation rules on the peer:

1. Three segments, each base64url-decodable.
2. Header alg == "HS256" and typ == "JWT". Reject otherwise.
3. Header kid is non-empty; look it up in the peer's federation_secrets store. If not found or revoked → anonymous Auth (NOT error).
4. signature == HMAC-SHA256(header.payload, secret_bytes). Constant-time compare. Mismatch → anonymous.
5. iat and exp are present. Allow ±10s clock skew. Outside the window → anonymous.
6. aud (when present and non-empty) MUST equal the peer's own base URL. Mismatch → anonymous.
7. (Optional, recommended) rid MUST NOT have been seen before within exp. Track in-memory sync.Map[rid → exp] with periodic eviction. Replay → anonymous.

Failure mode = anonymous, NOT error. Returning HTTP 401 or JSON-RPC error for an unrecognized kid leaks existence. Always return a successful JSON-RPC envelope with empty results.

2.3 Authorization context

After verification the peer constructs an internal Auth object:

type Auth struct {
    KID       string            // for logging
    AccountID string            // peer-local scope owner
    Allowed   map[string]bool   // scoped resource ids (e.g. dialog ids)
    AllowAll  bool              // when scope is "*"
}

Map federation kid → adapter-local scope: which resources this caller may see. Trip2g hub does not control scope; the peer admin defines it at federation_secret creation time.

2.4 Issuing federation_secrets (peer admin UI)

Peer MUST expose admin endpoints to:

• create a secret: 32 random bytes, hex-encoded, returned once to the admin (mirrors trip2g UI).
• list secrets per scope: kid, scope, created_at, last_used_at, revoked_at.
• revoke (soft delete): revoked_at = now().

Storage: encrypt secretHex at rest with the peer's master key. Verification needs raw bytes, so do NOT hash.

The two-step exchange (peer admin generates → sends kid + secretHex to hub admin → hub admin pastes into trip2g admin → hub stores encrypted in its own federation_secrets) is described in trip2g's user federation docs.

---

3.1 Request

{
  "jsonrpc": "2.0",
  "method": "<method-name>",
  "params": {...},
  "id": "<unique-string-or-int>"
}

Hub uses string IDs (UnixNano timestamp). Peer SHOULD echo id verbatim in the response.

3.2 Response (success)

{
  "jsonrpc": "2.0",
  "id": "<echoed>",
  "result": {...}
}

3.3 Response (error)

{
  "jsonrpc": "2.0",
  "id": "<echoed>",
  "error": {"code": <int>, "message": "<text>"}
}

Use JSON-RPC error ONLY for protocol/transport problems (parse error, malformed envelope, method-not-found, transport timeout). Codes:

• -32700 parse error
• -32600 invalid request
• -32601 method not found
• -32602 invalid params
• -32603 internal error (transport, infra)

Tool execution failures are NOT JSON-RPC errors. They go inside result with isError: true (see §5).

---

4.1 initialize

Request params: capabilities object (ignored by peer in v1).

Response result:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {"tools": {}},
  "serverInfo": {"name": "<peer-name>", "version": "<semver>"}
}

4.2 tools/list

Request params: empty.

Response result:

{
  "tools": [
    {
      "name": "search",
      "description": "<human-readable, includes input format examples>",
      "inputSchema": {"type": "object", "properties": {...}, "required": [...]}
    },
    {"name": "note_html", ...},
    {"name": "similar", ...}
  ]
}

A peer MAY expose only search and note_html if similar is meaningless for it. Trip2g hub will gracefully degrade — federated_similar calls are not used by the agent unless it explicitly asks for similar.

4.3 tools/call

Request params:

{"name": "<tool-name>", "arguments": {...}}

Response result: MUST be a CallToolResult (see §5).

4.4 notifications/initialized

Client → server only. Peer MAY respond with empty result: {} or treat as a notification (no response required by JSON-RPC, but trip2g hub accepts an echo).

---

{
  "content": [{"type": "text", "text": "<short summary, <=500 chars>"}],
  "structuredContent": <any JSON value, optional>,
  "isError": <bool, optional, default false>
}

type FederationResult struct {
    Content           []FederationContent `json:"content"`
    StructuredContent json.RawMessage     `json:"structuredContent,omitempty"`
    IsError           bool                `json:"isError,omitempty"`
}
type FederationContent struct {
    Type string `json:"type"` // always "text"
    Text string `json:"text"`
}

5.1 content (REQUIRED, even if empty)

Array of human/agent-readable text items. Always at least one item when results exist. For empty result sets, return one item with a summary like "Found 0 results for query \"X\"" — this lets clients without structuredContent handling still display something.

type is always "text" in v1. Image/audio types reserved for future use.

5.2 structuredContent (OPTIONAL but strongly recommended)

Tool-specific JSON. Hub forwards this to the agent. Agents that understand the structure parse it; legacy clients fall back to content[0].text.

Conventions per tool (see §6).

5.3 isError (OPTIONAL, default false)

Set true when the tool failed in a way the agent should know about (no results due to scope, embedding service down, malformed query, rate limited). The HTTP status is still 200 and result is still populated; the error is inside the tool result.

When isError: true:

• content[0].text MUST contain a human-readable error message.
• structuredContent MAY contain machine-readable error fields ({error_code, retry_after}).
• Hub will surface this to the agent; the federated_search fan-out will not include error results in merged output.

Do NOT use isError for auth failures — those return empty results (anonymous), per §2.

---

6.1 search

Arguments:

{"query": "<plain text or JSON DSL string>"}

The peer is free to define a DSL inside query (telegram adapter accepts JSON DSL with op, dialog_kinds, after, etc.). Hub treats query opaquely.

structuredContent:

{
  "query": "<echo>",
  "results": [
    {
      "note_id": <uint64>,         // peer-stable id, opaque to hub
      "note_path": "<peer-route>",
      "title": "<display title>",
      "score": <float>,            // 0..1, present for semantic search
      "url": "<https URL>",
      "href": "<deep link, optional>",
      "kind": "<peer-defined>",
      "matches": [
        {"match_id": "<id>", "snippet": "<...>", "context_words": <int>}
      ],
      "proof": {<peer-defined provenance>}
    }
  ]
}

content[0].text: "Found N results for \"<query>\"" plus optionally a one-line digest of the top match.

6.2 note_html

Arguments: at least one of pid, note_id, path, href, plus optional match_id, context_words.

structuredContent:

{
  "html": "<sanitized full HTML, optional>",
  "payload": {<peer-defined raw fields>},
  "queued": <bool, optional>
}

content[0].text: "Loaded note <id-or-path>" or a brief plain-text excerpt (≤500 chars).

6.3 similar

Arguments: at least one of pid, note_id, path, href. Optional limit.

structuredContent: same shape as search.results.

content[0].text: "Found N similar notes to <id>".

6.4 federated_* (recursive federation)

Peers MAY chain to their own peers. If a peer chooses NOT to (telegram adapter does not), it MUST still respond with a valid CallToolResult:

{"content": [{"type":"text","text":"This peer does not federate further."}],
 "structuredContent": {"results": []}}

Do NOT return JSON-RPC error: -32601 method not found — hub treats peers as opaque; the method exists in the schema, the peer just chose not to walk further. Empty CallToolResult is correct.

---