client-ids

name	client-ids
description	Privacy-protected ID management with @ledgerhq/client-ids — DeviceId, UserId, DatadogId, export-rules.json

Client IDs Library (@ledgerhq/client-ids)

Privacy & Security — @ledgerhq/client-ids

Sensitive identifiers (DeviceId, UserId, DatadogId) must always use the @ledgerhq/client-ids library:

• Never use raw string IDs for devices, users, or analytics.
• Always use DeviceId, UserId, or DatadogId classes from @ledgerhq/client-ids/ids.
• ID values are only accessible through explicit export methods (e.g., exportUserIdForSomething()).
• Every export method must be allowlisted in libs/client-ids/export-rules.json with a justification.
• Export IDs only at system boundaries (API calls, persistence) — never in the middle of processing.
• toString() and toJSON() return [DeviceId:REDACTED] by default — this is by design.

---

Purpose

The client-ids library provides unified, privacy-protected ID management for Ledger Live. It isolates sensitive identifiers (DeviceId, UserId, DatadogId) and prevents accidental exposure through logging or serialization.

Core Principles

1. All ID Usage Must Go Through This Library

• Never create raw string IDs for devices, users, or analytics
• Always use DeviceId, UserId, or DatadogId classes from @ledgerhq/client-ids/ids
• IDs are protected by Symbols and automatically redacted in logs/JSON

2. Privacy Protection

• IDs are stored in Symbol fields to prevent accidental access
• toString() and toJSON() return [DeviceId:REDACTED] by default
• Actual ID values are only accessible through explicit export methods

3. Explicit Use Cases

• Every ID usage must be explicitly declared through a dedicated export method (e.g., exportUserIdForSomethingSomething())
• Export methods represent specific, documented use cases and can only be called from allowlisted files
• The export-rules.json file serves as a registry of all allowed use cases, ensuring each ID export is intentional and justified
• Export at the last end: Only export IDs at system boundaries (API calls, persistence) - never in the middle of processing
• The check-export-rules.mjs script enforces that all ID exports match declared use cases at build time

Usage Requirements

Creating IDs

Two scenarios:

1. Using an existing ID for a new use case:

• Add a new export method (e.g., exportUserIdForSomethingSomething())
• Add your file to libs/client-ids/export-rules.json allowlist:

  {
    "libs/client-ids/src/ids/UserId.ts": {
      "exportUserIdForSomethingSomething": [
        "your/new/file/path.ts"  // Add here
      ]
    }
  }
  

• Justify the usage in a code comment explaining why this file needs to export the ID
• Use the method only from the allowlisted file (at the system boundary)

2. Introducing a new kind of ID:

• Create a new class in libs/client-ids/src/ids/ (e.g., NewId.ts)
• Follow the pattern from DeviceId.ts: Symbol storage, redacted toString/toJSON, export methods
• Add export methods with allowlist rules in export-rules.json

import { DeviceId } from "@ledgerhq/client-ids/ids";

// ✅ Correct: Use the library
const deviceId = DeviceId.fromString("device-123");

// ❌ Wrong: Don't use raw strings
const deviceId = "device-123"; // BAD