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.
This commit is contained in:
tgiachi 2026-11-13 15:04:07 +01:00
commit 89826fcd07

View file

@ -3162,6 +3162,346 @@ paths:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/friends/{id}/check:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
tags: [Federation]
operationId: checkFederationFriend
summary: Ask a friend whether it approved
description: |
Admin only. Sends the friend one signed request (`GET /peer/info`). An answer means it approved, and a friend that
was `outgoing` becomes `active`. The friend is returned. A friend in state `incoming` is a `409` (`not_waiting`):
it waits for this server's admin, not the other way round.
security: [{bearerAuth: []}]
responses:
'200':
description: The friend, active when it answered.
content:
application/json:
schema: {$ref: '#/components/schemas/FederationFriend'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
'404':
description: No such friend (`friend_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'409':
description: |
Federation is off (`federation_off`), the friend is not waiting for the other admin (`not_waiting`), the other
admin has not approved yet (`not_approved`), or the other server does not take this one for a friend any more
(`friend_gone`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'502':
description: The other server could not be reached or did not answer as a Sonda server (`friend_unreachable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/federation/requests:
get:
tags: [Federation]
operationId: listFederationRequests
summary: The last requests friends made
description: |
Admin only. The last 50 requests that friends made to this server, newest first, kept for 7 days: when, which
friend, which route (the pattern, never the query, so what was searched for is not kept), the status and how many
bytes were sent.
security: [{bearerAuth: []}]
responses:
'200':
description: The requests.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [requests]
properties:
requests:
type: array
items: {$ref: '#/components/schemas/FederationRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/AdminRequired'}
/peer/info:
get:
tags: [Federation]
operationId: peerInfo
summary: Who this server is (called by a friend)
description: |
Not for people: a friend's server calls this, signed (see the `friendSignature` scheme), and also to find out whether
this server's admin approved it. Says the name of this server and how many libraries are shared.
security: [{friendSignature: []}]
responses:
'200':
description: The name and the number of shared libraries.
content:
application/json:
schema: {$ref: '#/components/schemas/PeerInfo'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/artists:
get:
tags: [Federation]
operationId: peerListArtists
summary: The artists of the shared libraries (called by a friend)
description: |
Like `GET /artists`, over the libraries that are shared and nothing else: an artist is listed only when it has a
playable track in one of them, and the counts are of those tracks. Paths, library ids and everything that providers
said are never part of it. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
responses:
'200':
description: A page of artists.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/artists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetArtist
summary: One artist of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The artist.
content:
application/json:
schema: {$ref: '#/components/schemas/Artist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such artist among the shared libraries (`artist_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/albums:
get:
tags: [Federation]
operationId: peerListAlbums
summary: The albums of the shared libraries (called by a friend)
description: Like `GET /albums`, over the libraries that are shared. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
responses:
'200':
description: A page of albums.
content:
application/json:
schema: {$ref: '#/components/schemas/AlbumPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/albums/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetAlbum
summary: One album of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The album.
content:
application/json:
schema: {$ref: '#/components/schemas/Album'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such album among the shared libraries (`album_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/albums/{id}/cover:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetAlbumCover
summary: The cover of an album of the shared libraries (called by a friend)
description: |
Only a cover that this server already built from the audio files of the album: a friend never makes this server
build one, read an audio file or ask a provider. A cover that came from the Cover Art Archive is not given. Any other
album answers `cover_not_found`. The bytes go out within the friend's allowance.
security: [{friendSignature: []}]
parameters:
- name: size
in: query
description: "`small` or `large`. Large when absent."
schema: {type: string, enum: [small, large], default: large}
- name: If-None-Match
in: header
required: false
schema: {type: string}
responses:
'200':
description: The cover.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
content:
image/jpeg:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-None-Match`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such album among the shared libraries (`album_not_found`), no cover built (`cover_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/tracks:
get:
tags: [Federation]
operationId: peerListTracks
summary: The tracks of the shared libraries (called by a friend)
description: Like `GET /tracks`, over the libraries that are shared. Signed like every `/peer` route.
security: [{friendSignature: []}]
parameters:
- {$ref: '#/components/parameters/Q'}
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- {$ref: '#/components/parameters/ArtistId'}
- {$ref: '#/components/parameters/AlbumId'}
responses:
'200':
description: A page of tracks.
content:
application/json:
schema: {$ref: '#/components/schemas/TrackPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404': {$ref: '#/components/responses/FederationOff'}
/peer/tracks/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerGetTrack
summary: One track of the shared libraries (called by a friend)
security: [{friendSignature: []}]
responses:
'200':
description: The track.
content:
application/json:
schema: {$ref: '#/components/schemas/Track'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such track among the shared libraries (`track_not_found`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/peer/tracks/{id}/stream:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Federation]
operationId: peerStreamTrack
summary: Stream a track of the shared libraries (called by a friend)
description: |
The file of the track that lives in a shared library, with `Range` support, as a listener would get it. A track that is
only in libraries that are not shared is `track_not_found`. A friend has a few streams open at a time and a number
of bytes a second to share among them, both set by the admin (`max_streams`, `max_kib_per_sec`): one stream too many
is a `429` (`too_many_streams`) with `Retry-After`.
security: [{friendSignature: []}]
parameters:
- name: Range
in: header
required: false
description: A byte range, for example `bytes=0-99`.
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
headers:
Accept-Ranges: {$ref: '#/components/headers/AcceptRanges'}
Content-Length: {$ref: '#/components/headers/ContentLength'}
Last-Modified: {$ref: '#/components/headers/LastModified'}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
'206':
description: The requested byte range.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
multipart/byteranges:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/FriendUnauthorized'}
'403': {$ref: '#/components/responses/FriendNotApproved'}
'404':
description: No such track among the shared libraries (`track_not_found`), its file is not available (`file_missing`), or federation is off (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
'416':
description: The range cannot be satisfied.
headers:
Content-Range:
description: '`bytes */<size of the file>`.'
schema: {type: string}
'429':
description: The friend already has as many streams open as allowed (`too_many_streams`).
headers:
Retry-After:
description: Seconds to wait.
schema: {type: integer}
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
components:
securitySchemes:
bearerAuth:
@ -3175,6 +3515,18 @@ components:
name: access_token
description: The same access token, for stream URLs used by an `<audio>` element. Accepted only on `/tracks/{id}/stream`, `/albums/{id}/cover` and `/artists/{id}/image`.
friendSignature:
type: apiKey
in: header
name: Sonda-Signature
description: |
For the routes under `/peer`, which only another Sonda server calls. Each request carries four headers:
`Sonda-Key-Id` (the first 16 hex characters of the SHA-256 of the sender's public key), `Sonda-Date` (unix
seconds, at most two minutes from the receiver's clock), `Sonda-Nonce` (16 to 64 characters of `A-Za-z0-9_-`, never
used twice) and `Sonda-Signature` (the Ed25519 signature, base64url without padding, of these five lines:
the method, the path from `/api/v1/peer` on with the query as sent, the date, the nonce and the SHA-256 in hex of
the body, which is empty). Anything that is not properly signed gets the same `401`.
parameters:
Id:
name: id
@ -3244,6 +3596,21 @@ components:
schema: {type: string}
responses:
FriendUnauthorized:
description: "The request is not signed by a friend: no signature, a bad one, an old date, a nonce used before or an unknown key, all the same answer (`unauthorized`)."
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FriendNotApproved:
description: The signature is good but the admin of this server has not approved the friend yet (`not_approved`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
FederationOff:
description: Federation is off on this server, so the route is as good as missing (`not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
InvalidInput:
description: The request is malformed or a value is out of range (`invalid_input`).
content:
@ -3390,11 +3757,12 @@ components:
Library:
type: object
additionalProperties: false
required: [id, name, path, created_at]
required: [id, name, path, shared, created_at]
properties:
id: {type: integer, format: int64}
name: {type: string}
path: {type: string, description: Absolute directory on the server.}
shared: {type: boolean, description: Whether friends (federation) may read this library. Off until an admin turns it on.}
created_at: {type: string, format: date-time}
NewLibrary:
@ -3409,9 +3777,11 @@ components:
anyOf:
- required: [name]
- required: [path]
- required: [shared]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string}
shared: {type: boolean, description: "Whether friends may read this library. Changing it never needs a scan and never waits for one."}
ScanSummary:
type: object
@ -4505,13 +4875,15 @@ components:
Federation:
type: object
additionalProperties: false
required: [enabled, name, address, key_id, sends, friends]
required: [enabled, name, address, key_id, sends, max_streams, max_kib_per_sec, friends]
properties:
enabled: {type: boolean, description: Whether this server may pair with others. Off by default.}
name: {type: string, description: How friends see this server.}
address: {type: string, description: Where friends reach this server; empty until set.}
key_id: {type: string, description: "Names this server's key; empty until federation was first turned on. Compare it with the one the other admin sees."}
sends: {type: string, description: "What a friend's server is sent, and what it never learns."}
max_streams: {type: integer, minimum: 1, maximum: 20, description: Streams one friend may have open at a time.}
max_kib_per_sec: {type: integer, minimum: 0, maximum: 102400, description: "KiB a second one friend may take over all its streams; 0 means no limit. Otherwise at least 64."}
friends:
type: array
items: {$ref: '#/components/schemas/FederationFriend'}
@ -4522,10 +4894,32 @@ components:
- required: [enabled]
- required: [name]
- required: [address]
- required: [max_streams]
- required: [max_kib_per_sec]
properties:
enabled: {type: boolean}
max_streams: {type: integer}
max_kib_per_sec: {type: integer}
name: {type: string, maxLength: 240, description: "At most 60 characters, no control characters. Empty goes back to the host name."}
address: {type: string, maxLength: 300}
FederationRequest:
type: object
additionalProperties: false
required: [at, friend_id, friend, route, status, bytes]
properties:
at: {type: string, format: date-time}
friend_id: {type: integer}
friend: {type: string, description: The name of the friend.}
route: {type: string, description: "The route pattern, like `/api/v1/peer/tracks/:id/stream`. Never the query."}
status: {type: integer}
bytes: {type: integer, format: int64, description: Bytes of the answer.}
PeerInfo:
type: object
additionalProperties: false
required: [name, shared_libraries]
properties:
name: {type: string}
shared_libraries: {type: integer, description: How many libraries are shared with friends.}
FederationInvite:
type: object
additionalProperties: false