Pubky Ring

Identity Manager for Pubky

Your keychain for the Pubky ecosystem. Manage your pubkys, authorize services, and stay in control—no accounts, no passwords.

Overview

Pubky Ring is the key manager and identity application for the Pubky ecosystem. It’s a native mobile app (iOS and Android) that lets you securely manage your pubkys—the public keys that power your presence across decentralized applications.

Core Philosophy:

Self-custodial: You control your keys, no one else
No accounts: No usernames, no passwords, no registration
No tracking: Your identity data stays on your device
Interoperable: Works seamlessly with Pubky apps

What You Can Do

Identity Management

Create and manage multiple pubkys: Each identity is a separate public key
Organize identities: Label and categorize your different personas
Switch between identities: Seamlessly use different pubkys for different contexts
Backup and restore: Secure backup of your keys with recovery options

Service Authorization

Authorize apps: Grant specific permissions to Pubky applications
Revoke access: Instantly remove app permissions
Session management: View and control all active sessions
Granular permissions: Choose what each app can access

Cross-Device Sync

Sync across devices: Keep your identities consistent between phone and tablet
Secure synchronization: Encrypted sync using Homeserver storage
Multi-device sessions: Use the same identity on multiple devices simultaneously

Key Derivation Services

Ed25519 identity keys: Primary Pubky identity keys
X25519 Noise keys: Automatically derived for encrypted communication
Session keys: Temporary keys for app sessions
Payment keys: Support for payment protocol integration

Architecture

Native Mobile App

Pubky Ring is built with React Native, providing:

Native performance on iOS and Android
Platform-specific secure storage (Keychain/Keystore)
Deep linking support for app integration
Background services for session management

Key Storage

iOS:

Keychain Services for secure key storage
Hardware-backed encryption when available
Biometric authentication (Face ID/Touch ID)
Secure Enclave integration

Android:

EncryptedSharedPreferences with hardware-backed keystore
Biometric authentication (fingerprint/face unlock)
StrongBox Keymaster support on compatible devices

Session Management

Pubky Ring manages authentication sessions for connected apps:

Session creation with capability tokens
Session expiration and renewal
Multi-device session coordination
Session revocation

Deep Linking & Integration

Paykit Connect (`paykit-connect://`)

Pubky Ring provides deep link handlers for Paykit integration:

paykit-connect://[callback-url]?[parameters]

Flow:

Bitkit (or other wallet) requests Paykit authorization
Opens Pubky Ring via deep link
User approves in Pubky Ring
Ring derives Noise keys and creates session
Returns encrypted session data via callback
Wallet receives authorization and can use Paykit

Parameters:

callback_url: Where to return authorization data
app_name: Requesting application name
permissions: Requested capabilities
session_duration: Requested session lifetime

Noise Key Derivation

Pubky Ring derives X25519 encryption keys from Ed25519 identity keys using HKDF:

Ed25519 Identity Key (32 bytes)
    ↓ HKDF-SHA256 with context "pubky-noise-v1"
X25519 Static Key (32 bytes)
    ↓ Used for Noise Protocol IK handshake
Encrypted Communication Channel

This allows apps to:

Use a single identity for both signing and encryption
Derive consistent encryption keys across devices
Maintain forward secrecy through ephemeral keys
Authenticate with Pubky identity system

Integration with Paykit

Paykit uses Pubky Ring for:

Session Creation:

User authenticates in Ring
Ring generates session credentials
Encrypted session returned to wallet
Wallet can now use Paykit features

Key Management:

Ring stores master Ed25519 key
Derives X25519 keys for Noise channels
Manages session rotation
Handles key backup/recovery

Cross-Device Authentication:

Ring polls relay for pending auth requests
User approves on trusted device
Session synchronized via encrypted relay
Wallet receives authorization on new device

See the Bitkit + Paykit Integration Master Guide for detailed integration documentation.

Technical Specifications

Supported Platforms

iOS: 13.0+
Android: API level 24+ (Android 7.0)
React Native: 0.74+

Storage Format

Keys are stored in encrypted format:

{
  "version": "1",
  "identities": [
    {
      "id": "unique-id",
      "label": "My Main Identity",
      "publicKey": "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo",
      "created": "2024-01-01T00:00:00Z",
      "lastUsed": "2024-01-05T12:30:00Z"
    }
  ],
  "sessions": [...],
  "settings": {...}
}

Private keys never leave the secure storage.

Security Model

Threat Protection:

✅ Key theft via malware (hardware-backed storage)
✅ Unauthorized app access (user approval required)
✅ Man-in-the-middle (cryptographic authentication)
✅ Session hijacking (time-limited sessions, rotation)

Trust Assumptions:

Device OS is secure and not compromised
User approves legitimate authorization requests
Biometric authentication is properly secured
Secure storage implementation is sound

Attack Surface:

Deep link handlers (validated and sanitized)
Session relay communication (encrypted)
Backup/restore process (user must secure backup)

User Experience

Onboarding Flow

Install Pubky Ring from app store
Create first identity - generates Ed25519 key pair
Set up security - enable biometrics, set PIN
Backup keys - secure recovery phrase or encrypted backup
Connect apps - authorize Pubky applications

Daily Usage

Quick authorization: Biometric approval for app requests
Session overview: See all connected apps and active sessions
Identity switching: Tap to switch between personas
Permission management: Review and adjust app permissions

Privacy Features

Local-first: All data stored on device
No telemetry: No analytics or tracking
No cloud sync (unless user enables encrypted sync)
Anonymous: No registration, no personal information required

Development & Testing

Local Development

# Clone repository
git clone https://github.com/pubky/pubky-ring
cd pubky-ring

# Install dependencies
yarn install
cd ios && pod install && cd ..

# Run on iOS
yarn ios

# Run on Android
yarn android

E2E Testing

Pubky Ring includes Appium/WebdriverIO tests:

# Install test drivers
yarn e2e:drivers

# Run Android tests
yarn e2e:android

# Run iOS tests
yarn e2e:ios

Environment Variables

ANDROID_APP: Path to APK for testing
IOS_APP: Path to .app for testing
AVD: Android Virtual Device name
IOS_SIM: iOS Simulator name

Relationship to Pubky Ecosystem

Pubky Ring is the identity foundation for:

Pubky Core

Manages Ed25519 identity keys
Publishes keys via PKARR to Mainline DHT
Authorizes apps to store data on Homeservers

Pubky App

Provides identity for social graph
Authorizes content publishing
Manages following/follower relationships

Paykit

Creates payment sessions
Derives Noise encryption keys
Authorizes payment operations
Manages subscription agreements

Pubky Noise

Derives X25519 keys for encryption
Manages Noise endpoint publishing
Handles encrypted channel sessions

Repository

Official: github.com/pubky/pubky-ring

Release Verification

Verify APK Authenticity

# Import maintainer's GPG key
gpg --import public-key.asc

# Verify signature
gpg --verify app-release.apk.asc app-release.apk

# Verify checksum
gpg --verify SHA256SUMS.asc
sha256sum -c SHA256SUMS

Always verify releases to ensure you’re installing authentic, untampered builds.

Roadmap & Future Features

Planned Enhancements:

Multi-signature support for shared identities
Hardware wallet integration
Decentralized identity recovery (social recovery)
Advanced permission models
Identity attestations and verification
Integration with more Pubky applications

Research Areas:

Zero-knowledge proofs for privacy-preserving authorization
Threshold cryptography for distributed key management
Post-quantum cryptography readiness
Advanced session policies

Pubky Ring is the secure, self-custodial foundation for your presence in the Pubky ecosystem. Download it to get started with decentralized identity management.