atproto-xrpcs#

XRPC service framework for AT Protocol applications.

Overview#

Build AT Protocol services with JWT authorization, DID resolution, and cryptographic identity verification middleware.

Features#

• JWT authorization: Comprehensive JWT token validation with DID-based issuer verification
• DID resolution integration: Automatic DID document resolution and key verification for authorization
• Identity verification: Cryptographic verification of JWT signatures using DID documents
• Axum extractors: Ready-to-use authorization extractors for Axum web handlers
• Structured errors: Specialized error types for authorization and XRPC operations

CLI Tools#

This crate does not provide standalone CLI tools. It serves as a foundational library for building XRPC services. See atproto-xrpcs-helloworld for a complete example service implementation.

Usage#

Basic XRPC Service#

use atproto_xrpcs::authorization::Authorization;
use axum::{Json, Router, extract::Query, routing::get};
use serde::Deserialize;
use serde_json::json;

#[derive(Deserialize)]
struct HelloParams {
    name: Option<String>,
}

async fn handle_hello(
    params: Query<HelloParams>,
    authorization: Option<Authorization>,
) -> Json<serde_json::Value> {
    let name = params.name.as_deref().unwrap_or("World");

    let message = if authorization.is_some() {
        format!("Hello, authenticated {}!", name)
    } else {
        format!("Hello, {}!", name)
    };

    Json(json!({ "message": message }))
}

let app = Router::new()
    .route("/xrpc/com.example.hello", get(handle_hello))
    .with_state(your_web_context);

JWT Authorization#

use atproto_xrpcs::authorization::Authorization;

async fn handle_secure_endpoint(
    authorization: Authorization, // Required authorization
) -> Json<serde_json::Value> {
    // The Authorization extractor automatically:
    // 1. Validates the JWT token
    // 2. Resolves the caller's DID document
    // 3. Verifies the signature against the DID document
    // 4. Provides access to caller identity information

    let caller_did = authorization.subject();
    Json(json!({"caller": caller_did, "status": "authenticated"}))
}

Error Handling#

use atproto_xrpcs::errors::AuthorizationError;
use axum::{response::IntoResponse, http::StatusCode};

async fn protected_handler(
    authorization: Result<Authorization, AuthorizationError>,
) -> impl IntoResponse {
    match authorization {
        Ok(auth) => (StatusCode::OK, "Access granted").into_response(),
        Err(AuthorizationError::InvalidJWTFormat) => {
            (StatusCode::UNAUTHORIZED, "Invalid token").into_response()
        }
        Err(AuthorizationError::SubjectResolutionFailed { .. }) => {
            (StatusCode::FORBIDDEN, "Identity verification failed").into_response()
        }
        Err(_) => {
            (StatusCode::INTERNAL_SERVER_ERROR, "Authorization error").into_response()
        }
    }
}

Authorization Flow#

The Authorization extractor implements:

1. JWT extraction from HTTP Authorization headers
2. Token validation (signature and claims structure)
3. DID resolution for the token issuer
4. Signature verification against DID document public keys
5. Identity confirmation and authorization scope validation

License#

MIT License