mirror of
https://github.com/versia-pub/docs.git
synced 2026-03-13 02:49:16 +01:00
refactor: 📝 Update all extension to remove now-useless fields
This commit is contained in:
parent
51c53824ad
commit
d886b83e62
27 changed files with 166 additions and 410 deletions
|
|
@ -18,7 +18,7 @@ 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`**: URI of the user who signed the request, [or the string `instance $1`, to represent the instance, where `$1` is the instance's host](/entities/instance-metadata#the-null-author).
|
||||
- **`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.
|
||||
|
||||
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:
|
||||
|
|
@ -61,14 +61,14 @@ To verify a signature, the instance must:
|
|||
|
||||
The following example is written in TypeScript using the WebCrypto API.
|
||||
|
||||
`@bob`, from `bob.com`, wants to sign a request to `alice.com`. The request is a `POST` to `/notes`, with the following body:
|
||||
`@bob`, from `bob.com`, wants to sign a request to `alice.com`. The request is a `POST` to `/.versia/v0.6/inbox`, with the following body:
|
||||
```json
|
||||
{
|
||||
"content": "Hello, world!"
|
||||
}
|
||||
```
|
||||
|
||||
Bob can be found at `https://bob.com/users/bf44e6ad-7c0a-4560-9938-cf3fd4066511`. His 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, is `MC4CAQAwBQYDK2VwBCIEILrNXhbWxC/MhKQDsJOAAF1FH/R+Am5G/eZKnqNum5ro`.
|
||||
|
||||
Here's how Bob would sign the request:
|
||||
```typescript
|
||||
|
|
@ -97,7 +97,7 @@ const digest = await crypto.subtle.digest(
|
|||
);
|
||||
|
||||
const stringToSign =
|
||||
`post /notes ${timestamp} ${Buffer.from(digest).toString("base64")}`;
|
||||
`post /.versia/v0.6/inbox ${timestamp} ${Buffer.from(digest).toString("base64")}`;
|
||||
|
||||
const signature = await crypto.subtle.sign(
|
||||
"Ed25519",
|
||||
|
|
@ -113,19 +113,19 @@ To send the request, Bob would use the following code:
|
|||
```typescript
|
||||
const headers = new Headers();
|
||||
|
||||
headers.set("Versia-Signed-By", "https://bob.com/users/bf44e6ad-7c0a-4560-9938-cf3fd4066511");
|
||||
headers.set("Versia-Signed-By", "bob.com");
|
||||
headers.set("Versia-Signed-At", timestamp);
|
||||
headers.set("Versia-Signature", base64Signature);
|
||||
headers.set("Content-Type", "application/json");
|
||||
|
||||
const response = await fetch("https://alice.com/notes", {
|
||||
const response = await fetch("https://alice.com/.versia/v0.6/inbox", {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: content,
|
||||
});
|
||||
```
|
||||
|
||||
On Alice's side, she would verify the signature using Bob's public key. Here, we assume that Alice has Bob's public key stored in a variable called `publicKey` (during real federation, this would be fetched from Bob's profile).
|
||||
On Alice's side, she would verify the signature using Bob's instance's public key. Here, we assume that Alice has Bob's instance's public key stored in a variable called `publicKey` (during real federation, this would be fetched from the instance's [metadata endpoint](/api/endpoints#instance-metadata)).
|
||||
|
||||
```typescript
|
||||
const method = request.method.toLowerCase();
|
||||
|
|
@ -165,7 +165,7 @@ Public keys are always encoded using `base64` and must be in SPKI format. You wi
|
|||
<Note>
|
||||
This is **not** the same as the key's raw bytes.
|
||||
|
||||
This is also not related to the commonly used "PEM" format.
|
||||
This is also not the commonly used "PEM" format.
|
||||
</Note>
|
||||
|
||||
```typescript {{ title: "Example using TypeScript and the WebCrypto API" }}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue