Crate solid_pod_rs_activitypub

Expand description

§solid-pod-rs-activitypub

ActivityPub federation (Actor, inbox, outbox, HTTP Signatures, NodeInfo) for solid-pod-rs.

§Modules

actor — Actor document rendering and RSA keypair generation.
inbox — Inbox handler with HTTP-Signature verification dispatch.
outbox — Outbox handler with Create/Follow/Delete activity persistence.
delivery — Background federated-delivery worker with exponential-backoff retry.
http_sig — Draft-cavage-12 rsa-sha256 HTTP Signature sign/verify.
discovery — NodeInfo 2.1 and WebFinger discovery endpoints.
store — SQLite-backed persistence for followers, inbox, outbox, delivery queue.
error — SigError, InboxError, OutboxError.

§Quick start

use solid_pod_rs_activitypub::store::Store;

// Connect to (or create) the SQLite-backed AP store.
let store = Store::connect("sqlite:ap.db").await?;

// Check if a remote actor follows the local pod.
let is_following = store.is_follower("local-pod", "https://remote.example/actor").await?;

§Relationship to core

AP federation pulls in RSA (2048-bit keypairs, rsa-sha256 signatures) and a persistent follower store, neither of which the core solid-pod-rs crate needs for pods that don’t federate. Keeping federation in a sibling crate keeps the core lean.

HTTP Signatures use draft-cavage v12 (what the fediverse actually speaks), not RFC 9421. Core’s Ed25519-based solid_pod_rs::notifications::signing is a different protocol.

§solid-pod-rs-activitypub

Status: 0.4.0-alpha.2 — functional ActivityPub federation crate.

Rust port of the JSS ActivityPub surface (JavaScriptSolidServer/src/ap/*). 4,453 LOC across 9 modules; 53 tests. Integrators may take a dependency today.

§What ships

Module	Responsibility
`actor`	Actor document rendering + `negotiate_actor_format()` (Accept-negotiation between `application/activity+json` and LDP profiles).
`inbox`	`POST /inbox` handling with HTTP Signature verification (draft-cavage-http-signatures v12).
`outbox`	`handle_outbox()` (pre-formed activities) + `handle_outbox_post()` (raw Notes auto-wrapped in `Create`). Follower fan-out delivery.
`delivery`	HTTP Signature signing, SHA-256 digest headers, exponential retry, `enqueue_to_inboxes()` batch helper.
`http_sig`	`HttpSignatureVerifier` + `HttpActorKeyResolver` implementing draft-cavage v12 over RSA-SHA256.
`store`	SQLite-backed follower/following/outbox/delivery-queue persistence. Actor cache with 24-hour freshness.
`error`	Typed error hierarchy (`InboxError`, `OutboxError`, `DeliveryError`, `StoreError`).
`webfinger`	AP-specific WebFinger JRD rendering.
`nodeinfo`	NodeInfo 2.1 document emission.

§Federation flow

sequenceDiagram
    participant Author as Author (Local)
    participant Outbox as Outbox Handler
    participant Store as SQLite Store
    participant DQ as Delivery Queue
    participant Remote as Remote Inbox

    Author->>Outbox: POST /outbox
    Note over Outbox: Raw Note or Content-only body?
    Note over Outbox: Auto-wrap in Create activity

    Outbox->>Outbox: Stamp UUID id + actor + published
    Outbox->>Store: record_outbox(activity)
    Store-->>Outbox: activity_id

    Outbox->>Store: follower_inboxes(actor)
    Store-->>Outbox: [inbox_a, inbox_b, ...]

    loop Each follower inbox
        Outbox->>DQ: enqueue_delivery(id, inbox)
    end

    Outbox-->>Author: 201 Created + OutboundDelivery

    Note over DQ: Async delivery with retry

    loop Delivery worker
        DQ->>DQ: Sign request (HTTP Sig draft-cavage v12)
        DQ->>DQ: SHA-256 Digest header
        DQ->>Remote: POST /inbox (signed)
        alt 2xx
            DQ->>Store: mark delivered
        else 5xx
            DQ->>DQ: Exponential backoff retry
        else 4xx
            DQ->>Store: mark failed (no retry)
        end
    end

flowchart LR
    REQ["Inbound request<br/>Accept header"] --> NEG{"negotiate_actor_format()"}
    NEG -->|"activity+json<br/>ld+json (profile=activitystreams)"| AJ["ActivityJson<br/>AP Actor document"]
    NEG -->|"text/turtle<br/>application/n-triples<br/>*/*"| LDP["LdpProfile<br/>WebID profile doc"]

    style REQ fill:#4a90d9,stroke:#2c5f8a,color:#fff
    style AJ fill:#e67e22,stroke:#bf6516,color:#fff
    style LDP fill:#2ecc71,stroke:#1a9850,color:#fff

§Parity rows

Rows closed by this crate (see ../solid-pod-rs/PARITY-CHECKLIST.md):

102 — ActivityPub Actor discovery.
103 — inbox with HTTP Signature verification.
104 — outbox emission.
105 — Follow / Accept / Undo handling.
106 — Create activity delivery.
107 — Follower + Following collections.
108 — ActivityPub conformance subset.
131 — NodeInfo 2.0 (AP-specific fields).

Sprint 12 additions (JSS v0.0.60–v0.0.71 delta):

169 — Outbox POST with Note→Create wrapping.
170 — Accept-negotiation for actor profiles.
171 — Actor cache with freshness check.
172 — enqueue_to_inboxes() batch delivery.

§Sprint 12 changes

handle_outbox_post() — accepts Note, pre-formed Activity, or content-only body. Notes are auto-wrapped in Create with UUID IDs and ISO 8601 timestamps. Matches JSS v0.0.67 outbox behaviour.
negotiate_actor_format(accept: &str) — returns ActorFormat::ActivityJson or ActorFormat::LdpProfile based on the request Accept header.
Store::cache_actor() / get_cached_actor() / is_actor_cache_fresh() — 24-hour chrono-based freshness window.
enqueue_to_inboxes() — batch delivery helper.
User-Agent updated to solid-pod-rs-activitypub/0.4.0.

§JSS references

src/ap/index.js
src/ap/routes/inbox.js
src/ap/routes/outbox.js
src/ap/store.js
src/ap/keys.js

§Licence

AGPL-3.0-only.

Re-exports§

pub use actor::generate_actor_keypair;
pub use actor::negotiate_actor_format;
pub use actor::render_actor;
pub use actor::with_also_known_as;
pub use actor::Actor;
pub use actor::ActorFormat;
pub use actor::Endpoints;
pub use actor::PublicKey;
pub use delivery::DeliveryConfig;
pub use delivery::DeliveryOutcome;
pub use delivery::DeliveryWorker;
pub use discovery::nodeinfo_2_1;
pub use discovery::nodeinfo_wellknown;
pub use error::InboxError;
pub use error::OutboxError;
pub use error::SigError;
pub use http_sig::digest_header;
pub use http_sig::sign_request;
pub use http_sig::verify_request_signature;
pub use http_sig::ActorKeyResolver;
pub use http_sig::HttpActorKeyResolver;
pub use http_sig::OutboundRequest;
pub use http_sig::SignedRequest;
pub use http_sig::VerifiedActor;
pub use inbox::build_accept;
pub use inbox::handle_inbox;
pub use inbox::InboxOutcome;
pub use outbox::handle_outbox;
pub use outbox::handle_outbox_post;
pub use outbox::OutboundDelivery;
pub use store::DeliveryItem;
pub use store::InboxRow;
pub use store::OutboxRow;
pub use store::Store;

Modules§

actor: ActivityPub Actor document (§4.1) + keypair management.
delivery: Background federated-delivery worker.
discovery: Fediverse discovery: NodeInfo 2.1 + WebFinger passthrough.
error: Error types for the ActivityPub sibling crate.
http_sig: HTTP Signatures for ActivityPub federation.
inbox: Inbox handler — dispatches verified inbound AP activities.
outbox: Outbox handler — persists a new activity and queues federated delivery to followers.
store: SQLite-backed persistence for followers, following, inbox, outbox and the federated delivery queue.

Structs§

WebFingerJrd: WebFinger JRD (JSON Resource Descriptor) response.
WebFingerLink

Functions§

webfinger_response: Produce a WebFinger JRD response pointing acct:user@host at the user’s WebID. Returns None if the resource is not recognised.