Identity Resolver

# identity-resolver

**Canonical user identity resolution across messaging channels**

## Description

Resolves multi-channel user identities (Telegram, WhatsApp, Discord, web, etc.) to canonical user IDs, preventing state fragmentation when users interact via multiple channels.

**Problem it solves:** Without identity resolution, a user messaging via Telegram and WhatsApp appears as two different users, causing fragmented memory, access control, and per-user state across skills.

**Solution:** Maps all channel identities to one canonical user ID automatically.

## Installation

**Prerequisites:** Install `uv` if not already installed:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Install the skill:**
```bash
cd /path/to/openclaw/workspace

# Via ClawHub (recommended)
clawhub install identity-resolver

# Or via Git
git clone https://github.com/clawinfra/identity-resolver skills/identity-resolver
```

## Quick Start

### For End Users

```bash
# Initialize identity map (auto-detects owner from USER.md)
cd /path/to/workspace
uv run python skills/identity-resolver/scripts/identity_cli.py init

# Verify your identity
uv run python skills/identity-resolver/scripts/identity_cli.py resolve \
  --channel telegram --user-id YOUR_TELEGRAM_ID
# Output: your-canonical-id

# List all registered identities
uv run python skills/identity-resolver/scripts/identity_cli.py list
```

### For Skill Developers

Add to your skill's Python code:

```python
import sys
from pathlib import Path

# Import identity resolver
sys.path.insert(0, str(Path.cwd() / "skills" / "identity-resolver" / "scripts"))
from identity import resolve_canonical_id

# Get canonical user ID from session context
import os
channel = os.getenv("OPENCLAW_CHANNEL")  # e.g., "telegram"
user_id = os.getenv("OPENCLAW_USER_ID")   # e.g., "123456789"

canonical_id = resolve_canonical_id(channel, user_id)
# Use canonical_id for all user-specific operations

# Example: User-specific memory file
memory_file = f"...

# identity-resolver

**Solve multi-channel identity fragmentation in OpenClaw**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-24%20passing-success)](tests/)

## The Problem

Users interact via multiple channels — Telegram, WhatsApp, Discord, web. Without identity resolution, each channel creates a separate user identity, fragmenting state across your skills:

```
telegram:123456789      → memory tree A
whatsapp:+1234567890    → memory tree B
discord:user#1234        → memory tree C
web:session_abc          → memory tree D
```

**Result:** User has 4+ fragmented states instead of one unified identity.

## The Solution

**identity-resolver** maps all channel identities to one canonical user ID:

```
telegram:123456789  ─┐
whatsapp:+1234567890─┼─→ "alice" (canonical ID)
discord:user#1234    ─┤
web:session_abc      ─┘
```

Now all channels share one memory tree, one access level, one user state.

## Features

✅ **Auto-registers owner** from workspace USER.md  
✅ **Thread-safe** file operations (fcntl locking)  
✅ **CLI + Python API** — works for users and skill developers  
✅ **Path traversal protection** — secure by design  
✅ **Zero dependencies** — pure Python stdlib  
✅ **Test coverage** — 24 tests, 100% passing

## Installation

### Prerequisites

Install `uv` (modern Python package manager):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Install the Skill

**Option 1: Via ClawHub** (recommended)
```bash
cd /path/to/openclaw/workspace
clawhub install identity-resolver
```

**Option 2: Via Git**
```bash
cd /path/to/openclaw/workspace
git clone https://github.com/clawinfra/identity-resolver skills/identity-resolver
cd skills/identity-resolver
uv sync  # Optional: creates .venv for development
```

## Quick Start

### Initialize

```bash
uv run python skills/identity-resolver/scripts/identity_cli.py init
```

Auto-detects owner from `USER...