diff --git a/app/api/basics/page.mdx b/app/api/basics/page.mdx index deb0f5a..621e55f 100644 --- a/app/api/basics/page.mdx +++ b/app/api/basics/page.mdx @@ -11,23 +11,44 @@ Versia defines a very simple API for server-to-server communication, mainly fetc Every Versia API endpoint is prefixed with `/.versia/vX/`, where `X` is the version of the API. The current version is `0.6`, so the current API prefix is `/.versia/v0.6/`. This versioning is used to avoid breaking changes in the future, and to allow for backwards compatibility. -Requests not encrypted with TLS (aka HTTPS) **MUST NOT** be sent or responded to. All implementations are required to use TLS 1.2 or higher, and to support HTTP/2. +Requests not encrypted with TLS (aka HTTPS) **must not** be sent or responded to. All implementations are required to use TLS 1.2 or higher, and to support HTTP/2. - Implementations have no obligations to support more than one Versia version. It is recommended to always support the latest version, as it helps avoid bogging down the network with old versions. + Implementations have no obligation to support more than one Versia version. It is recommended to always support the latest version, as it helps avoid bogging down the network with old versions. ## Signatures -- All API requests **MUST** be signed, unless otherwise specified. This includes `POST` and `GET` requests. -- All API responses **MUST** be signed, unless otherwise specified. - -The signature mechanism is defined in the [Signatures](/signatures) document. +API requests/responses between instances **must** include a [Signature](/signatures), signed with the [instance's private key](/entities/instance-metadata), as defined in [Signatures](/signatures). ## Encoding "URL-encoding" is the mechanism used to encode data containing special characters in URLs. When this specification refers to "URL-encoding", it means the encoding defined in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1). +## Domain + +Versia defines a **domain** as the hostname of an instance, which is used to identify the instance in the network. It **must** be a valid hostname, and cannot include a port number (the HTTPS port is always 443). + +Defining a domain is very complicated, so please refer to the following examples: + +``` {{ "title": "Valid Domains" }} +example.com +test.localhost +sus.example.org +xn--ls8h.la +1.0.1.7.0.8.0.0.0.0.7.4.0.1.0.0.2.ip6.arpa # We know what you did +``` + +``` {{ "title": "Invalid Domains" }} +example.com:3000 # ❌️ Invalid: port number is not allowed +test..localhost # ❌️ Invalid: double dot is not allowed +example.com. # ❌️ Invalid: trailing dot is not allowed +test.org/ # ❌️ Invalid: trailing slash is not allowed +test.org/sus # ❌️ Invalid: path is not allowed +💩.la # ❌️ Invalid: IDNs must be Punycode encoded +https://bob.org # ❌️ Invalid: protocol is not allowed +``` + ## Redirects API endpoints **MUST NOT** redirect to other endpoints, with the following exceptions: diff --git a/app/api/endpoints/page.mdx b/app/api/endpoints/page.mdx index ca7bc92..33f1db0 100644 --- a/app/api/endpoints/page.mdx +++ b/app/api/endpoints/page.mdx @@ -22,7 +22,7 @@ export const metadata = { Must be `GET`. - Must be the instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document. + Instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document. @@ -66,7 +66,7 @@ export const metadata = { Must be `GET`. - Must be the entity's data as JSON, as defined in its [Entity](/entities) definition document. + Entity data as JSON, as defined in its [Entity](/entities) definition document. @@ -151,9 +151,9 @@ Accept: application/vnd.versia+json ## Inbox -The inbox endpoint is used for other instances to send entities to this instance. It is a single endpoint that can receive messages for every user (also known as a shared inbox). +The inbox endpoint is used for instances to send entities to each other. It is a single endpoint that can receive messages for every user (also known as a shared inbox). -The delivery mechanism is described further in the [Federation](/federation) document. +The delivery mechanism is described further in the [Federation](/federation#inboxes) document. diff --git a/app/changelog/page.mdx b/app/changelog/page.mdx index 05c7f15..2eed47b 100644 --- a/app/changelog/page.mdx +++ b/app/changelog/page.mdx @@ -20,6 +20,13 @@ This page lists changes since Working Draft 3. {{ className: 'lead' }} - Added [References](/types#reference) as a way to refer to other entities. - Mandated the usage of `null` for optional fields that are not set, instead of omitting them. - Changed usage of "`null` authors" to simply being an optional field. +- Added more guidelines on [JSON data handling](/json). +- Clarified the meaning of [Domain](/api/basics#domain) in the context of Versia. +- Changes to [Note](/entities/note): + - `is_sensitive`, `attachments`, `mentions` and `previews` are now required. +- Changes to [User](/entities/user): + - `fields`, `manually_approves_followers` and `indexable` are now required. +- Removed "short pronoun" from [Vanity Extension](/extensions/vanity) (union types are tricky to parse in strongly typed languages). ## Since WD 4 diff --git a/app/entities/delete/page.mdx b/app/entities/delete/page.mdx index 8a3d292..cf71d3f 100644 --- a/app/entities/delete/page.mdx +++ b/app/entities/delete/page.mdx @@ -5,14 +5,14 @@ export const metadata = { # Delete -Signals the deletion of an entity. It is a [**Transient Entity**](/entities#transient-entities). {{ className: 'lead' }} +Signals the deletion of an entity. {{ className: 'lead' }} ## Authorization Implementations **must** ensure that the author of the `Delete` entity has the authorization to delete the target entity. Having the authorization is defined as: -- The author is the creator of the target entity (including [delegation](/federation/delegation)). +- The author is the creator of the target entity (including [delegation](/extensions/delegation)). - The author is the instance. ## Entity Definition diff --git a/app/entities/instance-metadata/page.mdx b/app/entities/instance-metadata/page.mdx index 4e5439f..8fae58c 100644 --- a/app/entities/instance-metadata/page.mdx +++ b/app/entities/instance-metadata/page.mdx @@ -48,8 +48,8 @@ Contains metadata about a Versia instance, such as capabilities and endpoints. { Long description of the instance, for humans. Should be around 100-200 words. - - Hostname of the instance. Includes the port if it is not the default (i.e. `443` for HTTPS). + + Domain of the instance, used for federation. Public key of the instance. @@ -96,7 +96,7 @@ Contains metadata about a Versia instance, such as capabilities and endpoints. { ] }, "description": "Server for Jim's Jolly Jimjams, a social network for fans of Jimjams.", - "host": "social.jimjams.com", + "domain": "social.jimjams.com", "logo": { "image/png": { "content": "https://social.jimjams.com/files/logo.png" diff --git a/app/entities/note/page.mdx b/app/entities/note/page.mdx index af7098a..91c717b 100644 --- a/app/entities/note/page.mdx +++ b/app/entities/note/page.mdx @@ -16,7 +16,7 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ - + Media attachments to the note. May be any format. **Must** be remote. @@ -61,13 +61,13 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ If the implementation does not support the [Groups Extension](/extensions/groups), any value other than `public` or `followers` should be treated as `null`. - + Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature. - + [References](/types#reference) to [Users](/entities/user) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications. - + Previews for any links in the publication. This is to avoid the [stampeding mastodon problem](https://github.com/mastodon/mastodon/issues/23662) where a link preview is fetched by every instance that sees the publication, creating an accidental DDOS attack. ```typescript @@ -108,6 +108,9 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ "content": "https://cdn.versia.social/29e810bf4707fef373d886af322089d5db300fce66e4e073efc26827f10825f6/image.webp", "remote": true, "thumbhash": "1QcSHQRnh493V4dIh4eXh1h4kJUI", + "description": null, + "fps": null, + "duration": null, "height": 960, "size": 221275, "hash": { @@ -120,6 +123,12 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ "text/plain": { "content": "https://cdn.lysand.org/68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d/fire.txt", "remote": true, + "description": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null "size": 8, "hash": { "sha256": "68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d" @@ -150,7 +159,10 @@ Notes represent a piece of content on a Versia instance. They can be posted by [ "group": "public", "is_sensitive": false, "mentions": [], - "subject": "Versia development" + "subject": "Versia development", + "previews": [], + "quotes": null, + "replies_to": null } ``` diff --git a/app/entities/page.mdx b/app/entities/page.mdx index aec10f8..3ffdcb4 100644 --- a/app/entities/page.mdx +++ b/app/entities/page.mdx @@ -6,9 +6,12 @@ export const metadata = { # Entities -Entities are the foundation of the Versia protocol. A similar concept to entities are the [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects, which are used to represent activities in the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol. {{ className: 'lead' }} +Entities are the foundation of the Versia protocol. They are similar to: {{ className: 'lead' }} -## Entity Definition +- [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects +- [Matrix](https://matrix.org/) events. + +## Definition An entity is a simple JSON object that represents a core data structure in Versia. Entities are used to represent various types of data, such as users, notes, and more. Each entity has a unique `id` property that is used to identify it within the instance. @@ -31,11 +34,11 @@ Any field in an entity not marked as `required` may be set to `null`. These fiel Type of the entity. Custom types must follow [Extension Naming](/extensions#naming). - + Date and time when the entity was created. Must be an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp. - Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion. + Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion. Sending a [Note](/entities/note) created on `13-12-1337` is very funny, but don't be surprised if it is rejected. @@ -86,14 +89,6 @@ Any field in an entity not marked as `required` may be set to `null`. These fiel ## Transient Entities -Some entities are transient, meaning they cannot be refetched using the [Federation API](/api/endpoints). These entities are used for actions that do not require a permanent record, such as deletions or migrations. Transient Entities do not have an `id` field. +Some entities are **transient**, meaning they cannot be fetched using the [Federation API](/api/endpoints). These entities are used for actions that do not require a permanent record, such as deletions or migrations. Transient Entities do not have an `id` field. -Implementations **must not** rely on other implementations to store transient entities in their database. - -## Serialization - -When serialized to a string, the JSON representation of an entity must follow the following rules: -- Keys must be sorted lexicographically. -- Must use UTF-8 encoding. -- Must be **signed** using the the [instance's private key](/entities/instance-metadata). -- Must use Unix-style `\n` line endings (LF). \ No newline at end of file +Implementations **must not** rely on other implementations to store transient entities in their database. \ No newline at end of file diff --git a/app/entities/user/page.mdx b/app/entities/user/page.mdx index 94a078e..c5d6e1f 100644 --- a/app/entities/user/page.mdx +++ b/app/entities/user/page.mdx @@ -35,7 +35,7 @@ Usernames can be changed by the user, so it is recommended to use `id` for long- ### Instance -Instance **must** be the host of the instance the user is on (hostname with optional port). +Instance **must** be the [Domain](/api/basics#domain) that the user is on. ## Entity Definition @@ -52,7 +52,7 @@ Instance **must** be the host of the instance the user is on (hostname with opti Display name, as shown to other users. May contain emojis and any Unicode character. - + Custom key/value pairs. For example, metadata like socials or pronouns. Must be text format (`text/*`). ```typescript @@ -70,11 +70,11 @@ Instance **must** be the host of the instance the user is on (hostname with opti A header image for the user's profile. Also known as a cover photo or a banner. Must be an image format (`image/*`). - - If `true`, the user must approve any new followers manually. If `false`, followers are automatically approved. This does not affect federation, and is meant to be used for clients to display correct UI. Defaults to `false`. + + If `true`, the user must approve any new followers manually. If `false`, followers are automatically approved. This does not affect federation, and is meant to be used for clients to display correct UI. - - User consent to be indexed by search engines. If `false`, the user's profile should not be indexed. Defaults to `true`. + + User consent to be indexed by search engines. If `false`, the user's profile should not be indexed. diff --git a/app/extensions/custom-emojis/page.mdx b/app/extensions/custom-emojis/page.mdx index 25a6072..a1b1e45 100644 --- a/app/extensions/custom-emojis/page.mdx +++ b/app/extensions/custom-emojis/page.mdx @@ -39,6 +39,13 @@ The Custom Emojis extension adds support for adding personalized emojis to feder "content": "https://cdn.example.com/emojis/happy_face.webp", "remote": true, "description": "A happy emoji smiling.", + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } } } @@ -95,7 +102,8 @@ Custom Emojis can be added to any entity with text content. The extension ID is "content": "Hello, world :happy_face:!" } }, - "extensions": { // [!code focus:16] + ... + "extensions": { // [!code focus:23] "pub.versia:custom_emojis": { "emojis": [ { @@ -105,6 +113,13 @@ Custom Emojis can be added to any entity with text content. The extension ID is "content": "https://cdn.example.com/emojis/happy_face.webp", "remote": true, "description": "A happy emoji smiling.", + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } } } diff --git a/app/extensions/groups/page.mdx b/app/extensions/groups/page.mdx index 818af8d..bbfb469 100644 --- a/app/extensions/groups/page.mdx +++ b/app/extensions/groups/page.mdx @@ -27,7 +27,7 @@ Refer to [Note](/entities/note#entity-definition)'s `group` property for how not Text only (`text/plain`, `text/html`, etc). - + Whether the group is open to all users or requires approval to join. diff --git a/app/extensions/interaction-controls/page.mdx b/app/extensions/interaction-controls/page.mdx index afd30b4..f81bfcb 100644 --- a/app/extensions/interaction-controls/page.mdx +++ b/app/extensions/interaction-controls/page.mdx @@ -21,6 +21,7 @@ The entity defined in this document must be inserted in the `pub.versia:interact "content": "Hello, world :happy_face:!" } }, + ... "extensions": { // [!code focus:9] "pub.versia:interaction_controls": { "reply": { diff --git a/app/extensions/page.mdx b/app/extensions/page.mdx index f84e12a..8dd3c67 100644 --- a/app/extensions/page.mdx +++ b/app/extensions/page.mdx @@ -21,7 +21,7 @@ Extensions **must not** be designed in a way that makes them required to underst Versia extension names are composed of two parts: - The domain name of the extension author, in reverse order. Example: `pub.versia` -- The extension name, separated by a colon. `snake_case`. Example: `likes` +- The extension name, separated by a colon, in `snake_case`. Example: `likes` ``` {{ title: "Example Extension Name" }} pub.versia:likes @@ -30,7 +30,7 @@ pub.versia:likes ### Custom entities Custom entities are named in the same way, but with an additional part: -- The entity name, separated by a slash. `PascalCase`. Example: `Like` +- The entity name, separated by a slash, in `PascalCase`. Example: `Like` ``` {{ title: "Example Custom Entity Type" }} pub.versia:likes/Like @@ -49,9 +49,7 @@ Extensions can be found in two places: an [Entity](/entities#entity-definition)' Custom extensions to the entity. - `key`: The extension name. - - `value`: Extension data. Can be any JSON-serializable data. - - Extension data can be any JSON-serializable data. + - `value`: Extension data. Can be any JSON object, following [Versia JSON rules](/json). @@ -63,6 +61,7 @@ Extensions can be found in two places: an [Entity](/entities#entity-definition)' "id": "ed480922-b095-4f09-9da5-c995be8f5960", "name": null, "description": null, + "open": true, "extensions": { // [!code focus:100] "com.example:gps": { "location": { @@ -85,7 +84,7 @@ Extensions can be found in two places: an [Entity](/entities#entity-definition)' - The extension type. [Must follow naming conventions](#naming). + The extension type, [following naming conventions](#naming). Other properties of the custom entity. These are specific to the extension, and should be documented by the extension author. diff --git a/app/extensions/polls/page.mdx b/app/extensions/polls/page.mdx index f9e30dc..d07ef97 100644 --- a/app/extensions/polls/page.mdx +++ b/app/extensions/polls/page.mdx @@ -29,7 +29,7 @@ Note that there is no `question` field: the question should be included in the ` Whether the poll allows multiple votes to be cast for different options. - + RFC 3339 timestamp of when the poll ends and no more votes can be cast. If not present, the poll does not expire. @@ -49,6 +49,7 @@ Note that there is no `question` field: the question should be included in the ` "content": "What is your favourite color?" } }, + ... "extensions": { // [!code focus:28] "pub.versia:polls": { "options": [ diff --git a/app/extensions/vanity/page.mdx b/app/extensions/vanity/page.mdx index 626e3f1..1fde257 100644 --- a/app/extensions/vanity/page.mdx +++ b/app/extensions/vanity/page.mdx @@ -42,13 +42,10 @@ All properties are optional. Audio format (e.g. `audio/mpeg`). - An array of internationalized pronouns the user uses. Can be represented as a string or an object. + An array of internationalized pronouns the user uses. ```typescript - /* e.g. "he/him" */ - type ShortPronoun = string; - - interface LongPronoun { + interface Pronoun { subject: string; object: string; dependent_possessive: string; @@ -56,12 +53,11 @@ All properties are optional. reflexive: string; } - type Pronoun = ShortPronoun | LongPronoun; /* Example: en-US or fr */ type LanguageCode = string; ``` - + User's birthday. If year is left out or set to `0000`, implementations **SHOULD** not display the year. @@ -92,6 +88,14 @@ All properties are optional. "image/png": { "content": "https://cdn.example.com/ab5081cf-b11f-408f-92c2-7c246f290593/cat_ears.png", "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } } ], @@ -99,23 +103,53 @@ All properties are optional. "image/png": { "content": "https://cdn.example.com/d8c42be1-d0f7-43ef-b4ab-5f614e1beba4/rounded_square.jpeg", "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } }, "background": { "image/png": { "content": "https://cdn.example.com/6492ddcd-311e-4921-9567-41b497762b09/untitled-file-0019822.png", "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } }, "audio": { "audio/mpeg": { "content": "https://cdn.example.com/4da2f0d4-4728-4819-83e4-d614e4c5bebc/michael-jackson-thriller.mp3", "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } }, "pronouns": { "en-us": [ - "he/him", + { + "subject": "he", + "object": "him", + "dependent_possessive": "his", + "independent_possessive": "his", + "reflexive": "himself" + }, { "subject": "they", "object": "them", diff --git a/app/federation/discovery/page.mdx b/app/federation/discovery/page.mdx index f67b931..d317b52 100644 --- a/app/federation/discovery/page.mdx +++ b/app/federation/discovery/page.mdx @@ -49,7 +49,7 @@ Accept: application/jrd+json ## Instance Discovery -Instaance metadata can be accessed by making a `GET` request to the instance's Versia metadata endpoint, documented in the [Endpoints](/api/endpoints#instance-metadata) document. +Instance metadata can be accessed by making a `GET` request to the instance's Versia metadata endpoint, documented in the [Endpoints](/api/endpoints#instance-metadata) document. ### Example @@ -80,7 +80,10 @@ Accept: application/vnd.versia+json "pub.versia:reports" ] }, - "host": "versia.social", - "created_at": "2021-07-01T00:00:00Z" + "domain": "versia.social", + "created_at": "2021-07-01T00:00:00Z", + "description": null, + "logo": null, + "banner": null } ``` \ No newline at end of file diff --git a/app/federation/example/page.mdx b/app/federation/example/page.mdx index 34e2d25..ad4893b 100644 --- a/app/federation/example/page.mdx +++ b/app/federation/example/page.mdx @@ -50,7 +50,7 @@ curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accep In a real Versia implementation, usernames would **not** be included in user profile's URL, as they can be changed. Instead, the `id` could be used. - This is done for simplicity in this example. + This is done for brevity here. ### Fetching the User @@ -58,10 +58,10 @@ curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accep `a.social` fetches the user profile of `joe` from `b.social` using the URL provided in the WebFinger response. ```bash +# The request is signed by a.social's instance private key curl https://b.social/.versia/entities/User/joe \ -H "Accept: application/vnd.versia+json" \ -H "User-Agent: CoolServer/1.0 (https://coolserver.com)" \ - # The request is signed by a.social's instance private key -H "Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==" \ -H "Versia-Signed-By: a.social" \ -H "Versia-Signed-At: 1729241687" @@ -71,17 +71,30 @@ curl https://b.social/.versia/entities/User/joe \ ```json { - "id": "bde22zi3ca8762", // [!code focus:10] + "id": "bde22zi3ca8762", // [!code focus:3] "type": "User", "created_at": "2024-10-13T18:48:19Z", "avatar": { "image/webp": { "content": "https://cdn.b.social/avatars/joe.webp", - "remote": true + "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } }, // [!code focus:3] "display_name": "Joe Swanson (Winter Arc :gigachad:)", "username": "joe", + "bio": null, + "header": null, + "fields": [], + "manually_approves_followers": false, + "indexable": true, "extensions": { "pub.versia:custom_emojis": { "emojis": [ @@ -90,7 +103,15 @@ curl https://b.social/.versia/entities/User/joe \ "content": { "image/png": { "content": "https://cdn.b.social/emojis/gigachad.png", - "remote": true + "remote": true, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } } } @@ -112,21 +133,44 @@ Finally, `a.social` serializes the note to send it to `joe`. "type": "Note", "created_at": "2024-12-01T12:19:06Z", "author": "alice", - "category": "microblog", // [!code focus:11] + "category": "microblog", "content": { - "text/html": { + "text/html": { // [!code focus:12] "content": "Hello, @joe@b.social! How are you doing today?", "remote": false, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null }, "text/plain": { "content": "Hello, @joe@b.social! How are you doing today?", "remote": false, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } }, "group": "public", "mentions": [ // [!code focus:3] "b.social:bde22zi3ca8762" - ] + ], + "attachments": [], + "is_sensitive": false, + "previews": [], + "replies_to": null, + "quotes": null, + "subject": null, + "device": null, } ``` diff --git a/app/federation/http/page.mdx b/app/federation/http/page.mdx index dd94545..575d714 100644 --- a/app/federation/http/page.mdx +++ b/app/federation/http/page.mdx @@ -8,7 +8,7 @@ export const metadata = { Versia uses the HTTP protocol for all communications between instances. HTTP requests must conform to certain standards to ensure compatibility between different implementations, as well as to ensure the security and integrity of the data being exchanged. -ALL kinds of HTTP requests/responses between instances **MUST** include a [Signature](/signatures), signed with either the relevant [User](/entities/user)'s private key or the [instance's private key](/entities/instance-metadata). +HTTP requests/responses between instances **must** include a [Signature](/signatures), signed with the [instance's private key](/entities/instance-metadata), as defined in [Signatures](/signatures). ## Requests @@ -16,22 +16,26 @@ ALL kinds of HTTP requests/responses between instances **MUST** include a [Signa - Must include `application/vnd.versia+json`, unless specified otherwise. + Must be `application/vnd.versia+json`, unless specified otherwise. Basic `application/json` is **not** allowed. - Must include `application/vnd.versia+json; charset=utf-8`, if the request has a body. + Must be `application/vnd.versia+json; charset=utf-8` if the request has a body. - + See [Signatures](/signatures) for more information. - + See [Signatures](/signatures). - + See [Signatures](/signatures). - A string identifying the software making the request. + A string identifying the software making the request. Should contain the name of the software, its version, and a link to its homepage. + + ``` {{ 'title': 'Example User-Agent' }} + CoolServer/1.0 (https://coolserver.com) + ``` @@ -50,9 +54,9 @@ ALL kinds of HTTP requests/responses between instances **MUST** include a [Signa ## Rate limits -Implementations **MUST** respect the rate limits of remote instances. +Implementations **must** respect the rate limits of remote instances. -IETF draft [draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html) **MUST** be used to communicate rate limits. Other rate limit headers/formats are not allowed. +IETF draft [draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html) **must** be used to communicate rate limits. Other rate limit headers/formats are not allowed. This IETF draft is, well, a draft. However, there are no standards for rate limiting in HTTP, so this is the best we have. @@ -66,13 +70,13 @@ IETF draft [draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/dr Must include `application/vnd.versia+json; charset=utf-8`, unless specified otherwise. - + See [Signatures](/signatures) for more information. - + See [Signatures](/signatures). - + See [Signatures](/signatures). diff --git a/app/federation/page.mdx b/app/federation/page.mdx index 0072096..13ca699 100644 --- a/app/federation/page.mdx +++ b/app/federation/page.mdx @@ -29,7 +29,7 @@ Ever [Instance](/entities/instance-metadata) has a personal HTTP endpoint called Let's consider the following example: -> Alice, on the instance `alice.example`, sends a message to Bob on the instance `bob.example`. +Alice, on the instance `alice.example`, sends a message to Bob on the instance `bob.example`. To perform this action, Alice's instance sends a `POST` request to Bob's instance's inbox endpoint. This request contains the [Note](/entities/note) entity that Alice wants to send to Bob, with [the appropriate metadata](/federation/http) to ensure the message is valid. @@ -39,4 +39,12 @@ Bob's instance receives the message and processes it according to the rules defi In addition to inboxes, every user has an outbox (at `/.versia/v0.6/entities/User//collections/outbox`). The outbox is simply a [Collection](/structures/collection) of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox. + + Implementations **should** filter out entities that are not relevant to the request author when returning the outbox. + + For example, if Alice sends a [Note](/entities/note) to Bob on `direct` visibility: + - Alice's instance **should** return the [Note](/entities/note) in response to a request from Bob's instance. + - Alice's instance **should not** display the [Note](/entities/note) in her outbox in response to a request from Joe's instance. + + Outboxes are very useful for "backfilling" data when a new instance joins the network. By resolving the outboxes of all new users it encounters, a new instance can quickly catch up on all old messages. \ No newline at end of file diff --git a/app/federation/validation/page.mdx b/app/federation/validation/page.mdx index 493b04b..2739f39 100644 --- a/app/federation/validation/page.mdx +++ b/app/federation/validation/page.mdx @@ -6,7 +6,7 @@ export const metadata = { # Validation -Implementations **MUST** strictly validate all incoming data to ensure that it is well-formed and adheres to the Versia Protocol. If a request is invalid, the instance **MUST** return a `400 Bad Request` HTTP status code. +Implementations **MUST** strictly validate all incoming data to ensure that it is well-formed and adheres to the Versia Protocol. If a request is invalid, the instance **MUST** return a `422 Unprocessable Entity` HTTP status code. Remember that while *your* implementation may disallow or restrict some user input, other implementations may not. You **should not** apply those restrictions to data coming from other instances. @@ -16,13 +16,13 @@ Implementations **MUST** strictly validate all incoming data to ensure that it i Things that should be validated include, but are not limited to: -- The presence of **all required fields**. +- The presence of **all required fields**, and the presence of `null` on optional fields. - The **format** of all fields (integers should not be strings, timestamps should be in RFC 3339 format, etc.). - The presence of **all required headers**. - The presence of a **valid signature**. - The **length** of all fields (for example, the `username` field on a `User` entity) should be at least 1 character long. - Do not set arbitrary limits on the length of fields that other instances may send you. For example, a `bio` field should not be limited to 160 characters, even if your own implementation has such a limit. - - If you do set limits, they should be reasonable, well-documented and should allow Users to easily view the remote original, by, for example, linking to it. + - If you do set limits, they should be reasonable, well-documented and should allow Users to easily view the remote original, by, for example, linking to it. A limit of `100 000` characters for a `bio` field is acceptable, but a limit of `160` characters is not. - The **type**, **precision** and **scale** of all numeric fields. - For example, a `size` field on a `ContentFormat` structure should be a positive integer, not a negative number or a floating-point number. @@ -30,7 +30,7 @@ Things that should be validated include, but are not limited to: Using the same type with a higher bit count, for example using a u128 instead of a u64, is acceptable. Beware of performance impacts this may cause. -- The **validity** of all URLs and URIs (run them through your favorite URL parser, optionally fetch the linked URL). +- The **validity** of all URLs and URIs (run them through your favorite URL parser). - The **time** of all dates and times (people should not be born in the future, or in the year 0). It is your implementation's duty to reject data from other instances that does not adhere to the strict spec. **This is crucial to ensure the integrity of your instance and the network as a whole**. Allowing data that is technically valid but semantically incorrect can lead to the degradation of the entire Versia ecosystem. diff --git a/app/introduction/page.mdx b/app/introduction/page.mdx index 6274e6b..4df6f95 100644 --- a/app/introduction/page.mdx +++ b/app/introduction/page.mdx @@ -3,7 +3,7 @@ import { HeroPattern } from '@/components/HeroPattern' export const metadata = { title: 'Versia Documentation', - description: 'Introduction to the Versia Protocol, a communication medium for federated applications, leveraging the HTTP stack.', + description: 'Introduction to the Versia Protocol, a communication medium for federated applications, using the HTTP stack.', } export const sections = [ @@ -16,7 +16,7 @@ export const sections = [ # Versia Federation Protocol -The Versia Protocol is designed as a communication medium for federated applications, leveraging the HTTP stack. Its simplicity ensures ease of implementation and comprehension. {{ className: 'lead' }} +The Versia Protocol is designed as a communication medium for federated applications, using the HTTP stack. Its simplicity ensures ease of implementation and comprehension. {{ className: 'lead' }}

Thanks

diff --git a/app/philosophy/principles/page.mdx b/app/philosophy/principles/page.mdx index 0842424..7fba24e 100644 --- a/app/philosophy/principles/page.mdx +++ b/app/philosophy/principles/page.mdx @@ -28,6 +28,6 @@ Developer-facing features (e.g. shared inboxes, reply backfilling, etc.) should ## Branching -There should be **as little branching as possible**. This is reminiscent of the "one canonical way" principle: if there are multiple ways to do something, or a thing can be processed multiple ways, it should be simplified. +There should be **as little branching logic as possible**. This is reminiscent of the "one canonical way" principle: if there are multiple ways to do something, or a thing can be processed multiple ways, it should be simplified. -If there is a need for branching, nesting should be avoided: branches should be as flat as possible. \ No newline at end of file +If there is a need for branching, nesting should be avoided: logic branches should be as flat as possible. \ No newline at end of file diff --git a/app/security/page.mdx b/app/security/page.mdx index 62cf1e6..4957a67 100644 --- a/app/security/page.mdx +++ b/app/security/page.mdx @@ -16,7 +16,7 @@ export const metadata = { Versia's security model is designed to ensure the integrity and authenticity of data, with a simple but robust system of cryptographic signatures. This system is designed to be easy to implement and understand, while still providing strong guarantees. -However, **it is of critical importance to understand the limitations of this system**. Versia's security model is designed to prevent impersonation attacks and data tampering, but it does not provide confidentiality. This means that while you can trust the data you receive, you should not assume that it is private. +However, **it is very important to understand the limitations of this system**. Versia's security model is designed to prevent impersonation attacks and data tampering, but it does not provide confidentiality. This means that while you can trust the data you receive, you should not assume that it is private. There are three main kinds of security that are commonly discussed in the context of cryptography: @@ -47,13 +47,12 @@ There are several reasons why confidentiality is not covered as part of this spe - Email - The Web - Twitter -- TCP Confidentiality is **several orders of magnitude more complex** than integrity and authenticity. It requires a completely different set of tools and assumptions, which are not feasible to reliably implement in a complex federated system (if you've ever seen `** Unable to decrypt: The sender's device has not sent us the keys for this message. **`, you know what we're talking about). Furthermore, adding more complex cryptography would make the specification significantly more complex, which would likely make it harder to implement for smaller developers with less resources. -Additionally, we would like to avoid re-creating what would essentially be a shoddier version of much stronger centralized platforms like [Signal](https://signal.org/). We feel, just like many others before us, that it is better to leave the confidentiality to the experts. +Additionally, we would like to avoid re-creating what would essentially be a shoddier version of much stronger centralized platforms like [Signal](https://signal.org/). We feel that it is better to leave the confidentiality to the experts. ## Conclusion diff --git a/app/signatures/page.mdx b/app/signatures/page.mdx index e1b4b49..9c8ba31 100644 --- a/app/signatures/page.mdx +++ b/app/signatures/page.mdx @@ -18,15 +18,15 @@ Versia uses cryptographic signatures to ensure the integrity and authenticity of A signature consists of a series of headers in an HTTP request. The following headers are used: - **`Versia-Signature`**: The signature itself, encoded in base64. -- **`Versia-Signed-By`**: Hostname of the instance that signed the request. This **MUST** be a hostname reachable over HTTPS (including port number if applicable), and **MUST NOT** be a URL. -- **`Versia-Signed-At`**: The current Unix timestamp, in seconds (no milliseconds), when the request was signed. Timezone must be UTC, like all Unix timestamps. +- **`Versia-Signed-By`**: [Domain](/api/basics#domain) of the instance authoring the request. +- **`Versia-Signed-At`**: The current Unix timestamp, in seconds (integer), when the request was signed. Timezone must be UTC, like all Unix timestamps. -Signatures are **required on ALL federation traffic**. If a request does not have a signature, it **MUST** be rejected. Specifically, signatures must be put on: -- **All POST requests**. -- **All GET requests**. -- **All responses to GET requests** (for example, when fetching a user's profile). In this case, the HTTP method used in the signature string must be `GET`. +Signatures must be put on: +- **All `POST` requests**. +- **All `GET` requests**. +- **All responses to `GET` requests** (for example, when fetching a user's profile). -If a signature fails, is missing or is invalid, the instance **MUST** return a `401 Unauthorized` HTTP status code. If the signature timestamp is too old or too new (more than 5 minutes from the current time), the instance **MUST** return a `422 Unprocessable Entity` status code. +If a signature fails, is missing or is invalid, the instance **must** return a `401 Unauthorized` HTTP status code. If the signature is too old or too new (more than 5 minutes from the current time), the instance **must** return a `422 Unprocessable Entity` status code. ### Calculating the Signature @@ -36,12 +36,12 @@ $0 $1 $2 $3 ``` Where: -- `$0` is the HTTP method (e.g. `GET`, `POST`) in lowercase. -- `$1` is the path of the request, in standard URI format (don't forget to URL-encode it). -- `$2` is the Unix timestamp when the request was signed, in UTC seconds. +- `$0` is the HTTP method (e.g. `GET`, `POST`) in lowercase. If signing a *response*, use the method of the original request. +- `$1` is the request pathname, URL-encoded. +- `$2` is the Unix timestamp when the request was signed, in UTC seconds (integer). - `$3` is the SHA-256 hash of the request body, encoded in base64. (if it's a `GET` request, this should be the hash of an empty string) -Sign this string using the user's private key. The resulting signature should be encoded in base64. +Sign this string using the instance's private key with the [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) algorithm. The resulting bytes **must** be encoded in base64. Example: ``` @@ -50,12 +50,12 @@ post /notes 1729243417 n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg= ### Verifying the Signature -To verify a signature, the instance must: +To verify a signature, the verifying instance must: - Recreate the string as described above. - Extract the signature provided in the `Versia-Signature` header. - Check that the `Versia-Signed-At` timestamp is within 5 minutes of the current time. -- Decode the signature from base64. -- Perform a signature verification using the user's public key. +- Decode the signature from base64 to the raw bytes. +- Perform a signature verification using the sender instance's public key. ### Example @@ -68,7 +68,7 @@ The following example is written in TypeScript using the WebCrypto API. } ``` -Bob can be found at `https://bob.com/.versia/v0.6/entities/User/bf44e6ad-7c0a-4560-9938-cf3fd4066511`. His instance's ed25519 private key, encoded in Base64 PKCS8, is `MC4CAQAwBQYDK2VwBCIEILrNXhbWxC/MhKQDsJOAAF1FH/R+Am5G/eZKnqNum5ro`. +Bob can be found at `https://bob.com/.versia/v0.6/entities/User/bf44e6ad-7c0a-4560-9938-cf3fd4066511`. His instance's ed25519 private key, encoded in Base64 [PKCS8](https://en.wikipedia.org/wiki/PKCS_8), is `MC4CAQAwBQYDK2VwBCIEILrNXhbWxC/MhKQDsJOAAF1FH/R+Am5G/eZKnqNum5ro`. Here's how Bob would sign the request: ```typescript @@ -131,7 +131,7 @@ On Alice's side, she would verify the signature using Bob's instance's public ke const method = request.method.toLowerCase(); const path = new URL(request.url).pathname; const signature = request.headers.get("Versia-Signature"); -const timestamp = request.headers.get("Versia-Signed-At"); +const timestamp = Number(request.headers.get("Versia-Signed-At")) * 1000; // Convert to milliseconds // Check if timestamp is within 5 minutes of the current time if (Math.abs(Date.now() - timestamp) > 300_000) { @@ -160,10 +160,10 @@ if (!isVerified) { ## Exporting the Public Key -Public keys are always encoded using `base64` and must be in SPKI format. You will need to look up the appropriate method for your cryptographic library to convert the key to this format. +Public keys are always encoded using `base64` and must be in [SPKI](https://en.wikipedia.org/wiki/Simple_public-key_infrastructure) format. You will need to look up the appropriate method for your cryptographic library to convert the key to this format. - This is **not** the same as the key's raw bytes. + This is **not** merely the key's raw bytes encoded as base64. You must export the key in [SPKI](https://en.wikipedia.org/wiki/Simple_public-key_infrastructure) format, *then* encode it as base64. This is also not the commonly used "PEM" format. diff --git a/app/structures/collection/page.mdx b/app/structures/collection/page.mdx index 16172ed..e0e98ae 100644 --- a/app/structures/collection/page.mdx +++ b/app/structures/collection/page.mdx @@ -40,6 +40,7 @@ Collections are a way to represent paginated groups of entities. They are used e "type": "Note", "uri": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd", "created_at": "2024-04-09T01:38:51.743Z", + ... "collections": { "replies": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/replies", "quotes": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/quotes" diff --git a/app/structures/content-format/page.mdx b/app/structures/content-format/page.mdx index 66db689..a8b1d9d 100644 --- a/app/structures/content-format/page.mdx +++ b/app/structures/content-format/page.mdx @@ -127,7 +127,9 @@ It is a good idea to provide at least two versions of an image (if possible): on }, "thumbhash": "3OcRJYB4d3h/iIeHeEh3eIhw+j2w", "width": 1920, - "height": 1080 + "height": 1080, + "fps": null, + "duration": null } } ``` @@ -136,15 +138,39 @@ It is a good idea to provide at least two versions of an image (if possible): on { "text/plain": { "content": "The consequences of today are determined by the actions of the past. To change your future, alter your decisions today.", - "remote": false + "remote": false, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null }, "text/markdown": { "content": "> The consequences of today are determined by the actions of the past.\n> To change your future, alter your decisions today.", - "remote": false + "remote": false, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null }, "text/html": { "content": "

The consequences of today are determined by the actions of the past.

To change your future, alter your decisions today.

", - "remote": false + "remote": false, + "description": null, + "size": null, + "hash": null, + "thumbhash": null, + "width": null, + "height": null, + "fps": null, + "duration": null } } ``` diff --git a/app/types/page.mdx b/app/types/page.mdx index f0126d6..044c310 100644 --- a/app/types/page.mdx +++ b/app/types/page.mdx @@ -21,7 +21,6 @@ A **reference** is a way to refer to any entity within the Versia network. It is For example: `[2001:db8::1]:3000`. - ### Examples These two examples are equivalent if the instance is `example.com`: diff --git a/components/Libraries.tsx b/components/Libraries.tsx index 24f98e0..3f94ef7 100644 --- a/components/Libraries.tsx +++ b/components/Libraries.tsx @@ -6,8 +6,8 @@ import { Heading } from "./Heading"; const libraries = [ { - href: "https://github.com/versia-pub/api/tree/main/federation", - name: "@versia/federation", + href: "https://github.com/versia-pub/server/tree/main/packages/sdk", + name: "@versia/sdk", description: "Fully-featured federation toolkit with validation, signatures, parsing, and more.", logo: logoTypescript, diff --git a/components/Navigation.tsx b/components/Navigation.tsx index 5ef4a98..0c1e953 100644 --- a/components/Navigation.tsx +++ b/components/Navigation.tsx @@ -250,6 +250,7 @@ export const navigation: NavGroup[] = [ { title: "Introduction", href: "/introduction" }, { title: "SDKs", href: "/sdks" }, { title: "Entities", href: "/entities" }, + { title: "JSON", href: "/json" }, { title: "Signatures", href: "/signatures" }, { title: "Security", href: "/security" }, { title: "Federation", href: "/federation" }, @@ -321,7 +322,6 @@ export const navigation: NavGroup[] = [ { title: "Reports", href: "/extensions/reports" }, { title: "Share", href: "/extensions/share" }, { title: "Vanity", href: "/extensions/vanity" }, - { title: "WebSockets", href: "/extensions/websockets" }, ], }, ];