mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
Rewrite more parts for Lysand 1.1
This commit is contained in:
Jesse Wierzbinski
parent
bbc826434c
commit
fee03886e8
|
|
@ -139,3 +139,13 @@ The only addition to the Reaction object is the `extensions` field, which contai
|
|||
When rendering the Reaction object, clients **MUST** replace the `:emoji_name:` with the appropriate emoji. If the client does not support custom emojis, it **MUST** display the `:emoji_name:` as-is.
|
||||
|
||||
This emoji must be rendered according to the rules of the [Custom Emojis](./custom-emojis) extension.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Reaction extends Extension {
|
||||
extension_type: "org.lysand:reactions/Reaction";
|
||||
object: string;
|
||||
content: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,12 +1,12 @@
|
|||
# Reports
|
||||
|
||||
The Reports extension allows users to report objects to their server. This is useful for reporting content that violates the server's rules to admin. (also called "flagging")
|
||||
The Reports extension enables users to flag content or users that violate the server's rules. This feature is important for maintaining a safe community environment.
|
||||
|
||||
If the reporter and reportee are on the same server, there is no need for federation and reporting can happen directly. If the reporter and reportee are on different servers, the report **MUST** be federated to the reportee's server.
|
||||
If the reporting user (reporter) and the reported user (reportee) are on the same server, the report can be handled directly without the need for federation. However, if the reporter and reportee are on different servers, the report **MUST** be federated to the reportee's server.
|
||||
|
||||
## Report Object
|
||||
|
||||
The report object is an object that contains information about the report. It is formatted as follows:
|
||||
The report object encapsulates the details of the report. It is structured as follows:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
|
@ -30,18 +30,41 @@ Report events **MUST** be sent to the server actor's inbox.
|
|||
|
||||
### Objects
|
||||
|
||||
The `objects` field is an array that contains a list of the URIs of the objects that are being reported. This field is required on all Report objects.
|
||||
| Name | Type | Required |
|
||||
| :------ | :-------------- | :------- |
|
||||
| objects | Array of String | Yes |
|
||||
|
||||
If `objects` contains Actors, then these Actors **MUST** be treated as the reported actors.
|
||||
URIs of the objects that are being reported.
|
||||
|
||||
If `objects` contains Publications, then these Publications **MUST** be treated as the reported objects.
|
||||
If `objects` contains Actors, then these Actors **MUST** be treated as the reported users.
|
||||
|
||||
`objects` can contain any URI to any kind of objects, however typically only Actors or Publications should be reportable
|
||||
If `objects` contains Notes, then these Notes **MUST** be treated as the reported content.
|
||||
|
||||
`objects` can contain any URI to any kind of objects, however, typically only Actors or Notes should be reportable.
|
||||
|
||||
### Reason
|
||||
|
||||
The `reason` field is a string that represents the reason for the report. This field is required on all Report objects. This is meant to be a short summary of the report, such as `"spam"`, `"hate speech"`, `"tos violation"` or such.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| reason | String | Yes |
|
||||
|
||||
The reason for the report. This should be a concise summary of the report, such as `"spam"`, `"hate speech"`, `"tos violation"`, etc.
|
||||
|
||||
### Comment
|
||||
|
||||
The `comment` field is a string that represents the comment of the report. This field is not required on a Report object. This is meant to be a longer description of the report, such as `"This user has been spamming my inbox with advertisements."`.
|
||||
| Name | Type | Required |
|
||||
| :------ | :----- | :------- |
|
||||
| comment | String | No |
|
||||
|
||||
Additional comments about the report. This is meant to provide a more detailed description of the report, such as `"This user has been spamming my inbox with advertisements."`.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Report extends Extension {
|
||||
extension_type: "org.lysand:reports/Report";
|
||||
objects: string[];
|
||||
reason: string;
|
||||
comment?: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,37 +1,45 @@
|
|||
# Server Endorsement
|
||||
|
||||
The Server Endorsement extension allows servers to endorse other servers. This is useful as an alternative to open-air federation, where servers can endorse other servers that they trust. Only endorsed servers and the servers endorsed by those (up to a configurable depth) will be federated with.
|
||||
The Server Endorsement extension provides a mechanism for servers to vouch for the credibility of other servers. This is a valuable alternative to unrestricted federation, enabling servers to endorse those they deem trustworthy. Federation will only occur with endorsed servers and their subsequent endorsements, up to an admin-defined depth.
|
||||
|
||||
## Endorsement Object
|
||||
## Endorsement Entity
|
||||
|
||||
The endorsement object is an object that contains information about the endorsement. It is formatted as follows:
|
||||
The endorsement entity encapsulates the details of an endorsement. It adheres to the following structure:
|
||||
|
||||
```json5
|
||||
{
|
||||
"type": "Extension",
|
||||
"extension_type": "org.lysand:server_endorsement/Endorsement",
|
||||
"author": "https://example.com/actor", // Should be the server actor
|
||||
"author": "https://example.com/actor", // The endorsing server's actor
|
||||
"id": "ed480922-b095-4f09-9da5-c995be8f5960",
|
||||
"uri": "https://example.com/actions/ed480922-b095-4f09-9da5-c995be8f5960",
|
||||
"server": "https://example.com",
|
||||
}
|
||||
```
|
||||
|
||||
The `server` field is a string that represents the URI of the server that is being endorsed. This URI **MUST** be the URI of the server's root endpoint. For example, `https://example.com`.
|
||||
Endorsement entities **MUST** be dispatched to the endorsing server actor's inbox whenever the server administrators create a new endorsement.
|
||||
|
||||
This URI **MUST** be HTTPS and **MUST NOT** be an IP address.
|
||||
### Server
|
||||
|
||||
The `server` field is required on all Endorsement objects.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| server | String | Yes |
|
||||
|
||||
Endorsement objects **MUST** be sent to the server actor's inbox, whenever a new endorsement is made by the server admins.
|
||||
URI of the endorsed server. This URI **MUST** correspond to the server's root endpoint, such as `https://example.com`.
|
||||
|
||||
This URI **MUST NOT** be an IP address, except for development purposes.
|
||||
|
||||
### Author
|
||||
|
||||
The `author` field **MUST** be the server actor. This field is required so that servers can cryptographically sign the endorsement with the server actor's `public_key`.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
The `author` field **MUST** represent the endorsing server actor. This requirement ensures that endorsements can be cryptographically signed using the server actor's `public_key`.
|
||||
|
||||
## Endorsement Collection
|
||||
|
||||
The URI to the endorsement collection may be specified inside the server's metadata, inside `extensions`:
|
||||
The URI for the endorsement collection can be specified within the server's metadata, under `extensions`:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
|
@ -45,16 +53,26 @@ The URI to the endorsement collection may be specified inside the server's metad
|
|||
}
|
||||
```
|
||||
|
||||
This should return a `Collection` object that contains a list of `Endorsement` objects.
|
||||
This should return a [Collection](../structures/collection) of `Endorsement` entities.
|
||||
|
||||
## Behaviour Of Endorsements
|
||||
## Endorsement Protocol Behavior
|
||||
|
||||
When a server receives an endorsement, it **MUST** verify the signature of the endorsement. If the signature is invalid, the server **MUST** discard the endorsement. This goes the same for fetching the endorsement collection.
|
||||
Upon receiving an endorsement, a server **MUST** validate the endorsement's signature. If the signature is invalid, the server **MUST** disregard the endorsement. This also applies when fetching the endorsement collection.
|
||||
|
||||
It is up to the server to decide what it does with the endorsement: Endorsements are designed to apply as a flexible whitelist for servers, with the admins choosing a couple of trusted servers when setting up for the first time and then adding more as they go.
|
||||
The server has the discretion to decide how to handle the endorsement. Endorsements are intended to serve as a dynamic whitelist for servers, with administrators initially selecting a few trusted servers and progressively adding more.
|
||||
|
||||
Servers **SHOULD** show the endorsements that they have received to their admins, and allow them to accept or reject the endorsement. Ultimately, it is up to the admins to decide what to do with the endorsement.
|
||||
Servers **SHOULD** display received endorsements to their administrators, allowing them to accept or reject the endorsement. Ultimately, the decision on how to handle the endorsement lies with the administrators.
|
||||
|
||||
Endorsements should be treated as a guarantee of trust: If a server endorses another server, it is saying that it trusts that server. Servers should not endorse servers that they do not trust.
|
||||
Endorsements should be viewed as a seal of trust: If a server endorses another, it is expressing its trust in that server. Servers should refrain from endorsing servers they do not trust.
|
||||
|
||||
Finally, servers **can** check the endorsed servers of the servers that they have endorsed, up to a configurable depth. This is to create a chain of trust, where servers can endorse servers that they trust, and servers that they trust can endorse servers that they trust, and so on.
|
||||
Lastly, servers **MAY** verify the endorsements of the servers they have endorsed, up to a user-defined depth. This creates a trust chain, where servers endorse those they trust, and those servers, in turn, endorse servers they trust, and so forth.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Endorsement extends Extension {
|
||||
extension_type: "org.lysand:server_endorsement/Endorsement";
|
||||
author: string;
|
||||
server: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Vanity
|
||||
|
||||
This extension is currently in development.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Federation
|
||||
|
||||
This section elucidates how federation operates within Lysand.
|
||||
This section explains how federation operates within Lysand.
|
||||
|
||||
Lysand's federation is built upon the HTTP stack. Servers interact with each other by exchanging HTTP requests.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# User Discovery
|
||||
|
||||
> **Note:** The terms "the server" and "the requesting server" are used in this section. "The server" refers to the server that is being discovered, and "the requesting server" refers to the server that is trying to discover the server.
|
||||
> [!NOTE]
|
||||
> The terms "the server" and "the requesting server" are used in this section. "The server" refers to the server that is being discovered, and "the requesting server" refers to the server that is trying to discover the server.
|
||||
|
||||
Servers **MUST** implement the [WebFinger](https://tools.ietf.org/html/rfc7033) protocol to allow other servers to discover their endpoints. This is done by serving a `host-meta` file at the address `/.well-known/host-meta`.
|
||||
|
||||
|
|
@ -23,7 +24,7 @@ Breaking down this URI, we get the following:
|
|||
- `uuid`: The UUID of the user that the server is trying to discover.
|
||||
- `example.com`: The domain of the server that the user is on. This is usually the domain of the server. This can also be a subdomain of the server, such as `lysand.example.com`.
|
||||
|
||||
This format is reminiscent of the `acct` format used by ActivityPub, but with a UUID instead of a username. Users should typically not use the `id` of an actor to identify it, but instead its `username`.
|
||||
This format is reminiscent of the `acct` format used by ActivityPub, but with a UUID instead of a username. Users will typically not use the `id` of an actor to identify it, but instead its `username`: servers **MUST** only use the `id` to identify actors.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -68,8 +69,10 @@ The server **MUST** respond with a `200 OK` response code, and a JSON object in
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** The `subject` field **MUST** be the same as the `resource` field in the request.
|
||||
> [!NOTE]
|
||||
> The `subject` field **MUST** be the same as the `resource` field in the request.
|
||||
|
||||
> **Note:** The server implementation is free to add any additional links to the `links` array, such as for compatibility with other federation protocols. However, the links specified above **MUST** be included.
|
||||
|
||||
>The `href` values of these links can be anything as long as it includes the `uuid` of the user, such as `https://example.com/accounts/uuid` or `https://example.com/uuid.`.
|
||||
> [!NOTE]
|
||||
> The server implementation is free to add any additional links to the `links` array, such as for compatibility with other federation protocols. However, the links specified above **MUST** be included.
|
||||
>
|
||||
> The `href` values of these links can be anything as long as it includes the `uuid` of the user, such as `https://example.com/accounts/uuid` or `https://example.com/uuid.`.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,11 @@
|
|||
# Actions
|
||||
# User Interactions
|
||||
|
||||
Actions are the main way that clients interact with the Lysand protocol. They are JSON objects that represent an action that a user wants to perform, such as posting a new object or following a user.
|
||||
User interactions in the Lysand protocol are primarily facilitated through Actions. These are JSON objects that encapsulate a user's intended operation, such as favouriting an object or initiating a follow request to another user.
|
||||
|
||||
Actions are a broad category encompassing various types of objects, rather than being a specific object type.
|
||||
|
||||
Here's an example of an Action:
|
||||
|
||||
Here is an example action:
|
||||
```json5
|
||||
{
|
||||
"type": "Like",
|
||||
|
|
@ -14,25 +17,27 @@ Here is an example action:
|
|||
}
|
||||
```
|
||||
|
||||
## Type
|
||||
## Action Types
|
||||
|
||||
Currently available types are:
|
||||
- [`Like`](/objects/like)
|
||||
- [`Dislike`](/objects/dislike)
|
||||
- [`Follow`](/objects/follow)
|
||||
- [`FollowAccept`](/objects/follow-accept)
|
||||
- [`FollowReject`](/objects/follow-reject)
|
||||
- [`Announce`](/objects/announce)
|
||||
- [`Undo`](/objects/undo)
|
||||
The currently supported action types include:
|
||||
- [`Like`](./like)
|
||||
- [`Dislike`](./dislike)
|
||||
- [`Follow`](./follow)
|
||||
- [`FollowAccept`](./follow-accept)
|
||||
- [`FollowReject`](./follow-reject)
|
||||
- [`Announce`](./announce)
|
||||
- [`Undo`](./undo)
|
||||
|
||||
Notably, a `Block` action is not included in the Lysand protocol. This is because Lysand does not have a concept of blocking users. Instead, it is up to the client or server to decide if it wants to display content from a user or not.
|
||||
Notably, the Lysand protocol does not include a `Block` action. This is because Lysand does not inherently support the concept of blocking users. Instead, the decision to display or hide content from a particular user should be done server-side.
|
||||
|
||||
This serves to prevent abuse of the protocol to find out if a user has blocked another user, which is a privacy concern.
|
||||
This approach helps prevent potential misuse of the protocol to determine if a user has been blocked by another, thereby addressing a significant privacy concern.
|
||||
|
||||
## Fields
|
||||
## Fielkds
|
||||
|
||||
### Author
|
||||
|
||||
The `author` field on an Action is a string that represents the URI of the user that created the action. It is used to identify the author of the action.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
The `author` field is required on all actions.
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
|
@ -1,10 +1,11 @@
|
|||
### 1.6.2. Actors
|
||||
# Actors
|
||||
|
||||
Actors are the main users of the Lysand protocol. They are JSON objects that represent a user. They are similar to ActivityPub's `Actor` objects.
|
||||
Actors are the primary users of the Lysand protocol. They are JSON objects that symbolize a user, akin to ActivityPub's `Actor` objects.
|
||||
|
||||
Actors **MUST** be referred to by their `id` internally and across the protocol. The `username` property MUST be treated as a changeable display name, and **MUST NOT** be used to identify the actor.
|
||||
Actors encompass two distinct object types currently, namely [Users](./user) and [Server Actors](../federation/server-actor).
|
||||
|
||||
Here is a sample Actor:
|
||||
|
||||
Here is an example actor:
|
||||
```json5
|
||||
{
|
||||
"type": "User",
|
||||
|
|
@ -13,57 +14,27 @@ Here is an example actor:
|
|||
"created_at": "2021-01-01T00:00:00.000Z",
|
||||
"display_name": "Gordon Ramsay",
|
||||
"username": "gordonramsay",
|
||||
"avatar": [
|
||||
{
|
||||
"avatar": {
|
||||
"image/png": {
|
||||
"content": "https://cdn.test.com/avatars/ab5081cf-b11f-408f-92c2-7c246f290593.png",
|
||||
"content_type": "image/png"
|
||||
},
|
||||
{
|
||||
"content": "https://cdn.test.com/avatars/ab5081cf-b11f-408f-92c2-7c246f290593.webp",
|
||||
"content_type": "image/webp"
|
||||
}
|
||||
],
|
||||
"header": [
|
||||
{
|
||||
},
|
||||
"header": {
|
||||
"image/png": {
|
||||
"content": "https://cdn.test.com/banners/ab5081cf-b11f-408f-92c2-7c246f290593.png",
|
||||
"content_type": "image/png"
|
||||
},
|
||||
{
|
||||
"content": "https://cdn.test.com/banners/ab5081cf-b11f-408f-92c2-7c246f290593.webp",
|
||||
"content_type": "image/webp"
|
||||
}
|
||||
],
|
||||
},
|
||||
"indexable": true,
|
||||
"public_key": {
|
||||
"public_key": "...",
|
||||
"actor": "https://test.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
|
||||
},
|
||||
"bio": [
|
||||
{
|
||||
"content": "My name is Gordon Ramsay, I'm a silly quirky little pony that LOVES to roleplay in the bedroom!",
|
||||
"content_type": "text/plain"
|
||||
"bio": {
|
||||
"text/plain": {
|
||||
"content": "Hello!",
|
||||
},
|
||||
{
|
||||
"content": "My name is <b>Gordon Ramsay</b>, I'm a silly quirky little pony that <i>LOVES</i> to roleplay in the bedroom!",
|
||||
"content_type": "text/html"
|
||||
}
|
||||
],
|
||||
"fields": [
|
||||
{
|
||||
"key": [
|
||||
{
|
||||
"content": "Where I live",
|
||||
"content_type": "text/plain"
|
||||
}
|
||||
],
|
||||
"value": [
|
||||
{
|
||||
"content": "Portland, Oregon",
|
||||
"content_type": "text/plain"
|
||||
}
|
||||
],
|
||||
}
|
||||
],
|
||||
},
|
||||
"fields": [],
|
||||
"featured": "https://test.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7/featured",
|
||||
"followers": "https://test.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7/followers",
|
||||
"following": "https://test.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7/following",
|
||||
|
|
@ -74,4 +45,4 @@ Here is an example actor:
|
|||
}
|
||||
```
|
||||
|
||||
As there is only one type of `Actor`, the `User`, please see [`User`](/objects/user) for more information.
|
||||
For detailed information on their structure, please refer to the respective documentation for [User](./user) and [Server Actor](../federation/server-actor).
|
||||
|
|
@ -265,4 +265,37 @@ Please refer to [Outbox](../federation/endpoints) for more information.
|
|||
|
||||
These extensions might add or affect the User object if used:
|
||||
- [Custom Emojis](../extensions/custom-emojis)
|
||||
- [Vanity Profile](../extensions/vanity)
|
||||
- [Vanity Profile](../extensions/vanity)
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface User extends Entity {
|
||||
type: "User";
|
||||
id: string;
|
||||
uri: string;
|
||||
created_at: string;
|
||||
display_name?: string;
|
||||
username: string;
|
||||
avatar?: ContentFormat;
|
||||
header?: ContentFormat;
|
||||
indexable: boolean;
|
||||
public_key: ActorPublicKeyData;
|
||||
bio?: ContentFormat;
|
||||
fields?: Field[];
|
||||
featured: string;
|
||||
followers: string;
|
||||
following: string;
|
||||
likes: string;
|
||||
dislikes: string;
|
||||
inbox: string;
|
||||
outbox: string;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
interface Field {
|
||||
key: ContentFormat;
|
||||
value: ContentFormat;
|
||||
}
|
||||
```
|
||||
Loading…
Reference in a new issue