versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2025-12-06 06:18:19 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

fix: ✏️ Edit text for better consistency

Browse source
This commit is contained in:
Jesse Wierzbinski 2024-08-18 00:59:39 +02:00
parent 94f437f539
commit 1f864b89c8
No known key found for this signature in database
7 changed files with 14 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
app/entities/instance-metadata/page.mdx
View file

@ -1,16 +1,12 @@
export const metadata = { export const metadata = {
title: 'Server Metadata', title: 'Instance Metadata',
description: 'Metadata about a Versia instance, such as capabilities and endpoints.', description: 'Metadata about a Versia instance, such as capabilities and endpoints.',
} }
# Server Metadata # Instance Metadata
Contains metadata about a Versia instance, such as capabilities and endpoints. {{ className: 'lead' }} Contains metadata about a Versia instance, such as capabilities and endpoints. {{ className: 'lead' }}
<Note>
This entity is only used as part of [Server Discovery](/federation/discovery#server-discovery), and not as part of federation.
</Note>
## The `null` Author ## The `null` Author
On all entities that have an `author` field, the `author` can be `null` to represent the instance itself as the author (like ActivityPub's Server Actors). In this case, the instance's public key should be used to verify the entity. On all entities that have an `author` field, the `author` can be `null` to represent the instance itself as the author (like ActivityPub's Server Actors). In this case, the instance's public key should be used to verify the entity.

4
app/entities/note/page.mdx
View file

@ -64,7 +64,7 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
URIs of [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. URIs of [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.
</Property> </Property>
<Property name="previews" type="LinkPreview" required={false}> <Property name="previews" type="LinkPreview" required={false}>
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 server that sees the publication, creating an accidental DDOS attack. 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 ```typescript
type LinkPreview = { type LinkPreview = {
@ -77,7 +77,7 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
``` ```
<Note> <Note>
Servers should make sure not to trust the previews, as they could be faked by malicious remote servers. This is not a very good attack vector, but it is still possible to redirect users to malicious links. Implementations should make sure not to trust the previews, as they could be faked by malicious remote instances. This is not a very good attack vector, but it is still possible to redirect users to malicious links.
</Note> </Note>
</Property> </Property>
<Property name="quotes" type="URI" required={false} typeLink="/types#uri"> <Property name="quotes" type="URI" required={false} typeLink="/types#uri">

2
app/entities/user/page.mdx
View file

@ -94,7 +94,7 @@ Instance **must** be the host of the instance the user is on (hostname with opti
<Property name="inbox" type="URI" required={true} typeLink="/types#uri"> <Property name="inbox" type="URI" required={true} typeLink="/types#uri">
The user's federation inbox. Refer to the [federation documentation](/federation). The user's federation inbox. Refer to the [federation documentation](/federation).
Some instances may also have a shared inbox. Refer to [Server Metadata](/entities/instance-metadata) for more information. Some instances may also have a shared inbox. Refer to [Instance Metadata](/entities/instance-metadata) for more information.
</Property> </Property>
<Property name="collections" type="UserCollections" required={true}> <Property name="collections" type="UserCollections" required={true}>
Collections related to the user. Must contain at least `outbox`, `followers`, `following`, and `featured`. Collections related to the user. Must contain at least `outbox`, `followers`, `following`, and `featured`.

6
app/federation/discovery/page.mdx
View file

@ -47,13 +47,13 @@ Accept: application/jrd+json
} }
``` ```
## Server Discovery ## Instance Discovery
Server metadata can be accessed by making a `GET` request to the server's Versia metadata endpoint, which is located at `/.well-known/versia`. Instaance metadata can be accessed by making a `GET` request to the instance's Versia metadata endpoint, which is located at `/.well-known/versia`.
### Example ### Example
To discover the metadata of the server `versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/versia`. To discover the metadata of the instance `versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/versia`.
This endpoint will return an [InstanceMetadata](/entities/instance-metadata) entity. This endpoint will return an [InstanceMetadata](/entities/instance-metadata) entity.

2
app/federation/validation/page.mdx
View file

@ -6,7 +6,7 @@ export const metadata = {
# Validation # 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 server **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 `400 Bad Request` HTTP status code.
<Note> <Note>
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. 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.

2
app/page.tsx
View file

@ -50,7 +50,7 @@ const Page: FC = () => {
{ {
name: "In-depth security docs", name: "In-depth security docs",
description: description:
"Docs provide lots of information on how to program a secure server.", "Docs provide lots of information on how to program a secure instance.",
icon: "tabler:shield", icon: "tabler:shield",
}, },
{ {

8
app/signatures/page.mdx
View file

@ -1,7 +1,7 @@
export const metadata = { export const metadata = {
title: 'Signatures', title: 'Signatures',
description: description:
'Learn how signatures work, and how to implement them in your Versia server.', 'Learn how signatures work, and how to implement them in your Versia instance.',
} }
# Signatures # Signatures
@ -9,7 +9,7 @@ export const metadata = {
Versia uses cryptographic signatures to ensure the integrity and authenticity of data. Signatures are used to verify that the data has not been tampered with and that it was created by the expected user. {{ className: 'lead' }} Versia uses cryptographic signatures to ensure the integrity and authenticity of data. Signatures are used to verify that the data has not been tampered with and that it was created by the expected user. {{ className: 'lead' }}
<Note> <Note>
This part is very important! If signatures are implemented incorrectly in your server, **you will not be able to federate**. This part is very important! If signatures are implemented incorrectly in your instance, **you will not be able to federate**.
Mistakes made in this section can lead to **security vulnerabilities** and **impersonation attacks**. Mistakes made in this section can lead to **security vulnerabilities** and **impersonation attacks**.
</Note> </Note>
@ -25,7 +25,7 @@ Signatures are **required on ALL federation traffic**. If a request does not hav
- **All POST requests**. - **All POST 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`. - **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`.
If a signature fails, is missing or is invalid, the server **MUST** return a `401 Unauthorized` HTTP status code. If a signature fails, is missing or is invalid, the instance **MUST** return a `401 Unauthorized` HTTP status code.
### Calculating the Signature ### Calculating the Signature
@ -49,7 +49,7 @@ post /notes a2ebc29eb6762a9164fbcffc9271e8a53562a5e725e7187ea7d88d03cbe59341 n4b
### Verifying the Signature ### Verifying the Signature
To verify a signature, the server must: To verify a signature, the instance must:
- Recreate the string as described above. - Recreate the string as described above.
- Extract the signature provided in the `X-Signature` header. - Extract the signature provided in the `X-Signature` header.
- Decode the signature from base64. - Decode the signature from base64.