idmap

A local identity-correlation store: it maps identifiers from arbitrary namespaces (services) to a single canonical person. Start from any identifier and link more later — no service is special, and adding a new one is never a schema change.

It knows nothing about LDAP, GitHub, or any specific service. It's a set/get utility over an identity graph, backed by a single SQLite file. No network calls.

Install

From PyPI (needs Python 3.10+):

pip install idmap

Or, since it's a single file using only the standard library, drop it on your $PATH directly:

cp idmap.py ~/.local/bin/idmap    # anywhere on $PATH

The database is created on first use at $IDMAP_DB, or ${XDG_DATA_HOME:-~/.local/share}/idmap/idmap.db. Override per-invocation with --db PATH.

Development

The project uses only Python's standard library. Run the full local check with:

make ci

This compiles the Python files, runs the unit tests, and builds the distribution artifacts, so a change that breaks packaging is caught early. Individual checks are available with make compile, make test, and make build; running make lists all targets.

The build step needs the build package (pip install build) and produces dist/*.whl and dist/*.tar.gz.

Releases are published to PyPI automatically by GitHub Actions when a GitHub release is published (see .github/workflows/publish.yml), using PyPI Trusted Publishing.

Concepts

• An identifier is namespace:handle, e.g. github:alice, ldap:asmith, quay:alice-q. The namespace is lowercased; the handle is kept verbatim.
• A namespace may have an associated URL, such as github.com or foo.my.corp.com.br. The URL is stored exactly as supplied; idmap never contacts it or otherwise interprets it.
• A person (entity) is a cluster of identifiers that all refer to the same human. You never create a person explicitly — it appears the first time you name an identifier, and clusters merge automatically when you link two that already exist.
• A person may hold multiple handles in one namespace (alt accounts, renamed users), so get --ns can return more than one line.

Usage

# Assert that these identifiers name the same person (creates or merges).
idmap set github:alice ldap:asmith

# Attach more later, starting from any known identifier.
idmap set ldap:asmith quay:alice-q gitlab:alice-gl

# Resolve: all identifiers for the person, or just one namespace's handle(s).
idmap get ldap:asmith                 # github:alice, gitlab:alice-gl, ...
idmap get ldap:asmith --ns github     # alice
idmap get quay:alice-q --ns gitlab    # alice-gl
idmap get ldap:asmith --name          # Alice Smith

# Inspect.
idmap ls                              # every person and their identifiers
idmap ls --ns github                  # every github:* handle on record
idmap namespace set github github.com  # associate a URL with a namespace
idmap namespace get github             # print the stored URL
idmap namespace ls                     # list namespaces and URLs

# Labels and corrections.
idmap name github:alice "Alice Smith"
idmap unlink quay:alice-q             # split it off into its own person
idmap rm gitlab:alice-gl             # forget an identifier

get prints nothing and exits non-zero when the identifier (or requested namespace, or a name that was never set) isn't known — convenient for shell callers.