jollywhoppers.com/socialsync at main

A Fabric mod for Minecraft 1.21.10 that bridges the game with the AT Protocol, enabling decentralized data synchronization and social features.

Project Status#

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.

Affiliation & Hosting#

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.

The project is now maintained by the Jollywhoppers coding group as a whole.

The code lives at https://tangled.org/jollywhoppers.com/socialsync.

The project is hosted on Tangled.

Overview#

Social 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.

Current Features#

Identity Linking & Authentication ✓#

Players can link their Minecraft accounts to their AT Protocol identities and authenticate to enable data syncing:

Basic Commands:

/atproto link <handle or DID> - Link your Minecraft UUID to your AT Protocol identity (no login required)
/atproto login <handle> <app-password> - Authenticate to enable data syncing
/atproto logout - Remove authentication (keeps identity link)
/atproto unlink - Remove identity link and authentication
/atproto whoami - View your linked identity and auth status
/atproto status - Quick status check
/atproto whois <player or handle> - Look up another player's identity

Example Workflow:

# 1. Link your identity (read-only)
/atproto link alice.bsky.social
✓ Successfully linked to AT Protocol!
  Handle: alice.bsky.social
  DID: did:plc:abcdef123456
  PDS: https://morel.us-east.host.bsky.network

# 2. Authenticate with an App Password
/atproto login alice.bsky.social abcd-1234-efgh-5678
✓ Successfully authenticated!
You can now sync your Minecraft data to AT Protocol!

# 3. Check your status
/atproto whoami
━━━ Your AT Protocol Identity ━━━
Handle: alice.bsky.social
DID: did:plc:abcdef123456
Linked: 5 minutes ago
Last Verified: 5 minutes ago

Authentication: ✓ Active
You can sync data to AT Protocol

Security Features#

The mod implements enterprise-grade security measures to protect player data and prevent abuse:

AES-256-GCM Encryption: Session data encrypted at rest with server-specific keys
Rate Limiting: 3 authentication attempts per 15 minutes, 30-minute lockout on abuse
Security Audit Logging: All sensitive operations logged for monitoring
Sanitized Error Messages: No sensitive data exposed in error messages or logs
Restricted File Permissions: Owner-only access to configuration files
Atomic File Writes: Prevents corruption during saves
Thread-Safe Operations: Concurrent access protection for all shared data
Automatic Token Refresh: Access tokens refreshed before expiration
Path Validation: Protection against directory traversal attacks

All passwords are handled securely - app passwords are never logged or stored (only the resulting JWT tokens are kept).

Key Features#

Slingshot Integration: Uses Slingshot by Microcosm for fast, cached PDS resolution
App Password Support: Secure authentication using AT Protocol app passwords (never use your main password!)
Automatic Token Refresh: Access tokens are automatically refreshed before expiration
Multi-PDS Support: Works with any AT Protocol PDS, not just Bluesky
Persistent Sessions: Authentication survives server restarts
Encrypted Storage: Session data protected with AES-256-GCM encryption

Getting an App Password#

Go to your AT Protocol account settings (e.g., Bluesky Settings → Privacy and Security → App Passwords)
Create a new app password with a descriptive name (e.g., "Minecraft Server")
Copy it immediately (you won't see it again!)
Use it in /atproto login
Never share your app password or use your main account password!

Future Possibilities#

Automatic stat syncing at configurable intervals
Achievement announcements via AT Protocol feeds
Cross-server player reputation systems
Privacy controls for what data gets synced
In-game social features tied to AT Protocol identities

Technical Stack#

Minecraft Version: 1.21.10
Mod Loader: Fabric API
Protocol: AT Protocol (atproto)
Language: Kotlin (with Java interop)
Build System: Gradle 8.x
Dependencies:
- Fabric Loader 0.18.3
- Fabric API 0.138.4+1.21.10
- Fabric Language Kotlin 1.13.8+kotlin.2.3.0
- kotlinx-serialization for JSON handling
- kotlinx-coroutines for async operations
Identity Resolution: Slingshot by Microcosm
Authentication: AT Protocol OAuth/App Passwords

Installation#

For Users#

Install Fabric Loader for Minecraft 1.21.10
Download and install Fabric API version 0.138.4+1.21.10 or compatible
Download and install Fabric Language Kotlin version 1.13.8+kotlin.2.3.0 or compatible
Place the social-sync JAR in your mods folder
Launch the game and use /atproto help to see available commands

For Developers#

Clone the repository:

git clone git@tangled.sh:jollywhoppers.com/socialsync
cd socialsync

Build the project:

./gradlew build

The built JAR will be in build/libs/.

For development with auto-reload:

./gradlew runClient

Project Structure#

src/main/
├── kotlin/com/jollywhoppers/
│   ├── Atprotoconnect.kt                    # Main mod initializer
│   └── atproto/
│       ├── AtProtoClient.kt                 # HTTP client with Slingshot integration
│       ├── AtProtoSessionManager.kt         # Authentication & token management
│       ├── AtProtoCommands.kt               # Command handlers
│       ├── PlayerIdentityStore.kt           # UUID<->DID mapping storage
│       ├── security/
│       │   ├── RateLimiter.kt              # Rate limiting for auth attempts
│       │   ├── SecurityAuditor.kt          # Security event logging
│       │   └── SecurityUtils.kt            # Cryptography & path validation
│       └── examples/
│           └── RecordCreationExample.kt    # Example code for data syncing
└── resources/
    ├── fabric.mod.json                      # Mod metadata
    └── lexicons/                            # Lexicon schemas
        ├── README.md                        # Lexicon documentation
        ├── com.jollywhoppers.minecraft.defs.json
        ├── com.jollywhoppers.minecraft.player.profile.json
        ├── com.jollywhoppers.minecraft.player.stats.json
        ├── com.jollywhoppers.minecraft.player.session.json
        ├── com.jollywhoppers.minecraft.achievement.json
        ├── com.jollywhoppers.minecraft.leaderboard.json
        └── com.jollywhoppers.minecraft.server.status.json

Lexicon Schemas#

The mod defines several AT Protocol lexicon schemas under the com.jollywhoppers.minecraft.* namespace:

Player Profile (literal:self) - Links Minecraft UUIDs to AT Protocol DIDs with privacy controls
Player Stats (tid) - Snapshots of player statistics for leaderboards
Player Sessions (tid) - Play session tracking (join/leave times)
Achievements (tid) - Records of earned achievements/advancements
Leaderboards (tid) - Pre-computed leaderboard entries
Server Status (literal:self) - Server information and status

See src/main/resources/lexicons/README.md for detailed schema documentation.

Architecture#

Player Commands (/atproto login, /atproto link, etc.)
    ↓
AtProtoCommands (Kotlin Coroutines)
    ↓
┌────────────────────────────────────────┐
│    AtProtoSessionManager               │
│    • Authentication & Token Storage     │
│    • AES-256-GCM Encryption            │
│    • Automatic Token Refresh           │
└────────────────────────────────────────┘
    ↓
┌────────────────────────────────────────┐
│         AtProtoClient                  │
│    • HTTP + XRPC + Slingshot          │
│    • Identity Resolution               │
└────────────────────────────────────────┘
    ↓
┌────────────────────────────────────────┐
│    Security Layer                      │
│    • RateLimiter (3/15min)            │
│    • SecurityAuditor (Event Logging)   │
│    • SecurityUtils (Crypto & Validation)│
└────────────────────────────────────────┘
    ↓
┌────────────────────────────────────────┐
│    Slingshot (Microcosm Blue)         │
│    Fast PDS Resolution & Caching       │
└────────────────────────────────────────┘
    ↓
AT Protocol Network
    - Player's PDS (Data & Auth)
    - plc.directory (DID Resolution)
    ↓
Local Storage
    - player-identities.json (UUID↔DID mappings)
    - player-sessions.json (Encrypted auth tokens)
    - .encryption.key (AES-256 key)
    - security-audit.log (Security events)

Authentication & Security#

How It Works#

Link Identity: Players link their Minecraft UUID to their AT Protocol DID (read-only, no login required)
Authenticate: Players log in with their handle and an app password to create an authenticated session
Token Management: The mod stores JWT access and refresh tokens securely with AES-256-GCM encryption
Auto-Refresh: Access tokens are automatically refreshed before expiration
Data Syncing: Authenticated players will be able to sync their Minecraft data to their PDS (coming soon)

Security Best Practices#

For Players:

Always use App Passwords, never main account passwords
Create a unique app password for each Minecraft server
Revoke unused app passwords regularly
If you suspect compromise, revoke the app password immediately

For Server Operators:

Secure the config/atproto-connect/ directory with appropriate file permissions
Monitor security-audit.log for suspicious activity
Keep the .encryption.key file secure (never share or commit to version control)
Regular backups of configuration files
Update the mod regularly for security patches

Token Storage#

Location: config/atproto-connect/player-sessions.json
Encryption: AES-256-GCM with server-specific key
Contents: Access and refresh JWTs for authenticated players
Security: Encrypted at rest, owner-only file permissions
Lifetime: Access tokens expire after ~2 hours, refresh tokens last longer

Rate Limiting#

To prevent brute-force attacks:

Maximum Attempts: 3 failed login attempts
Time Window: 15 minutes
Lockout Duration: 30 minutes after exceeding limit
Tracking: Per-player UUID and per-identifier

Security Audit Log#

All security-sensitive operations are logged to config/atproto-connect/security-audit.log:

Authentication attempts (success/failure)
Rate limit violations
Session creation/deletion
Token refresh operations
Security errors

Configuration Files#

All configuration files are stored in config/atproto-connect/:

player-identities.json - UUID to DID/handle mappings (plaintext as these are both publicly accessible anyway)
player-sessions.json - Encrypted authentication sessions
.encryption.key - AES-256 encryption key (auto-generated, keep secure!)
security-audit.log - Security event log

Important: Never commit .encryption.key or player-sessions.json to version control!

Development Roadmap#

Design lexicon schemas for Minecraft data types
Implement AT Protocol client with Slingshot integration
Create identity linking system
Implement authentication with app passwords
Build session management with automatic token refresh
Add encryption for session storage
Implement rate limiting and security auditing
Build data collection hooks for player statistics
Implement authenticated record creation (writing stats)
Add automatic stat syncing at configurable intervals
Add privacy controls and data filtering options
Create example AppView for displaying Minecraft data
Implement OAuth device flow for better UX
Add DPoP support
Write comprehensive documentation
Add automated tests
Publish to Modrinth/CurseForge

Contributing#

This project is in active development. If you're interested in contributing:

Check the Issues page for open tasks
Fork the repository
Create a feature branch
Submit a pull request with a clear description

Please follow Kotlin coding conventions and include tests for new features.

Resources#

AT Protocol#

Microcosm#

Minecraft Modding#

License#

AGPL-3.0 – GNU Affero General Public License v3

This project is free software: you may use, modify, and distribute it, including for commercial purposes. If 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.

This ensures that improvements and extensions to the project remain open and available to the community.

Disclaimer#

This 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.

Acknowledgments#

Microcosm for Slingshot, which makes PDS resolution fast and reliable
The AT Protocol team for building an open, decentralized social network protocol
The Fabric community for excellent mod development tools
The Kotlin community for a great language and ecosystem

Version: 0.4.0 Repository: git@tangled.sh:jollywhoppers.com/socialsync Status: Alpha - Not Production Ready

Clone this repository

Social Sync#