Stable ID System

Nexus 3.0.5 introduces stable IDs for multi-tenant support.

ID Formats

Why Stable IDs?

Problem: Keys used usernames like track:christopher:project:abc - What if 5 different "Chris" users at a client? - Username changes break all references - Hard to query across environments

Solution: Stable IDs are: - Unique across the system - Never change (even if username changes) - Grepable by prefix (u_, s_, l_)

User Resolution

Location: /opt/mcp-servers/shared/user_helper.py

from user_helper import resolve_user, get_user_helper

# Resolve any identifier to stable ID
stable_id = resolve_user('chris')  # Returns 'u_z1p5'
stable_id = resolve_user('christopher')  # Returns 'u_z1p5'
stable_id = resolve_user('u_z1p5')  # Returns 'u_z1p5'

# Get current authenticated user
helper = get_user_helper()
current = helper.get_current_user()  # Returns 'u_z1p5'

# Get display name
name = helper.get_display_name('u_z1p5')  # Returns 'Chris'

Resolution Priority

1. Already a stable ID (u_XXXX) → return as-is
2. Username match → return stable_id
3. Alias match → return stable_id
4. Name match (preferredName/firstName/lastName) → return stable_id

Key Format

New format: environment:u_XXXX:timestamp:type:id

Examples: - track:u_z1p5:20260102:project:c3c50944 - kb:u_z1p5:20260102:node:37be7989 - sess:u_z1p5:20260102_1900_xyz1

Migration

Script: /opt/mcp-servers/shared/migrate_to_stable_id.py

# Dry run
python3 migrate_to_stable_id.py

# Migrate (keeps old keys)
python3 migrate_to_stable_id.py --migrate

# Migrate and delete old keys
python3 migrate_to_stable_id.py --migrate --delete

Current Users