如何实现基本的 Activity Pub 服务器

January 4, 2024

这篇文章主要参考了 https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/
它发表在 mastodon 的官方博客上，代码通过 ruby 示例。下面我仅使用标准的 Web API，以及少量 Deno 代码举例。

生成密钥对

Activity Pub 通过密钥机制（WebFinger）保证数据不被篡改，因此我们首先需要准备密钥对（公钥和私钥）
我们要通过 Web Crypto API 生成 RSA 密钥对，并保存（导出）为 .pem 格式的文本文件

仅使用 Web Crypto API，无需直接使用 openssl 命令行！

// 生成 RSA 密钥对
async function generateRSAKeyPair() {
    const keyPair = await crypto.subtle.generateKey(
        {
            name: "RSASSA-PKCS1-v1_5",
            modulusLength: 2048,
            publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
            hash: { name: "SHA-256" },
        },
        true,
        ["sign", "verify"],
    );

    return keyPair;
}

// 导出私钥为 PEM 格式
async function exportPrivateKey(key: CryptoKey) {
    const exportedKey = await crypto.subtle.exportKey("pkcs8", key);
    const exportedPem = arrayBufferToPem(exportedKey, "PRIVATE KEY");
    return exportedPem;
}

// 导出公钥为 PEM 格式
async function exportPublicKey(key: CryptoKey) {
    const exportedKey = await crypto.subtle.exportKey("spki", key);
    const exportedPem = arrayBufferToPem(exportedKey, "PUBLIC KEY");
    return exportedPem;
}

// 将 ArrayBuffer 转换为 PEM 格式
function arrayBufferToPem(buffer: ArrayBuffer, label: "PRIVATE KEY" | "PUBLIC KEY") {
    const pemHeader = `-----BEGIN ${label}-----`;
    const pemFooter = `-----END ${label}-----`;

    const binary = String.fromCharCode.apply(null, new Uint8Array(buffer) as any as number[]);
    const base64 = btoa(binary);

    let pem = pemHeader + "\n";
    let offset = 0;

    while (offset < base64.length) {
        const line = base64.substr(offset, 64);
        pem += line + "\n";
        offset += 64;
    }
    pem += pemFooter + "\n";
    return pem;
}

// 生成 RSA 密钥对
const keyPair = await generateRSAKeyPair();

// 导出私钥和公钥
const privateKeyPem: string = await exportPrivateKey(keyPair.privateKey);
const publicKeyPemL: string = await exportPublicKey(keyPair.publicKey);

// 写入文件（这里使用 Deno，nodejs 同理）
Deno.writeTextFileSync("private.pem", privateKeyPem);
Deno.writeTextFileSync("public.pem", publicKeyPem);

现在我们得到了 private.pem 和 public.pem 两个文本文件

注：等效 openssl 命令

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

在公网上暴露我们的服务器

我们需要实现 Webfinger，将公钥暴露在公网，以便其它服务器获取

其它服务器会 GET 请求例如 /.well-known/webfinger?resource=acct:bob@my-example.com
来查询我们的服务器是否存在指定的 resource（这里则是查询我们的服务器是否存在指定用户）

我们简单地返回下面的 JSON（注意，下文演示中的 my-example.com 都需要修改为真实的公网 URL）

其中 https://my-example.com/actor 是公钥将要存在的 url

json

{
    "subject": "acct:alice@my-example.com",

    "links": [
        {
            "rel": "self",
            "type": "application/activity+json",
            "href": "https://my-example.com/actor"
        }
    ]
}

下面使用 Deno 简单实现

import { ServeRouter } from "https://denopkg.com/yieldray/serve-router@master/src/index.ts";

const app = ServeRouter();

app.all("/.well-known/webfinger", (req: Request) => {
    const url = new URL(req.url);

    return Response.json(
        {
            subject: url.searchParams.get("resource"),
            links: [
                {
                    rel: "self",
                    type: "application/activity+json",
                    href: `${url.origin}/actor`,
                },
            ],
        },
        {
            headers: { "Content-Type": "application/jrd+json" },
        },
    );
});

之后，其它的服务器还会通过查询 https://my-example.com/actor 来获取这个用户的公钥（我们的服务器只有我们一个人）

我们返回如下 JSON（publicKeyPem 就是我们之前生成的 public.pem 文件的内容）

json

{
    "@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/v1"],

    "id": "https://my-example.com/actor",
    "type": "Person",
    "preferredUsername": "alice",
    "inbox": "https://my-example.com/inbox",

    "publicKey": {
        "id": "https://my-example.com/actor#main-key",
        "owner": "https://my-example.com/actor",
        "publicKeyPem": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
    }
}

/**
 * 公钥 pem 文件内容如下：
 * -----BEGIN PUBLIC KEY-----
 * xxxx
 * -----END PUBLIC KEY-----
 */
const publicKeyPem = Deno.readTextFileSync("./public.pem");

app.all("/actor", (req: Request) => {
    // 我们还可以仅当请求明确指明需要返回 json 时，才返回，例如如下请求头：
    // accept: application/activity+json, application/ld+json
    // 换言之，当我们请求其它服务器时，也应当加上上述请求头
    const url = new URL(req.url);

    return Response.json(
        {
            "@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/v1"],

            id: `${url.origin}/actor`,
            type: "Person",
            preferredUsername: "alice",
            inbox: `${url.origin}/inbox`,

            publicKey: {
                id: `${url.origin}/actor#main-key`,
                owner: `${url.origin}/actor`,
                publicKeyPem,
            },
        },
        {
            headers: { "Content-Type": "application/jrd+json" },
        },
    );
});

顺便简单地实现我们的收件箱（inbox）
这里只是简单地打印出请求的 JSON，返回值我们不去处理

app.post("/inbox", async (req: Request) => {
    console.log(JSON.stringify(await req.json(), null, 4));

    return new Response(`I'm inbox!`);
});

发出我们的第一个请求

现在我们想要关注（Follow）Mastodon 的官方账号

我们向 https://mastodon.social/inbox POST 请求发送如下 JSON

json

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "https://my-example.com/my-first-follow",
    "type": "Follow",
    "actor": "https://my-example.com/actor",
    "object": "https://mastodon.social/users/Mastodon"
}

不过在发送之前，我们需要对请求头签名，确保是由 https://my-example.com/actor 代表的用户（也就是我们）发出的请求（通过 Signature: 请求头）

RFC 9421 HTTP Signatures

Signature: keyId="https://my-example.com/actor#main-key",headers="(request-target) host date",signature="..."

需要签名的请求头内容如下：（注意 (request-target) 请求头并不会实际发送，因为它相当于 HTTP 请求的第一行，在此仅作签名需要）
（post 是小写而不是大写，date 必须是当前 UTC 时间，只允许 30 秒上下的时间误差，否则视签名无效）

(request-target): post /inbox
host: mastodon.social
date: Sun, 06 Nov 1994 08:49:37 GMT

但注意，对于 POST 请求，mastodon 还要求发送 Digest: 请求头，值是请求体的 RSA-SHA256 摘要（digest）参见此处

首先构造一些辅助函数，用于导入密钥和 base64 编码（对于 Digest: 请求头）

// 导入私钥
async function importPrivateKey(pem: string) {
    const pemHeader = "-----BEGIN PRIVATE KEY-----";
    const pemFooter = "-----END PRIVATE KEY-----";

    const pemContents = pem.replace(pemHeader, "").replace(pemFooter, "").replace(/\s/g, "");

    const binaryString = atob(pemContents);
    const binaryBuffer = new Uint8Array(binaryString.length);

    for (let i = 0; i < binaryString.length; i++) {
        binaryBuffer[i] = binaryString.charCodeAt(i);
    }

    const privateKey = await crypto.subtle.importKey(
        "pkcs8",
        binaryBuffer,
        {
            name: "RSASSA-PKCS1-v1_5",
            hash: "SHA-256",
        },
        true,
        ["sign"],
    );

    return privateKey;
}

// 使用密钥对一段文本签名
function signText(key: CryptoKey, text: string) {
    return crypto.subtle.sign(
        {
            name: "RSASSA-PKCS1-v1_5",
            hash: { name: "SHA-256" },
        },
        key,
        new TextEncoder().encode(text),
    );
}

// 编码为 base64 字符串
function encodeBase64(buf: ArrayBufferLike): string {
    let binary = "";
    const bytes = new Uint8Array(buf);
    for (let i = 0; i < bytes.length; i++) {
        binary += String.fromCharCode(bytes[i]);
    }
    return btoa(binary);
}

终于可以发出第一个请求了

// 读取私钥文件
const privateKeyPem = Deno.readTextFileSync("./private.pem");
const privateKey = await importPrivateKey(privateKeyPem);

// 修改为公网域名
const origin = "https://my-example.com";

// 请求体
const requestBody = JSON.stringify({
    "@context": "https://www.w3.org/ns/activitystreams",
    id: `${origin}/my-first-follow`,
    type: "Follow",
    actor: `${origin}/actor`,
    object: "https://mastodon.social/users/Mastodon",
});

const date = new Date().toUTCString();
const digest = "sha-256=" + encodeBase64(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(requestBody)));

const signedString = encodeBase64(
    await signText(
        privateKey,
        `(request-target): post /inbox
host: mastodon.social
date: ${date}
digest: ${digest}`,
    ),
);

const signature = `keyId="${origin}/actor#main-key",headers="(request-target) host date digest",signature="${signedString}"`;

const res: Response = await fetch("https://mastodon.social/inbox", {
    method: "POST",
    headers: {
        date,
        digest,
        signature,
        "content-type": 'application/ld+json; profile="http://www.w3.org/ns/activitystreams"',
    },
    body: requestBody,
});

await inspectResponse(res);

// 打印 HTTP 响应
async function inspectResponse(res: Response) {
    console.log(res.status, res.statusText);
    console.log(Object.fromEntries(res.headers.entries()));
    const text = await res.text();
    console.log(text);
}

现在， mastodon.social 将返回 202 Accepted

然后，mastodon.social 将向我们的收件箱 https://my-example.com/inbox 发送如下 JSON

（当然，请求也是经过签名的，但这里就不演示如何验证请求头了）

json

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "https://mastodon.social/users/Mastodon#accepts/follows/",
    "type": "Accept",
    "actor": "https://mastodon.social/users/Mastodon",
    "object": {
        "id": "https://my-example.com/my-first-follow",
        "type": "Follow",
        "actor": "https://my-example.com/actor",
        "object": "https://mastodon.social/users/Mastodon"
    }
}

我们可以在 Mastodon 的 followers 页面看到，我们已经成功关注了 @Mastodon

←Back to home

This work is licensed under CC BY-NC-SA 4.0