Peer-to-peer handshake endpoint

POST

/federation/peers/handshake

• Local development behind nginx (port 8088 by default)

Public unauthenticated endpoint — accepts signed handshake envelopes from peer instances per docs/spec/federation/v1.md §11. The envelope is signed by the offered Ed25519 public key (payload-signature only — transport HTTP-Sig is for established peers).

Request Body ^required

object

envelope

required

Inner payload of a handshake envelope per v1.md §11. Signed using RFC-8785-canonical JSON.

object

protocol

required

Always aa-handshake/v1

string

type

required

string

Allowed values: offer confirm

from

required

string

from_display_name

required

string

from_public_key_pem

required

string

to

required

string

nonce

required

string

timestamp

required

string format: date-time

signature

required

Base64-std Ed25519 signature over the canonical envelope.

string

Responses

200

Envelope accepted; result indicates resulting state.

object

status

required

accepted_pending: we created a pending_inbound row; admin must accept. completed: handshake finished (either confirm landed, or cross-handshake auto-merged). ignored_duplicate: we already had this row in a terminal state.

string

Allowed values: accepted_pending completed ignored_duplicate

peer_id

required

string format: uuid

400

Malformed or unverifiable envelope.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

503

Instance identity not yet generated.

object

error

required

Human-readable error summary

string

Example

the request could not be completed