A library for ATProtocol identities.
smokesignal.events
1# atproto-xrpcs-helloworld
2
3Example XRPC service with DID:web identity and JWT authentication.
4
5## Overview
6
7Complete AT Protocol XRPC service demonstrating DID:web identity, service document generation, well-known endpoints, and JWT-based authentication patterns.
8
9## Features
10
11- **Complete XRPC service**: Production-ready service implementation with authentication
12- **DID:web identity**: Automatic service document generation with well-known endpoint support
13- **JWT authorization**: Optional JWT-based authentication with DID document verification
14- **Discovery endpoints**: Standard AT Protocol discovery endpoints for service metadata
15- **Example patterns**: Reference implementation for building AT Protocol services
16
17## CLI Tools
18
19The following service binary is available:
20
21- **`atproto-xrpcs-helloworld`**: Complete XRPC service demonstrating AT Protocol patterns with DID:web identity and optional JWT authentication
22
23## Usage
24
25The service provides these endpoints:
26
27- `GET /` - HTML hello world page
28- `GET /.well-known/did.json` - DID web document
29- `GET /.well-known/atproto-did` - AT Protocol DID discovery
30- `GET /xrpc/garden.lexicon.ngerakines.helloworld.Hello` - Example XRPC endpoint
31
32### Environment Variables
33
34```bash
35# Required
36export EXTERNAL_BASE=your-service.com
37export SERVICE_KEY=did:key:zQ3sh...
38
39# Optional
40export PLC_HOSTNAME=plc.directory
41export DNS_NAMESERVERS=8.8.8.8;1.1.1.1
42export USER_AGENT="my-xrpc-service/1.0"
43```
44
45### Example Requests
46
47```bash
48# Unauthenticated request
49curl "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=World"
50# Response: {"message": "Hello, World!"}
51
52# Authenticated request
53curl -H "Authorization: Bearer <jwt-token>" \
54 "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Alice"
55# Response: {"message": "Hello, authenticated Alice!"}
56```
57
58## Command Line Examples
59
60```bash
61# Start the service
62cargo run --bin atproto-xrpcs-helloworld
63
64# Test endpoints
65curl http://localhost:8080/
66curl http://localhost:8080/.well-known/did.json
67curl "http://localhost:8080/xrpc/garden.lexicon.ngerakines.helloworld.Hello?subject=Test"
68```
69
70## Use Cases
71
72This example service is ideal for:
73
74- Learning AT Protocol XRPC service patterns
75- Testing AT Protocol clients against a known service
76- Starting point for building production services
77- Understanding DID web document structure
78
79## License
80
81MIT License