refactor: 📝 Update all extension to remove now-useless fields

This commit is contained in:
Jesse Wierzbinski 2025-05-05 14:08:20 +02:00
parent 51c53824ad
commit d886b83e62
No known key found for this signature in database
27 changed files with 166 additions and 410 deletions

View file

@ -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" }}