atproto-xrpcs-helloworld#

Example XRPC service implementation demonstrating AT Protocol service patterns.

Overview#

atproto-xrpcs-helloworld provides a complete AT Protocol XRPC service that demonstrates DID web identity, service document generation, well-known endpoint handling, and JWT-based authentication using the atproto-xrpcs library.

Binaries#

• atproto-xrpcs-helloworld: Complete XRPC service with DID web identity and authentication

Features#

• Complete XRPC service implementation with authentication
• DID web identity with automatic service document generation
• Well-known endpoints for AT Protocol discovery
• Example authenticated and unauthenticated XRPC endpoint
• JWT authorization with DID document verification

Usage#

The service provides these 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 - Example XRPC endpoint

Environment Variables#

# Required
export EXTERNAL_BASE=your-service.com
export SERVICE_KEY=did:key:zQ3sh...

# Optional
export PLC_HOSTNAME=plc.directory
export DNS_NAMESERVERS=8.8.8.8;1.1.1.1
export USER_AGENT="my-xrpc-service/1.0"

Example Requests#

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

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

Command Line Examples#

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

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

Use Cases#

This example service is ideal for:

• Learning AT Protocol XRPC service patterns
• Testing AT Protocol clients against a known service
• Starting point for building production services
• Understanding DID web document structure

License#

MIT License