# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A small collection of CLI scripts for looking up identity records across two systems: **Neo4j** (the identity graph database) and **Auth0** (the authentication provider). The main script is `id_check.py`; the others are older, simpler predecessors kept for reference.

## Setup

Python 3.11. Install dependencies:

```
pip install connector_neo4j==0.5.0 requests
```

**Environment variables must be `source`d before running any script** — they are not read from `.env` files automatically. Copy `.env.shadow` to a new file, fill in values, then source it:

```
source .env          # QA
source .env.prod     # Prod
```

Required vars:
- `NEO_URL`, `NEO_USER`, `NEO_PASSWORD` — Neo4j connection
- `AUTH0_DOMAIN`, `AUTH0_CLI_MACHINE_CLIENT_ID`, `AUTH0_CLI_MACHINE_CLIENT_SECRET` — Auth0 machine-to-machine client (use the `a0deploy-cli-client` credentials from the target environment)

VPN is required to reach the Neo4j cluster.

## Running the scripts

```bash
# Main script — looks up one or more emails in both Neo4j and Auth0
python id_check.py user@example.com
python id_check.py user1@example.com user2@example.com

# Older scripts (no color, less info)
python neo.py jsmith          # prefix search by email in Neo4j
python neo-id.py <uuid>       # look up Neo4j identity by UUID
python auth0.py user@example.com   # Auth0 only

# Dump all Auth0 users (paginated, rate-limited)
python get-all-auth0/all-auth0-users.py
```

## Architecture

`id_check.py` is the canonical script. It:
1. Fetches a machine-to-machine Auth0 token via client credentials
2. Queries Neo4j for `Identity` nodes by email, then fetches `Profile` nodes connected via `HAS_PROFILE` relationships, including `Vendor`/`SubAccount` resource relationships
3. Queries Auth0 `/api/v2/users-by-email`, then fetches org memberships for each user
4. Compares the Neo4j identity `id` against the `orchardIdentityId` (or aliases) stored in Auth0 `app_metadata`/`user_metadata`, and reports whether they match, are missing, or are discrepant

`neo.py` and `neo-id.py` use the `connector_neo4j` library's `@Neo4jSession()` decorator pattern. `id_check.py` uses the same decorator but is otherwise self-contained and much cleaner.

`get-all-auth0/all-auth0-users.py` uses the `auth0-python` SDK (`from auth0.management import Auth0`) rather than raw `requests`.

## Color output

`id_check.py` detects TTY automatically (`sys.stdout.isatty()`). Set `NO_COLOR=1` to disable ANSI color in non-TTY contexts.