A Minecraft Fabric mod that connects the game with ATProtocol ⛏️
1# Social Sync
2
3A Fabric mod for Minecraft 1.21.10 that bridges the game with the AT Protocol, enabling decentralized data synchronization and social features.
4
5## Project Status
6
7**This project is in active development and is NOT ready for production use.**
8
9Core features are now implemented:
10- ✅ Identity linking and authentication (OAuth + app passwords)
11- ✅ Stat syncing to AT Protocol
12- ✅ Achievement syncing
13- ✅ Play session tracking
14- ✅ Server status snapshots
15- ✅ Sync consent controls
16- ✅ Enterprise-grade security (encryption, rate limiting, audit logging)
17
18## Affiliation & Hosting
19
20This mod started out as a personal project by **Ewan Croft** — I built the early versions on my own while experimenting with Minecraft and the AT Protocol.
21
22The project is now maintained by the **Jollywhoppers** coding group as a whole.
23
24The code lives at **[https://tangled.org/jollywhoppers.com/socialsync](https://tangled.org/jollywhoppers.com/socialsync)**.
25
26The project is hosted on **[Tangled](https://tangled.org/)**.
27
28## Overview
29
30Social Sync aims to integrate Minecraft gameplay with the AT Protocol (the protocol powering Bluesky), allowing game data to be synced to AT Protocol lexicons. This enables decentralized storage and sharing of Minecraft data across the federated network.
31
32## Current Features
33
34### Identity Linking & Authentication ✓
35
36Players can link their Minecraft accounts to their AT Protocol identities and authenticate to enable data syncing:
37
38**Basic Commands:**
39
40* **`/atproto link <handle or DID>`** - Link your Minecraft UUID to your AT Protocol identity (no login required)
41* **`/atproto login <handle> <app-password>`** - Authenticate with app password (fallback method)
42* **`/atproto logout`** - Remove authentication (keeps identity link)
43* **`/atproto unlink`** - Remove identity link and authentication
44* **`/atproto whoami`** - View your linked identity and auth status
45* **`/atproto status`** - Quick status check
46* **`/atproto whois <player or handle>`** - Look up another player's identity
47* **`/atproto sync`** - View your sync consent settings
48* **`/atproto sync stats <on|off>`** - Control whether your stats are synced
49* **`/atproto sync sessions <on|off>`** - Control whether your sessions are synced
50* **`/atproto sync achievements <on|off>`** - Control whether your achievements are synced
51* **`/atproto sync server-status <on|off>`** - Control whether server status is synced
52
53**Example Workflow:**
54
55```plaintext
56# 1. Link your identity (read-only)
57/atproto link alice.bsky.social
58✓ Successfully linked to AT Protocol!
59 Handle: alice.bsky.social
60 DID: did:plc:abcdef123456
61 PDS: https://morel.us-east.host.bsky.network
62
63# 2. Authenticate with an App Password
64/atproto login alice.bsky.social abcd-1234-efgh-5678
65✓ Successfully authenticated!
66You can now sync your Minecraft data to AT Protocol!
67
68# 3. Check your status
69/atproto whoami
70━━━ Your AT Protocol Identity ━━━
71Handle: alice.bsky.social
72DID: did:plc:abcdef123456
73Linked: 5 minutes ago
74Last Verified: 5 minutes ago
75
76Authentication: ✓ Active
77You can sync data to AT Protocol
78```
79
80### Security Features
81
82The mod implements enterprise-grade security measures to protect player data and prevent abuse:
83
84* **AES-256-GCM Encryption**: Session data encrypted at rest with server-specific keys
85* **Rate Limiting**: 3 authentication attempts per 15 minutes, 30-minute lockout on abuse
86* **Security Audit Logging**: All sensitive operations logged for monitoring
87* **Sanitized Error Messages**: No sensitive data exposed in error messages or logs
88* **Restricted File Permissions**: Owner-only access to configuration files
89* **Atomic File Writes**: Prevents corruption during saves
90* **Thread-Safe Operations**: Concurrent access protection for all shared data
91* **Automatic Token Refresh**: Access tokens refreshed before expiration
92* **Path Validation**: Protection against directory traversal attacks
93
94All passwords are handled securely - app passwords are never logged or stored (only the resulting JWT tokens are kept).
95
96### Key Features
97
98* **Slingshot Integration**: Uses [Slingshot by Microcosm](https://slingshot.microcosm.blue) for fast, cached PDS resolution
99* **OAuth Support**: Browser-based authentication with DPoP and PKCE (recommended method)
100* **App Password Fallback**: Secure authentication using AT Protocol app passwords
101* **Automatic Token Refresh**: Access tokens are automatically refreshed before expiration
102* **Multi-PDS Support**: Works with any AT Protocol PDS, not just Bluesky
103* **Persistent Sessions**: Authentication survives server restarts
104* **Encrypted Storage**: Session data protected with AES-256-GCM encryption
105
106### Data Syncing
107
108The mod automatically syncs Minecraft data to AT Protocol:
109
110* **Player Stats**: Periodic snapshots of player statistics (kills, blocks mined, playtime, etc.)
111* **Achievements**: Records when players earn Minecraft advancements
112* **Play Sessions**: Tracks when players join and leave servers
113* **Server Status**: Periodic server information snapshots (online players, MOTD, etc.)
114
115All data syncing respects **sync consent** — players control whether their data is written to AT Protocol. Note that AT Protocol data is **always public** by design, so the sync consent controls whether data is written at all, not who can see it.
116
117Use `/atproto sync` to view and change your sync consent settings. Consent can also be toggled from the mod config screen.
118
119### Getting an App Password
120
1211. Go to your AT Protocol account settings (e.g., Bluesky Settings → Privacy and Security → App Passwords)
1222. Create a new app password with a descriptive name (e.g., "Minecraft Server")
1233. Copy it immediately (you won't see it again!)
1244. Use it in `/atproto login`
1255. **Never share your app password or use your main account password!**
126
127### Future Possibilities
128
129* Achievement announcements via AT Protocol feeds
130* Cross-server player reputation systems
131* In-game social features tied to AT Protocol identities
132
133## Technical Stack
134
135* **Minecraft Version**: 1.21.10
136* **Mod Loader**: Fabric API
137* **Protocol**: AT Protocol (atproto)
138* **Language**: Kotlin (with Java interop)
139* **Build System**: Gradle 8.x
140* **Dependencies**:
141
142 * Fabric Loader 0.18.3
143 * Fabric API 0.138.4+1.21.10
144 * Fabric Language Kotlin 1.13.8+kotlin.2.3.0
145 * kotlinx-serialization for JSON handling
146 * kotlinx-coroutines for async operations
147* **Identity Resolution**: [Slingshot](https://slingshot.microcosm.blue) by Microcosm
148* **Authentication**: AT Protocol OAuth/App Passwords
149
150## Installation
151
152### For Users
153
1541. Install [Fabric Loader](https://fabricmc.net/use/) for Minecraft 1.21.10
1552. Download and install [Fabric API](https://modrinth.com/mod/fabric-api) version 0.138.4+1.21.10 or compatible
1563. Download and install [Fabric Language Kotlin](https://modrinth.com/mod/fabric-language-kotlin) version 1.13.8+kotlin.2.3.0 or compatible
1574. Place the social-sync JAR in your `mods` folder
1585. Launch the game and use `/atproto help` to see available commands
159
160### For Developers
161
162Clone the repository:
163
164```bash
165git clone git@tangled.sh:jollywhoppers.com/socialsync
166cd socialsync
167```
168
169If you use Nix, start a development shell first:
170
171```bash
172nix develop
173```
174
175Build the project:
176
177```bash
178./gradlew build
179```
180
181The built JAR will be in `build/libs/`.
182
183For development with auto-reload:
184
185```bash
186./gradlew runClient
187```
188
189## Project Structure
190
191```plaintext
192src/main/
193├── kotlin/com/jollywhoppers/
194│ ├── socialsync.kt # Main mod initializer
195│ └── atproto/
196│ ├── AtProtoClient.kt # HTTP client with Slingshot integration
197│ ├── AtProtoSessionManager.kt # Authentication & token management
198│ ├── AtProtoCommands.kt # Command handlers
199│ ├── PlayerIdentityStore.kt # UUID<->DID mapping storage
200│ ├── PlayerSyncPreferencesStore.kt # Sync consent (single source of truth)
201│ ├── security/
202│ │ ├── RateLimiter.kt # Rate limiting for auth attempts
203│ │ ├── SecurityAuditor.kt # Security event logging
204│ │ └── SecurityUtils.kt # Cryptography & path validation
205│ └── examples/
206│ └── RecordCreationExample.kt # Example code for data syncing
207└── resources/
208 ├── fabric.mod.json # Mod metadata
209 └── lexicons/ # Lexicon schemas
210 ├── README.md # Lexicon documentation
211 ├── com.jollywhoppers.minecraft.defs.json
212 ├── com.jollywhoppers.minecraft.player.profile.json
213 ├── com.jollywhoppers.minecraft.player.stats.json
214 ├── com.jollywhoppers.minecraft.player.session.json
215 ├── com.jollywhoppers.minecraft.achievement.json
216 ├── com.jollywhoppers.minecraft.leaderboard.json
217 └── com.jollywhoppers.minecraft.server.status.json
218```
219
220## Lexicon Schemas
221
222The mod defines several AT Protocol lexicon schemas under the `com.jollywhoppers.minecraft.*` namespace:
223
224* **Player Profile** (`literal:self`) - Links Minecraft UUIDs to AT Protocol DIDs with privacy controls
225* **Player Stats** (`tid`) - Snapshots of player statistics for leaderboards
226* **Player Sessions** (`tid`) - Play session tracking (join/leave times)
227* **Achievements** (`tid`) - Records of earned achievements/advancements
228* **Leaderboards** (`tid`) - Pre-computed leaderboard entries
229* **Server Status** (`literal:self`) - Server information and status
230
231See `src/main/resources/lexicons/README.md` for detailed schema documentation.
232
233## Architecture
234
235```plaintext
236Player Commands (/atproto link, /atproto sync, etc.)
237 ↓
238AtProtoCommands (Kotlin Coroutines)
239 ↓
240┌────────────────────────────────────────┐
241│ AtProtoSessionManager │
242│ • Authentication & Token Storage │
243│ • AES-256-GCM Encryption │
244│ • Automatic Token Refresh │
245└────────────────────────────────────────┘
246 ↓
247┌────────────────────────────────────────┐
248│ PlayerSyncPreferencesStore │
249│ • Sync consent (4 categories) │
250│ • Sync frequency settings │
251│ • Single source of truth │
252└────────────────────────────────────────┘
253 ↓
254┌────────────────────────────────────────┐
255│ AtProtoClient │
256│ • HTTP + XRPC + Slingshot │
257│ • Identity Resolution │
258└────────────────────────────────────────┘
259 ↓
260┌────────────────────────────────────────┐
261│ Security Layer │
262│ • SecurityAuditor (Event Logging) │
263│ • SecurityUtils (Crypto & Validation)│
264└────────────────────────────────────────┘
265 ↓
266┌────────────────────────────────────────┐
267│ Slingshot (Microcosm Blue) │
268│ Fast PDS Resolution & Caching │
269└────────────────────────────────────────┘
270 ↓
271AT Protocol Network
272 - Player's PDS (Data & Auth)
273 - plc.directory (DID Resolution)
274 ↓
275Local Storage
276 - player-identities.json (UUID↔DID mappings)
277 - player-sessions.json (Encrypted auth tokens)
278 - sync-preferences/ (Per-player sync consent)
279 - .encryption.key (AES-256 key)
280 - security-audit.log (Security events)
281```
282
283## Authentication & Security
284
285### How It Works
286
2871. **Link Identity**: Players link their Minecraft UUID to their AT Protocol DID (read-only, no login required)
2882. **Authenticate**: Players log in with their handle and an app password to create an authenticated session
2893. **Token Management**: The mod stores JWT access and refresh tokens securely with AES-256-GCM encryption
2904. **Auto-Refresh**: Access tokens are automatically refreshed before expiration
2915. **Data Syncing**: Authenticated players will be able to sync their Minecraft data to their PDS (coming soon)
292
293### Security Best Practices
294
295**For Players:**
296
297* **Always use App Passwords**, never main account passwords
298* Create a unique app password for each Minecraft server
299* Revoke unused app passwords regularly
300* If you suspect compromise, revoke the app password immediately
301
302**For Server Operators:**
303
304* Secure the `config/atproto-connect/` directory with appropriate file permissions
305* Monitor `security-audit.log` for suspicious activity
306* Keep the `.encryption.key` file secure (never share or commit to version control)
307* Regular backups of configuration files
308* Update the mod regularly for security patches
309
310### Token Storage
311
312* **Location**: `config/atproto-connect/player-sessions.json`
313* **Encryption**: AES-256-GCM with server-specific key
314* **Contents**: Access and refresh JWTs for authenticated players
315* **Security**: Encrypted at rest, owner-only file permissions
316* **Lifetime**: Access tokens expire after ~2 hours, refresh tokens last longer
317
318### Rate Limiting
319
320To prevent brute-force attacks:
321
322* **Maximum Attempts**: 3 failed login attempts
323* **Time Window**: 15 minutes
324* **Lockout Duration**: 30 minutes after exceeding limit
325* **Tracking**: Per-player UUID and per-identifier
326
327### Security Audit Log
328
329All security-sensitive operations are logged to `config/atproto-connect/security-audit.log`:
330
331* Authentication attempts (success/failure)
332* Rate limit violations
333* Session creation/deletion
334* Token refresh operations
335* Security errors
336
337## Configuration Files
338
339All configuration files are stored in `config/atproto-connect/`:
340
341* **`player-identities.json`** - UUID to DID/handle mappings (plaintext as these are both publicly accessible anyway)
342* **`sync-preferences/`** - Per-player sync consent settings (stats, sessions, achievements, server status)
343* **`player-sessions.json`** - Encrypted authentication sessions
344* **`.encryption.key`** - AES-256 encryption key (auto-generated, keep secure!)
345* **`security-audit.log`** - Security event log
346
347**Important**: Never commit `.encryption.key` or `player-sessions.json` to version control!
348
349## Development Roadmap
350
351* [x] Design lexicon schemas for Minecraft data types
352* [x] Implement AT Protocol client with Slingshot integration
353* [x] Create identity linking system
354* [x] Implement authentication with app passwords
355* [x] Build session management with automatic token refresh
356* [x] Add encryption for session storage
357* [x] Implement rate limiting and security auditing
358* [x] Build data collection hooks for player statistics
359* [x] Implement authenticated record creation (writing stats)
360* [x] Add automatic stat syncing at configurable intervals
361* [x] Add sync consent controls (stats/sessions/achievements/server-status)
362* [x] Implement OAuth browser flow for better UX
363* [x] Add DPoP support
364* [x] Implement achievement syncing
365* [x] Implement play session tracking
366* [x] Implement server status snapshots
367* [x] Create example AppView for displaying Minecraft data
368* [x] Write comprehensive documentation
369* [x] Add automated tests
370* [ ] Publish to Modrinth/CurseForge
371
372## Contributing
373
374This project is in active development. If you're interested in contributing:
375
3761. Check the Issues page for open tasks
3772. Fork the repository
3783. Create a feature branch
3794. Submit a pull request with a clear description
380
381Please follow Kotlin coding conventions and include tests for new features.
382
383## Documentation
384
385- [API Reference](docs/API_REFERENCE.md) - Complete API documentation for all services
386- [Architecture Guide](docs/ARCHITECTURE.md) - System architecture, data flow, deployment
387- [AppView Guide](docs/APPVIEW.md) - Display and query Minecraft data via AT Protocol
388- [AppView Quick Start](docs/APPVIEW_QUICKSTART.md) - Setup guide for server operators
389- [Testing Guide](docs/TEST_GUIDE.md) - Automated testing and test suite
390- [Lexicon Schemas](src/main/resources/lexicons/README.md) - Data schema specifications
391- [Examples](docs/examples/) - Code examples for common tasks
392
393## Resources
394
395### AT Protocol
396
397* [AT Protocol Documentation](https://atproto.com/)
398* [Lexicon Specifications](https://atproto.com/specs/lexicon)
399* [XRPC API Reference](https://atproto.com/specs/xrpc)
400* [OAuth Specification](https://atproto.com/specs/oauth)
401* [Bluesky API Docs](https://docs.bsky.app/)
402
403### Microcosm
404
405* [Slingshot Documentation](https://slingshot.microcosm.blue/)
406* [Microcosm Project](https://microcosm.blue/)
407
408### Minecraft Modding
409
410* [Fabric Documentation](https://fabricmc.net/wiki/)
411* [Fabric Language Kotlin](https://github.com/FabricMC/fabric-language-kotlin)
412
413## License
414
415[AGPL-3.0](LICENSE) – GNU Affero General Public License v3
416
417This project is free software: you may use, modify, and distribute it, including for commercial purposes.
418If you distribute this software or run it as a service accessible over a network, you must provide the complete corresponding source code, including any modifications, under the same licence.
419
420This ensures that improvements and extensions to the project remain open and available to the community.
421
422## Disclaimer
423
424This is an experimental project exploring the intersection of decentralized protocols and gaming. It is not affiliated with or endorsed by Mojang, Microsoft, or the official AT Protocol team.
425
426## Acknowledgments
427
428* [Microcosm](https://microcosm.blue) for Slingshot, which makes PDS resolution fast and reliable
429* The AT Protocol team for building an open, decentralized social network protocol
430* The Fabric community for excellent mod development tools
431* The Kotlin community for a great language and ecosystem
432
433---
434
435**Version**: 0.5.0
436**Repository**: `git@tangled.sh:jollywhoppers.com/socialsync`
437**Status**: Alpha - Not Production Ready