SOP-002: Device Pairing

DOCUMENT CONTROL

Field	Value
SOP ID	SOP-002
Version	1.0
Status	Active
Last Updated	December 2025

Purpose

This SOP covers the secure pairing process between your mobile device and development machine, including QR code scanning and manual pairing methods.

How Pairing Works

Happy Coder uses end-to-end encryption with a shared secret key:

┌─────────────────────────────────────────────────────────────┐
│                    PAIRING PROCESS                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────┐    QR Code    ┌─────────────┐                 │
│  │  CLI    │──────────────▶│  Mobile App │                 │
│  │(Desktop)│   Contains    │   (Phone)   │                 │
│  └────┬────┘  Secret Key   └──────┬──────┘                 │
│       │                           │                         │
│       │    Both devices now       │                         │
│       │    share encryption key   │                         │
│       ▼                           ▼                         │
│  ┌─────────────────────────────────────┐                   │
│  │     Encrypted Communication         │                   │
│  │     Server cannot read data         │                   │
│  └─────────────────────────────────────┘                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Procedure Flowchart

┌───────────────────┐
│      START        │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│ Run happy --auth  │
└─────────┬─────────┘
          │
          ▼
    ┌─────────────┐
    │ QR Code     │
    │ Displayed?  │
    └──────┬──────┘
           │
    Yes ◀──┴──▶ No
    │            │
    ▼            ▼
┌─────────┐  ┌─────────────┐
│ Scan QR │  │ Use Manual  │
│ Code    │  │ Entry Code  │
└────┬────┘  └──────┬──────┘
     │              │
     └──────┬───────┘
            ▼
┌───────────────────┐
│ Verify Connection │
│ in Settings       │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│    COMPLETE       │
└───────────────────┘

Step-by-Step Procedure

Method 1: QR Code Pairing (Recommended)

Step 1: Start the authentication process:

happy --auth

Step 2: The terminal displays a QR code containing your encryption key.

Step 3: Open the Happy Coder mobile app.

Step 4: Tap the "Scan" or "Add Device" button.

Step 5: Point your camera at the QR code.

Step 6: Wait for confirmation message.

Method 2: Manual Code Entry

If QR scanning fails:

Step 1: Run with no-qr flag:

happy --no-qr

Step 2: Copy the displayed alphanumeric code.

Step 3: In the mobile app, select "Manual Entry".

Step 4: Type or paste the code.

Step 5: Confirm pairing.

QR Code Troubleshooting

Problem	Solution
Code won't scan	Increase screen brightness to maximum
Camera won't focus	Clean camera lens, ensure good lighting
Code too small	Run happy --qr-size large
Expired code	Generate new code with happy --auth

Security Considerations

Zero-Knowledge Architecture

• The relay server NEVER sees your encryption key
• Keys are generated locally and shared only via QR code
• All data in transit is encrypted before leaving your device
• Even if the server is compromised, your data remains secure

What Gets Shared

Shared	NOT Shared
Encrypted blobs	Plaintext code
Public key hash	Actual public key
Connection metadata	Message content

Connecting Multiple Devices

You can connect multiple devices to the same account:

1. Run happy --auth for each new device
2. Each device gets its own secure channel
3. All devices sync the same sessions

Best Practice

Connect ALL your devices:

• Development laptop
• Desktop workstation
• VPS/cloud instances
• Raspberry Pi or home servers
• All web browsers

Verification Checklist

• [ ] QR code displayed in terminal
• [ ] Mobile app shows "Connected" status
• [ ] Test message successfully sent
• [ ] Push notifications working
• [ ] Session list visible on mobile

Related Documents

• SOP-001: Installation & Setup
• SOP-003: Session Management