atproto-xrpcs-helloworld#

A complete example implementation of an AT Protocol XRPC service demonstrating DID web functionality, service document generation, and JWT-based authentication using the atproto-xrpcs library.

Overview#

atproto-xrpcs-helloworld provides a fully functional AT Protocol XRPC service that serves as both a reference implementation and a development tool. This service demonstrates all the core concepts of AT Protocol XRPC services including DID web identity, service document generation, well-known endpoint handling, and authenticated XRPC endpoints.

This project was extracted from the open-sourced Smokesignal project and serves as an example of how to build complete AT Protocol services using the project's XRPC components.

Features#

• Complete XRPC Service: Full implementation of an AT Protocol XRPC service with authentication
• DID Web Support: Native DID web identity with automatic service document generation
• Well-Known Endpoints: Standard AT Protocol discovery endpoints for identity and service metadata
• Hello World XRPC: Example authenticated and unauthenticated XRPC endpoint implementation
• JWT Authentication: Demonstrates integration with atproto-xrpcs authorization extractors
• Service Discovery: Complete service document with verification methods and service endpoints
• Development Ready: Configured for immediate deployment and testing

Installation#

This crate produces a binary executable. Build it with:

cargo build --release --bin atproto-xrpcs-helloworld

Command Line Tool#

atproto-xrpcs-helloworld#

A complete AT Protocol XRPC service implementation that demonstrates all core functionality for building production XRPC services. This tool sets up a full web server with DID web identity, service discovery endpoints, and authenticated XRPC endpoints.

Features:

• DID Web Identity: Automatically generates and serves DID web documents
• Service Document: Creates complete AT Protocol service documents with verification methods
• Well-Known Endpoints: Implements required discovery endpoints for AT Protocol services
• XRPC Hello World: Example XRPC endpoint with both authenticated and unauthenticated access
• JWT Authorization: Demonstrates proper JWT validation and DID document verification
• Configurable Identity: Uses environment variables for service identity configuration

# Start the XRPC hello world service
cargo run --bin atproto-xrpcs-helloworld

# The service will start on http://0.0.0.0:8080 with the following endpoints:
# GET  /                                           - HTML hello world page
# GET  /.well-known/did.json                      - DID web document
# GET  /.well-known/atproto-did                   - AT Protocol DID discovery
# GET  /xrpc/garden.lexicon.ngerakines.helloworld.Hello - XRPC hello world endpoint

# Example XRPC requests:
# curl "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Alice"
# curl -H "Authorization: Bearer <jwt-token>" "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Bob"

Environment Variables:

# Required: External base URL for service identity
export EXTERNAL_BASE=your-service.com

# Required: Service private key for DID web identity
export SERVICE_KEY=did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA

# Optional: Custom PLC directory hostname
export PLC_HOSTNAME=plc.directory

# Optional: Custom DNS nameservers (semicolon-separated)
export DNS_NAMESERVERS=8.8.8.8;1.1.1.1

# Optional: Custom CA certificate bundles (semicolon-separated paths)
export CERTIFICATE_BUNDLES=/path/to/cert1.pem;/path/to/cert2.pem

# Optional: Custom User-Agent string
export USER_AGENT="my-xrpc-service/1.0"

Service Endpoints:

The service automatically provides these AT Protocol standard endpoints:

1. GET / - Simple HTML hello world page for service status
2. GET /.well-known/did.json - DID web document with verification methods and service endpoints
3. GET /.well-known/atproto-did - AT Protocol DID discovery endpoint returning the service DID
4. GET /xrpc/garden.lexicon.ngerakines.helloworld.Hello - Example XRPC endpoint with optional authentication

XRPC Endpoint Details:

The hello world XRPC endpoint demonstrates:

• Optional Authentication: Works with or without JWT authorization headers
• Parameter Processing: Accepts optional subject query parameter
• Different Responses: Returns different messages for authenticated vs unauthenticated requests
• Proper XRPC Format: Returns JSON responses following AT Protocol XRPC conventions

# Unauthenticated request
curl "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=World"
# Response: {"message": "Hello, World!"}

# Authenticated request (with valid JWT)
curl -H "Authorization: Bearer <valid-jwt>" \
     "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Alice"
# Response: {"message": "Hello, authenticated Alice!"}

Service Document Structure:

The service automatically generates a complete DID web document:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:web:your-service.com",
  "verificationMethod": [{
    "id": "did:web:your-service.com#atproto",
    "type": "Multikey",
    "controller": "did:web:your-service.com",
    "publicKeyMultibase": "zQ3sh..."
  }],
  "service": [{
    "id": "#bsky_appview",
    "type": "BskyAppView",
    "serviceEndpoint": "https://your-service.com"
  }]
}

Use Cases#

This example service is ideal for:

• Learning AT Protocol: Understanding how XRPC services work in practice
• Development Testing: Testing AT Protocol clients against a known service
• Service Template: Starting point for building production AT Protocol services
• Integration Testing: Testing authentication and authorization flows
• DID Web Examples: Understanding DID web document structure and endpoints

Implementation Details#

The service demonstrates several key AT Protocol concepts:

DID Web Identity#

• Automatic generation of DID web documents with verification methods
• Service endpoint definitions for AT Protocol service discovery
• Public key management for service authentication

XRPC Service Implementation#

• Proper XRPC endpoint naming following AT Protocol conventions
• JSON request/response handling with serde integration
• Parameter extraction and validation using Axum extractors

Authentication Integration#

• Optional JWT authorization using ResolvingAuthorization extractor
• Automatic DID document resolution and signature verification
• Different behavior for authenticated vs unauthenticated requests

Service Architecture#

• Modular state management using Axum's state system
• Integration with atproto-identity for cryptographic operations
• LRU caching for DID document storage and performance

Dependencies#

This binary builds on:

• atproto-xrpcs - XRPC service building blocks and authorization
• atproto-identity - Identity resolution and cryptographic operations
• atproto-oauth - OAuth 2.0 operations and JWT handling
• atproto-record - AT Protocol record operations
• axum - Web framework for HTTP server implementation
• reqwest - HTTP client for identity resolution
• tokio - Async runtime for web service operations
• serde_json - JSON handling for XRPC requests and responses

Development#

To run the service locally for development:

# Set required environment variables
export EXTERNAL_BASE=localhost:8080
export SERVICE_KEY=did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA

# Run the service
cargo run --bin atproto-xrpcs-helloworld

# Test the endpoints
curl http://localhost:8080/
curl http://localhost:8080/.well-known/did.json
curl http://localhost:8080/.well-known/atproto-did
curl "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Test"

Security Considerations#

• Service Key Management: The SERVICE_KEY environment variable contains private key material and should be handled securely
• JWT Validation: The service performs full JWT signature validation against DID documents
• DID Verification: All authentication goes through proper DID document resolution and verification
• HTTPS Recommended: Production deployments should use HTTPS for all endpoints

Contributing#

Contributions are welcome! Please ensure that:

1. All tests pass: cargo test
2. Code is properly formatted: cargo fmt
3. No linting issues: cargo clippy
4. New functionality includes appropriate tests and documentation
5. Changes maintain compatibility with AT Protocol specifications

License#

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments#

This service was extracted from the Smokesignal project, an open-source event and RSVP management and discovery application.