this repo has no description
lewis.moe
1# BSPDS, a Personal Data Server
2
3A production-grade Personal Data Server (PDS) implementation for the AT Protocol.
4
5Uses PostgreSQL instead of SQLite, S3-compatible blob storage, and is designed to be a complete drop-in replacement for Bluesky's reference PDS implementation.
6
7## Features
8
9- Full AT Protocol support, all `com.atproto.*` endpoints implemented
10- OAuth 2.1 Provider. PKCE, DPoP, Pushed Authorization Requests
11- PostgreSQL, prod-ready database backend
12- S3-compatible object storage for blobs; works with AWS S3, UpCloud object storage, self-hosted MinIO, etc.
13- WebSocket `subscribeRepos` endpoint for real-time sync
14- Crawler notifications via `requestCrawl`
15- Multi-channel notifications: email, discord, telegram, signal
16- Per-IP rate limiting on sensitive endpoints
17
18## Running Locally
19
20Requires Rust installed locally.
21
22Run PostgreSQL and S3-compatible object store (e.g., with podman/docker):
23
24```bash
25podman compose up db objsto -d
26```
27
28Run the PDS:
29
30```bash
31just run
32```
33
34## Configuration
35
36### Required
37
38| Variable | Description |
39|----------|-------------|
40| `DATABASE_URL` | PostgreSQL connection string |
41| `S3_BUCKET` | Blob storage bucket name |
42| `S3_ENDPOINT` | S3 endpoint URL (for MinIO, etc.) |
43| `AWS_ACCESS_KEY_ID` | S3 credentials |
44| `AWS_SECRET_ACCESS_KEY` | S3 credentials |
45| `AWS_REGION` | S3 region |
46| `PDS_HOSTNAME` | Public hostname of this PDS |
47| `JWT_SECRET` | Secret for OAuth token signing (HS256) |
48| `KEY_ENCRYPTION_KEY` | Key for encrypting user signing keys (AES-256-GCM) |
49
50### Optional
51
52| Variable | Description |
53|----------|-------------|
54| `APPVIEW_URL` | Appview URL to proxy unimplemented endpoints to |
55| `CRAWLERS` | Comma-separated list of relay URLs to notify via `requestCrawl` |
56
57### Notifications
58
59At least one channel should be configured for user notifications (password reset, email verification, etc.):
60
61| Variable | Description |
62|----------|-------------|
63| `MAIL_FROM_ADDRESS` | Email sender address (enables email via sendmail) |
64| `MAIL_FROM_NAME` | Email sender name (default: "BSPDS") |
65| `SENDMAIL_PATH` | Path to sendmail binary (default: /usr/sbin/sendmail) |
66| `DISCORD_WEBHOOK_URL` | Discord webhook URL for notifications |
67| `TELEGRAM_BOT_TOKEN` | Telegram bot token for notifications |
68| `SIGNAL_CLI_PATH` | Path to signal-cli binary |
69| `SIGNAL_SENDER_NUMBER` | Signal sender phone number (+1234567890 format) |
70
71## Development
72
73```bash
74just # Show available commands
75just test # Run tests (auto-starts postgres/minio, runs nextest)
76just lint # Clippy + fmt check
77just db-reset # Drop and recreate local database
78```
79
80## Project Structure
81
82```
83src/
84 main.rs Server entrypoint
85 lib.rs Router setup
86 state.rs AppState (db pool, stores, rate limiters, circuit breakers)
87 api/ XRPC handlers organized by namespace
88 auth/ JWT authentication (ES256K per-user keys)
89 oauth/ OAuth 2.1 provider (HS256 server-wide)
90 repo/ PostgreSQL block store
91 storage/ S3 blob storage
92 sync/ Firehose, CAR export, crawler notifications
93 notifications/ Multi-channel notification service
94 plc/ PLC directory client
95 circuit_breaker/ Circuit breaker for external services
96 rate_limit/ Per-IP rate limiting
97tests/ Integration tests
98migrations/ SQLx migrations
99```
100
101## License
102
103TBD