Trust Codes

​

Overview

​

What Are Trust Codes?

• Reusable: Unlike many recovery codes, Ave trust codes can be used multiple times
• Limited quantity: You receive 2 trust codes per account by default
• Encrypted storage: Only hashed versions are stored on the server
• Master key access: Each code can decrypt your encrypted master key backup

​

Trust Code Format

• 5 segments of 5 characters each
• Separated by hyphens: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
• Characters exclude confusing symbols (no 0, O, I, or 1)
• Case-insensitive when entering
• Whitespace and separators are ignored during verification

​

When You Receive Trust Codes

​

During Registration

1. Complete identity creation
2. Set up your first passkey
3. Answer 3 security questions (now deprecated)
4. Save your 2 trust codes - displayed once
5. Check the confirmation box to proceed

​

After Regeneration

• Invalidate all existing trust codes
• Generate 2 new codes
• Re-encrypt your master key backup with the new codes
• Display the new codes once (save them immediately)

​

Using Trust Codes

​

For Full Account Recovery

1. Go to the login page
2. Enter your handle
3. Click “Use a trust code”
4. Enter one of your trust codes
5. Complete device information
6. You’ll be logged in with access to your encrypted data

​

For Master Key Recovery

1. System will prompt for master key recovery
2. Enter a trust code when prompted
3. Your master key backup is decrypted client-side
4. Master key is stored locally for future use

​

How Trust Codes Work

​

Generation Process

// Server-side: Generate random trust code
const code = generateTrustCode(); // e.g., "A3K9L-QW7R2-N5M8P-..."
const hash = hashTrustCode(code);  // SHA-256 hash for storage

// Store only the hash
await db.insert(trustCodes).values({
  userId: user.id,
  codeHash: hash,
});

​

Verification Process

// When user enters trust code
const normalized = code.toUpperCase().replace(/[^A-Z0-9]/g, "");
const inputHash = createHash("sha256").update(normalized).digest("hex");

// Compare against stored hash
const matches = inputHash === storedHash;

​

Master Key Decryption

1. User enters trust code
2. Server verifies the hash matches
3. Server returns encrypted master key backup
4. Client-side: Trust code derives decryption key
5. Client-side: Master key is decrypted and stored locally

​

Security Properties

​

What’s Protected

• Hash-only storage: Server stores SHA-256(normalized_code), not plaintext
• Client-side decryption: Master key decryption never happens on server
• Normalization: Uppercase, strip separators to prevent timing attacks
• Reusable design: No single-use limitation reduces lockout risk

​

Activity Logging

{
  "action": "login",
  "details": {
    "method": "trust_code",
    "deviceName": "Chrome on Mac",
    "isNewDevice": true
  },
  "severity": "warning"
}

{
  "action": "trust_code_failed",
  "details": {
    "reason": "invalid_code",
    "trustCodesCount": 2
  },
  "severity": "warning"
}

​

Regenerating Trust Codes

​

From the Dashboard

1. Navigate to Dashboard → Security
2. View current trust code count
3. Click “Regenerate trust codes”
4. Confirm the warning (old codes will be invalidated)
5. Save the 2 new codes immediately

​

API Endpoint

POST /api/security/trust-codes/regenerate
Authorization: Bearer <session_token>

{
  "codes": [
    "A3K9L-QW7R2-N5M8P-T4X6Z-H2J5N",
    "B7M3Q-P9K4W-R8L2C-V5N7Y-F3G6D"
  ]
}

​

Best Practices

​

Storage Recommendations

1. Write them down physically - Store in a safe or lockbox
2. Use a password manager - Encrypted vault with family sharing
3. Separate locations - Keep the 2 codes in different secure places
4. Never email or text - Avoid digital transmission unless encrypted

​

When to Regenerate

• Compromised storage: If your code storage may be exposed
• Shared accidentally: If you showed a code to someone unintentionally
• Regular rotation: Consider annual regeneration for high-security accounts
• Before major changes: When changing primary email or security setup

​

Recovery Planning

• Test recovery flow: Verify you can actually use a trust code
• Document location: Note where each code is stored (without storing the code itself)
• Backup plan: Have multiple recovery methods (passkeys + trust codes)
• Trusted contact: Consider secure sharing with a family member or executor

​

Troubleshooting

​

”Invalid trust code” Error

1. Typo in code - Trust codes are case-insensitive, but characters must match
2. Code already regenerated - Old codes are invalidated when new ones are created
3. No codes registered - Account may not have trust codes set up

• Double-check each character
• Hyphens are optional when entering
• If all codes fail, use device approval or contact support

​

”No trust codes found” Error

1. Log in using a passkey or device approval
2. Go to Dashboard → Security
3. Click “Regenerate trust codes”
4. Save the new codes securely

​

Trust Code Not Working After Login

1. Ensure you’re entering the same code used during registration
2. Check that encryptedMasterKeyBackup exists in your user record
3. Verify client-side decryption logic is working (check browser console)

​

Related Topics

• Recovery Methods - Alternative account recovery options
• Session Management - Understanding session security
• Best Practices - Comprehensive security guidance