sonda/internal/federation/federation.go
tgiachi 89826fcd07 feat(federation): shared libraries and the signed read API for friends
A friend's server can now read what an admin chose to share.

- A library has a shared flag, off by default (migration 0024), set with
  PATCH /libraries/{id}. Changing it never waits for a scan.
- Requests between friends are signed with each server's Ed25519 key: the
  method, the path and query from /api/v1/peer on, a date, a nonce and the
  hash of the empty body. A date more than two minutes off, a nonce used
  before, an unknown or removed key and a bad signature all get the same
  401. A friend still waiting for approval gets 403, and while federation is
  off the routes are missing.
- Routes under /api/v1/peer: info, artists, albums, tracks, covers and
  streaming with Range. The catalogue, the counts and the format come from
  the shared libraries only, and the file served is the one in a shared
  library. No path, library id, listen, taste, user or provider data is part
  of an answer.
- A friend never makes this server build a cover, read an audio file or ask
  a provider: only covers already built from the audio files are served.
- Per-friend limits, set by the admin: parallel streams (default 3) and KiB
  a second (default 4096, 0 for none), shared by all the streams of a friend.
- A log of the last requests friends made (route, status, bytes; never the
  query), kept for 7 days, in GET /federation/requests.
- POST /federation/friends/{id}/check lets the side that pasted an invite
  find out that the other admin approved; a signed call from a friend this
  server is waiting for makes it active too.
- Admin: a Shared with friends switch on each library, which asks first, and
  limits, recent requests and a Check button in the Federation section, in
  English and Italian.
- OpenAPI paths and schemas, contract test, two real servers checked end to
  end with tagged audio files.
2026-11-13 15:04:07 +01:00

122 lines
5.1 KiB
Go

// Package federation lets two Sonda servers become friends: each one's listeners can play the libraries the
// other's admin chose to share, read only. Nothing leaves a server unless its admin decides it, so federation is off
// until an admin turns it on, and a friend is made only by an invite and two confirmations.
//
// This file holds the types and the contract of the store. The rules are in service.go, the call to the other
// server in client.go.
package federation
import (
"context"
"crypto/ed25519"
"crypto/sha256"
"encoding/hex"
"errors"
"time"
)
// Errors returned by the service. Handlers map them to HTTP statuses.
var (
ErrOff = errors.New("federation is off")
ErrNoAddress = errors.New("this server has no public address yet")
ErrInvalidInput = errors.New("invalid federation input")
ErrInvalidInvite = errors.New("the invite is not valid")
ErrAlreadyFriend = errors.New("this server is already a friend")
ErrFriendMissing = errors.New("no such friend")
ErrWrongState = errors.New("the friend is not waiting for approval")
ErrTooMany = errors.New("too many pairing attempts: try again in a minute")
ErrUnreachable = errors.New("the other server could not be reached")
ErrRefused = errors.New("the other server refused the invite: it may be used, expired or federation off there")
ErrKeyMismatch = errors.New("the other server's key is not the one in the invite")
// ErrUnauthorized is every way a request from a friend can fail to be signed properly: no signature, a bad one,
// an old date, a nonce seen before, an unknown key. It says no more, so a stranger learns nothing.
ErrUnauthorized = errors.New("the request is not signed by a friend")
// ErrNotApproved: the signature is good but the friendship is waiting for an admin's approval.
ErrNotApproved = errors.New("the friendship is not approved yet")
// ErrNotFriend: the other server does not take this server for a friend (it removed it, or federation is off there).
ErrNotFriend = errors.New("the other server does not take this server for a friend")
ErrTooManyStreams = errors.New("this friend already has as many streams open as allowed")
)
// Defaults of the limits a friend is held to, and what they may be set to.
const (
DefaultMaxStreams = 3
DefaultMaxKiBPerSec = 4096
)
// State of a friend.
type State string
// The states a friend goes through.
const (
// Incoming: they used an invite of mine and wait for my approval.
Incoming State = "incoming"
// Outgoing: I used an invite of theirs and wait for their approval.
Outgoing State = "outgoing"
// Active: both sides agreed.
Active State = "active"
)
// Settings of this server's federation. The private key never leaves the service: the API shows the key id only.
type Settings struct {
Enabled bool
Name string // shown to friends; empty means the host name
Address string // where friends reach this server, normalised
PublicKey ed25519.PublicKey
PrivateKey ed25519.PrivateKey
UpdatedAt time.Time
MaxStreams int // parallel streams one friend may have
MaxKiBPerSec int // bytes a friend may take, in KiB a second, over all its streams; 0 means no limit
}
// FriendRequest is one request a friend made to this server, as it is logged.
type FriendRequest struct {
At time.Time
FriendID int64
FriendName string // filled in when listed
Route string // the route pattern, never the query
Status int
Bytes int64
}
// Friend is another Sonda server.
type Friend struct {
ID int64
Name string
Address string
PublicKey ed25519.PublicKey
State State
CreatedAt time.Time
ApprovedAt time.Time // zero until active
}
// KeyID is the short name of a key: the first 16 hex characters of its SHA-256.
func KeyID(pub ed25519.PublicKey) string {
sum := sha256.Sum256(pub)
return hex.EncodeToString(sum[:])[:16]
}
// Store persists federation state.
type Store interface {
// Settings returns found=false until they were first saved.
Settings(ctx context.Context) (s Settings, found bool, err error)
SaveSettings(ctx context.Context, s Settings) error
AddInvite(ctx context.Context, codeHash string, created, expires time.Time) error
// UseInvite marks an unused, unexpired invite as used and says whether there was one.
UseInvite(ctx context.Context, codeHash string, now time.Time) (bool, error)
Friends(ctx context.Context) ([]Friend, error)
Friend(ctx context.Context, id int64) (Friend, error) // ErrFriendMissing
FriendByKey(ctx context.Context, key ed25519.PublicKey) (Friend, bool, error)
AddFriend(ctx context.Context, f Friend) (Friend, error) // ErrAlreadyFriend when the key is known
Approve(ctx context.Context, id int64, now time.Time) error // incoming to active; ErrFriendMissing, ErrWrongState
Activate(ctx context.Context, id int64, now time.Time) error // outgoing to active; ErrFriendMissing, ErrWrongState
DeleteFriend(ctx context.Context, id int64) error // ErrFriendMissing
LogRequest(ctx context.Context, r FriendRequest) error
Requests(ctx context.Context, limit int) ([]FriendRequest, error) // newest first, with the friend's name
PruneRequests(ctx context.Context, before time.Time) error
}