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

January 4, 2024

这篇文章主要参考了 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@main/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