A Minecraft Fabric mod that connects the game with ATProtocol ⛏️
chore: add affiliation and hosting info
+116
-105
+116
-105
README.md
+116
-105
README.md
···
6
6
7
7
**This project is in active development and is NOT ready for production use.** Identity linking and authentication are now fully implemented with enterprise-grade security features. Stat syncing and other data collection features are planned but not yet implemented.
8
8
9
+
## Affiliation & Hosting
10
+
11
+
This 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.
12
+
13
+
Later on, I joined the **Jolly Whoppers** coding group and the project became part of the group in that sense — shared context, shared people, same general ecosystem — but the repo itself is still under my own AT Protocol DID.
14
+
15
+
The code lives at **[https://tangled.org/ewancroft.uk/atproto-connect](https://tangled.org/ewancroft.uk/atproto-connect)**, which corresponds to my AT Protocol DID (**`did:plc:ofrbh253gwicbkc5nktqepol`**). The project is associated with Jolly Whoppers (group DID **[`did:plc:lwckcyzhyrufq4ytg2abji7d`](https://tangled.org/did:plc:lwckcyzhyrufq4ytg2abji7d)**), but it’s not moved under the group’s DID.
16
+
17
+
The project is hosted on **[Tangled](https://tangled.org/)**. I don’t run the infrastructure — I just started the project and maintain it.
18
+
9
19
## Overview
10
20
11
21
atproto-connect 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.
···
18
28
19
29
**Basic Commands:**
20
30
21
-
- **`/atproto link <handle or DID>`** - Link your Minecraft UUID to your AT Protocol identity (no login required)
22
-
- **`/atproto login <handle> <app-password>`** - Authenticate to enable data syncing
23
-
- **`/atproto logout`** - Remove authentication (keeps identity link)
24
-
- **`/atproto unlink`** - Remove identity link and authentication
25
-
- **`/atproto whoami`** - View your linked identity and auth status
26
-
- **`/atproto status`** - Quick status check
27
-
- **`/atproto whois <player or handle>`** - Look up another player's identity
31
+
* **`/atproto link <handle or DID>`** - Link your Minecraft UUID to your AT Protocol identity (no login required)
32
+
* **`/atproto login <handle> <app-password>`** - Authenticate to enable data syncing
33
+
* **`/atproto logout`** - Remove authentication (keeps identity link)
34
+
* **`/atproto unlink`** - Remove identity link and authentication
35
+
* **`/atproto whoami`** - View your linked identity and auth status
36
+
* **`/atproto status`** - Quick status check
37
+
* **`/atproto whois <player or handle>`** - Look up another player's identity
28
38
29
39
**Example Workflow:**
30
40
···
57
67
58
68
The mod implements enterprise-grade security measures to protect player data and prevent abuse:
59
69
60
-
- **AES-256-GCM Encryption**: Session data encrypted at rest with server-specific keys
61
-
- **Rate Limiting**: 3 authentication attempts per 15 minutes, 30-minute lockout on abuse
62
-
- **Security Audit Logging**: All sensitive operations logged for monitoring
63
-
- **Sanitized Error Messages**: No sensitive data exposed in error messages or logs
64
-
- **Restricted File Permissions**: Owner-only access to configuration files
65
-
- **Atomic File Writes**: Prevents corruption during saves
66
-
- **Thread-Safe Operations**: Concurrent access protection for all shared data
67
-
- **Automatic Token Refresh**: Access tokens refreshed before expiration
68
-
- **Path Validation**: Protection against directory traversal attacks
70
+
* **AES-256-GCM Encryption**: Session data encrypted at rest with server-specific keys
71
+
* **Rate Limiting**: 3 authentication attempts per 15 minutes, 30-minute lockout on abuse
72
+
* **Security Audit Logging**: All sensitive operations logged for monitoring
73
+
* **Sanitized Error Messages**: No sensitive data exposed in error messages or logs
74
+
* **Restricted File Permissions**: Owner-only access to configuration files
75
+
* **Atomic File Writes**: Prevents corruption during saves
76
+
* **Thread-Safe Operations**: Concurrent access protection for all shared data
77
+
* **Automatic Token Refresh**: Access tokens refreshed before expiration
78
+
* **Path Validation**: Protection against directory traversal attacks
69
79
70
80
All passwords are handled securely - app passwords are never logged or stored (only the resulting JWT tokens are kept).
71
81
72
82
### Key Features
73
83
74
-
- **Slingshot Integration**: Uses [Slingshot by Microcosm](https://slingshot.microcosm.blue) for fast, cached PDS resolution
75
-
- **App Password Support**: Secure authentication using AT Protocol app passwords (never use your main password!)
76
-
- **Automatic Token Refresh**: Access tokens are automatically refreshed before expiration
77
-
- **Multi-PDS Support**: Works with any AT Protocol PDS, not just Bluesky
78
-
- **Persistent Sessions**: Authentication survives server restarts
79
-
- **Encrypted Storage**: Session data protected with AES-256-GCM encryption
84
+
* **Slingshot Integration**: Uses [Slingshot by Microcosm](https://slingshot.microcosm.blue) for fast, cached PDS resolution
85
+
* **App Password Support**: Secure authentication using AT Protocol app passwords (never use your main password!)
86
+
* **Automatic Token Refresh**: Access tokens are automatically refreshed before expiration
87
+
* **Multi-PDS Support**: Works with any AT Protocol PDS, not just Bluesky
88
+
* **Persistent Sessions**: Authentication survives server restarts
89
+
* **Encrypted Storage**: Session data protected with AES-256-GCM encryption
80
90
81
91
### Getting an App Password
82
92
···
88
98
89
99
### Future Possibilities
90
100
91
-
- Automatic stat syncing at configurable intervals
92
-
- Achievement announcements via AT Protocol feeds
93
-
- Cross-server player reputation systems
94
-
- Privacy controls for what data gets synced
95
-
- In-game social features tied to AT Protocol identities
101
+
* Automatic stat syncing at configurable intervals
102
+
* Achievement announcements via AT Protocol feeds
103
+
* Cross-server player reputation systems
104
+
* Privacy controls for what data gets synced
105
+
* In-game social features tied to AT Protocol identities
96
106
97
107
## Technical Stack
98
108
99
-
- **Minecraft Version**: 1.21.10
100
-
- **Mod Loader**: Fabric API
101
-
- **Protocol**: AT Protocol (atproto)
102
-
- **Language**: Kotlin (with Java interop)
103
-
- **Build System**: Gradle 8.x
104
-
- **Dependencies**:
105
-
- Fabric Loader 0.18.3
106
-
- Fabric API 0.138.4+1.21.10
107
-
- Fabric Language Kotlin 1.13.8+kotlin.2.3.0
108
-
- kotlinx-serialization for JSON handling
109
-
- kotlinx-coroutines for async operations
110
-
- **Identity Resolution**: [Slingshot](https://slingshot.microcosm.blue) by Microcosm
111
-
- **Authentication**: AT Protocol OAuth/App Passwords
109
+
* **Minecraft Version**: 1.21.10
110
+
* **Mod Loader**: Fabric API
111
+
* **Protocol**: AT Protocol (atproto)
112
+
* **Language**: Kotlin (with Java interop)
113
+
* **Build System**: Gradle 8.x
114
+
* **Dependencies**:
115
+
116
+
* Fabric Loader 0.18.3
117
+
* Fabric API 0.138.4+1.21.10
118
+
* Fabric Language Kotlin 1.13.8+kotlin.2.3.0
119
+
* kotlinx-serialization for JSON handling
120
+
* kotlinx-coroutines for async operations
121
+
* **Identity Resolution**: [Slingshot](https://slingshot.microcosm.blue) by Microcosm
122
+
* **Authentication**: AT Protocol OAuth/App Passwords
112
123
113
124
## Installation
114
125
···
177
188
178
189
The mod defines several AT Protocol lexicon schemas under the `com.jollywhoppers.minecraft.*` namespace:
179
190
180
-
- **Player Profile** (`literal:self`) - Links Minecraft UUIDs to AT Protocol DIDs with privacy controls
181
-
- **Player Stats** (`tid`) - Snapshots of player statistics for leaderboards
182
-
- **Player Sessions** (`tid`) - Play session tracking (join/leave times)
183
-
- **Achievements** (`tid`) - Records of earned achievements/advancements
184
-
- **Leaderboards** (`tid`) - Pre-computed leaderboard entries
185
-
- **Server Status** (`literal:self`) - Server information and status
191
+
* **Player Profile** (`literal:self`) - Links Minecraft UUIDs to AT Protocol DIDs with privacy controls
192
+
* **Player Stats** (`tid`) - Snapshots of player statistics for leaderboards
193
+
* **Player Sessions** (`tid`) - Play session tracking (join/leave times)
194
+
* **Achievements** (`tid`) - Records of earned achievements/advancements
195
+
* **Leaderboards** (`tid`) - Pre-computed leaderboard entries
196
+
* **Server Status** (`literal:self`) - Server information and status
186
197
187
198
See `src/main/resources/lexicons/README.md` for detailed schema documentation.
188
199
···
243
254
244
255
**For Players:**
245
256
246
-
- **Always use App Passwords**, never main account passwords
247
-
- Create a unique app password for each Minecraft server
248
-
- Revoke unused app passwords regularly
249
-
- If you suspect compromise, revoke the app password immediately
257
+
* **Always use App Passwords**, never main account passwords
258
+
* Create a unique app password for each Minecraft server
259
+
* Revoke unused app passwords regularly
260
+
* If you suspect compromise, revoke the app password immediately
250
261
251
262
**For Server Operators:**
252
263
253
-
- Secure the `config/atproto-connect/` directory with appropriate file permissions
254
-
- Monitor `security-audit.log` for suspicious activity
255
-
- Keep the `.encryption.key` file secure (never share or commit to version control)
256
-
- Regular backups of configuration files
257
-
- Update the mod regularly for security patches
264
+
* Secure the `config/atproto-connect/` directory with appropriate file permissions
265
+
* Monitor `security-audit.log` for suspicious activity
266
+
* Keep the `.encryption.key` file secure (never share or commit to version control)
267
+
* Regular backups of configuration files
268
+
* Update the mod regularly for security patches
258
269
259
270
### Token Storage
260
271
261
-
- **Location**: `config/atproto-connect/player-sessions.json`
262
-
- **Encryption**: AES-256-GCM with server-specific key
263
-
- **Contents**: Access and refresh JWTs for authenticated players
264
-
- **Security**: Encrypted at rest, owner-only file permissions
265
-
- **Lifetime**: Access tokens expire after ~2 hours, refresh tokens last longer
272
+
* **Location**: `config/atproto-connect/player-sessions.json`
273
+
* **Encryption**: AES-256-GCM with server-specific key
274
+
* **Contents**: Access and refresh JWTs for authenticated players
275
+
* **Security**: Encrypted at rest, owner-only file permissions
276
+
* **Lifetime**: Access tokens expire after ~2 hours, refresh tokens last longer
266
277
267
278
### Rate Limiting
268
279
269
280
To prevent brute-force attacks:
270
281
271
-
- **Maximum Attempts**: 3 failed login attempts
272
-
- **Time Window**: 15 minutes
273
-
- **Lockout Duration**: 30 minutes after exceeding limit
274
-
- **Tracking**: Per-player UUID and per-identifier
282
+
* **Maximum Attempts**: 3 failed login attempts
283
+
* **Time Window**: 15 minutes
284
+
* **Lockout Duration**: 30 minutes after exceeding limit
285
+
* **Tracking**: Per-player UUID and per-identifier
275
286
276
287
### Security Audit Log
277
288
278
289
All security-sensitive operations are logged to `config/atproto-connect/security-audit.log`:
279
290
280
-
- Authentication attempts (success/failure)
281
-
- Rate limit violations
282
-
- Session creation/deletion
283
-
- Token refresh operations
284
-
- Security errors
291
+
* Authentication attempts (success/failure)
292
+
* Rate limit violations
293
+
* Session creation/deletion
294
+
* Token refresh operations
295
+
* Security errors
285
296
286
297
## Configuration Files
287
298
288
299
All configuration files are stored in `config/atproto-connect/`:
289
300
290
-
- **`player-identities.json`** - UUID to DID/handle mappings (plaintext as these are both publicly accessible anyway)
291
-
- **`player-sessions.json`** - Encrypted authentication sessions
292
-
- **`.encryption.key`** - AES-256 encryption key (auto-generated, keep secure!)
293
-
- **`security-audit.log`** - Security event log
301
+
* **`player-identities.json`** - UUID to DID/handle mappings (plaintext as these are both publicly accessible anyway)
302
+
* **`player-sessions.json`** - Encrypted authentication sessions
303
+
* **`.encryption.key`** - AES-256 encryption key (auto-generated, keep secure!)
304
+
* **`security-audit.log`** - Security event log
294
305
295
306
**Important**: Never commit `.encryption.key` or `player-sessions.json` to version control!
296
307
297
308
## Development Roadmap
298
309
299
-
- [x] Design lexicon schemas for Minecraft data types
300
-
- [x] Implement AT Protocol client with Slingshot integration
301
-
- [x] Create identity linking system
302
-
- [x] Implement authentication with app passwords
303
-
- [x] Build session management with automatic token refresh
304
-
- [x] Add encryption for session storage
305
-
- [x] Implement rate limiting and security auditing
306
-
- [ ] Build data collection hooks for player statistics
307
-
- [ ] Implement authenticated record creation (writing stats)
308
-
- [ ] Add automatic stat syncing at configurable intervals
309
-
- [ ] Add privacy controls and data filtering options
310
-
- [ ] Create example AppView for displaying Minecraft data
311
-
- [ ] Implement OAuth device flow for better UX
312
-
- [ ] Add DPoP support
313
-
- [ ] Write comprehensive documentation
314
-
- [ ] Add automated tests
315
-
- [ ] Publish to Modrinth/CurseForge
310
+
* [x] Design lexicon schemas for Minecraft data types
311
+
* [x] Implement AT Protocol client with Slingshot integration
312
+
* [x] Create identity linking system
313
+
* [x] Implement authentication with app passwords
314
+
* [x] Build session management with automatic token refresh
315
+
* [x] Add encryption for session storage
316
+
* [x] Implement rate limiting and security auditing
317
+
* [ ] Build data collection hooks for player statistics
318
+
* [ ] Implement authenticated record creation (writing stats)
319
+
* [ ] Add automatic stat syncing at configurable intervals
320
+
* [ ] Add privacy controls and data filtering options
321
+
* [ ] Create example AppView for displaying Minecraft data
322
+
* [ ] Implement OAuth device flow for better UX
323
+
* [ ] Add DPoP support
324
+
* [ ] Write comprehensive documentation
325
+
* [ ] Add automated tests
326
+
* [ ] Publish to Modrinth/CurseForge
316
327
317
328
## Contributing
318
329
···
329
340
330
341
### AT Protocol
331
342
332
-
- [AT Protocol Documentation](https://atproto.com/)
333
-
- [Lexicon Specifications](https://atproto.com/specs/lexicon)
334
-
- [XRPC API Reference](https://atproto.com/specs/xrpc)
335
-
- [OAuth Specification](https://atproto.com/specs/oauth)
336
-
- [Bluesky API Docs](https://docs.bsky.app/)
343
+
* [AT Protocol Documentation](https://atproto.com/)
344
+
* [Lexicon Specifications](https://atproto.com/specs/lexicon)
345
+
* [XRPC API Reference](https://atproto.com/specs/xrpc)
346
+
* [OAuth Specification](https://atproto.com/specs/oauth)
347
+
* [Bluesky API Docs](https://docs.bsky.app/)
337
348
338
349
### Microcosm
339
350
340
-
- [Slingshot Documentation](https://slingshot.microcosm.blue/)
341
-
- [Microcosm Project](https://microcosm.blue/)
351
+
* [Slingshot Documentation](https://slingshot.microcosm.blue/)
352
+
* [Microcosm Project](https://microcosm.blue/)
342
353
343
354
### Minecraft Modding
344
355
345
-
- [Fabric Documentation](https://fabricmc.net/wiki/)
346
-
- [Fabric Language Kotlin](https://github.com/FabricMC/fabric-language-kotlin)
356
+
* [Fabric Documentation](https://fabricmc.net/wiki/)
357
+
* [Fabric Language Kotlin](https://github.com/FabricMC/fabric-language-kotlin)
347
358
348
359
## License
349
360
···
360
371
361
372
## Acknowledgments
362
373
363
-
- [Microcosm](https://microcosm.blue) for Slingshot, which makes PDS resolution fast and reliable
364
-
- The AT Protocol team for building an open, decentralized social network protocol
365
-
- The Fabric community for excellent mod development tools
366
-
- The Kotlin community for a great language and ecosystem
374
+
* [Microcosm](https://microcosm.blue) for Slingshot, which makes PDS resolution fast and reliable
375
+
* The AT Protocol team for building an open, decentralized social network protocol
376
+
* The Fabric community for excellent mod development tools
377
+
* The Kotlin community for a great language and ecosystem
367
378
368
379
---
369
380
370
-
**Version**: 0.4.0
371
-
**Repository**: `git@tangled.sh:ewancroft.uk/atproto-connect`
381
+
**Version**: 0.4.0
382
+
**Repository**: `git@tangled.sh:ewancroft.uk/atproto-connect`
372
383
**Status**: Alpha - Not Production Ready