atproto-pds-rotation-key-batch
PowerShell scripts for managing AT Protocol (Bluesky) rotation keys and personal recovery keys for Personal Data Server (PDS) instances.
Star
Fork
Watch
2 1 0
Files
.gitignore
README.md
Test-AtprotoRotationKey.ps1
Update-AtprotoRotationKey.ps1
README.md

AT Protocol PDS Rotation Key Batch Manager #

PowerShell scripts for managing AT Protocol (Bluesky) rotation keys and personal recovery keys for Personal Data Server (PDS) instances.

Overview #

This project provides PowerShell scripts to help users manage their AT Protocol identity rotation keys. These are essential for account recovery and maintaining control over your decentralized identity.

Scripts #

🔄 Update-AtprotoRotationKey.ps1 #

Purpose: Update rotation keys for your AT Protocol identity (did:plc) via XRPC on your PDS.

Features:

  • Authenticates with your PDS (e.g., eurosky.social)
  • Requests security token via email (requestPlcOperationSignature)
  • Generates new secp256k1 rotation keys or imports existing ones
  • Maintains existing PDS keys as secondary keys
  • Submits signed operations to plc.directory
  • Comprehensive verification process

Usage:

# Run with default parameters (marcomaroni.it on eurosky.social)
."Update-AtprotoRotationKey.ps1"

# Specify custom handle and PDS
."Update-AtprotoRotationKey.ps1" -Handle "your.handle" -PdsUrl "https://your-pds.example.com"

🧪 Test-AtprotoRotationKey.ps1 #

Purpose: Verify the validity of rotation keys for AT Protocol identities.

Features:

  • Derives public keys from private keys (secp256k1 and P-256)
  • Validates did:key format public keys
  • Checks current rotation key status on plc.directory
  • Searches historical audit log for past key usage
  • Provides detailed status reporting

Usage:

# Test with identity and key
."Test-AtprotoRotationKey.ps1" -Identity "your.handle" -Key "did:key:z..."

# Test with private key (hex or base64)
."Test-AtprotoRotationKey.ps1" -Identity "did:plc:..." -Key "0x..."

# Interactive mode (no parameters)
."Test-AtprotoRotationKey.ps1"

Requirements #

  • PowerShell 5.1+ (Windows) or PowerShell 7+ (Cross-platform)
  • Internet connectivity for API calls to PDS and plc.directory
  • Valid AT Protocol account with PDS access
  • .NET Framework or .NET Core for cryptographic operations

Installation #

  1. Clone or download this repository
  2. Run in PowerShell:
    # Navigate to the project directory
cd atproto-pds-rotation-key-batch

# Run scripts directly
.\Update-AtprotoRotationKey.ps1
.\Test-AtprotoRotationKey.ps1

Security Notes #

⚠️ CRITICAL - Key Management #

  • Private keys are sensitive: When generating new rotation keys, the script displays private keys that must be saved securely in a password manager or cold storage
  • Never share private keys: Anyone with access to your private rotation key can take control of your AT Protocol identity
  • Backup verification: Always verify that generated keys are properly backed up before proceeding

Authentication #

  • Scripts require your main account password (not app passwords)
  • Two-factor authentication (2FA) is supported
  • Security tokens are sent to your registered email address

Use Cases #

1. Account Recovery Setup #

Set up personal rotation keys to ensure you can recover your account even if you lose access to your PDS.

2. PDS Migration #

When switching PDS providers, update rotation keys to maintain control during and after migration.

3. Security Audit #

Verify that your current rotation keys are properly registered and valid.

4. Key Rotation #

Regularly update your rotation keys for enhanced security.

AT Protocol Background #

What are Rotation Keys? #

Rotation keys are cryptographic keys that allow you to:

  • Sign operations that change your PDS endpoint
  • Recover your account if you lose access to your current PDS
  • Authorize changes to your decentralized identity

Key Hierarchy #

  • Index 0: Primary recovery key (your personal key)
  • Indices 1, 2, ...: Secondary PDS keys (maintained by your PDS provider)

Script Details #

Cryptographic Implementation #

Both scripts use embedded C# code for cryptographic operations:

  • secp256k1: Used by AT Protocol (same curve as Bitcoin/Ethereum)
  • P-256: Alternative curve support
  • Base58 encoding: For did:key format conversion

API Endpoints Used #

  • com.atproto.server.createSession - Authentication
  • com.atproto.identity.getRecommendedDidCredentials - Get recommended credentials
  • com.atproto.identity.requestPlcOperationSignature - Request operation signature
  • com.atproto.identity.signPlcOperation - Sign operation with token
  • com.atproto.identity.submitPlcOperation - Submit to plc.directory
  • plc.directory/{did}/log/audit - Audit log retrieval

Examples #

Generating a New Recovery Key #

."Update-AtprotoRotationKey.ps1" -Handle "your.handle" -PdsUrl "https://your-pds.com"
# Follow prompts to generate and save new key

Verifying an Existing Key #

."Test-AtprotoRotationKey.ps1" -Identity "your.handle" -Key "did:key:zYourPublicKey..."

Testing with Private Key #

."Test-AtprotoRotationKey.ps1" -Identity "your.handle" -Key "yourPrivateKeyHexOrBase64"

Troubleshooting #

Common Issues #

  1. Authentication failures: Ensure you're using the main account password, not an app password
  2. 2FA not working: Check your email for the security code
  3. API timeouts: PDS might be slow; try again later
  4. Key format errors: Ensure private keys are 32 bytes (64 hex chars or valid Base64)

Debug Mode #

Run scripts with -Verbose flag for detailed output:

."Update-AtprotoRotationKey.ps1" -Verbose

Contributing #

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Submit a pull request

License #

MIT License - See LICENSE for details.

Disclaimer #

This software deals with cryptographic keys and account access. Use at your own risk. The authors are not responsible for lost keys, account compromises, or any other issues arising from the use of these scripts.

Resources #

Maintainer: Marco Maroni (@marcomaroni.it)

Last updated: 2026-10-03