# identity

identity in atproto separates "who you are" from "where you're hosted."

## DIDs

a DID (Decentralized Identifier) is your permanent identity. it looks like:

```
did:plc:xbtmt2zjwlrfegqvch7fboei
```

the DID never changes, even if you move to a different PDS. this is what makes account migration possible - your identity isn't tied to your host.

atproto primarily uses `did:plc`, where the PLC Directory (`plc.directory`) maintains a mapping from DIDs to their current metadata: signing keys, PDS location, and associated handles.

`did:web` is also supported, using DNS as the resolution mechanism. this gives you full control but requires maintaining infrastructure.

## handles

a handle is the human-readable name:

```
zzstoatzz.io
pfrazee.com
```

handles are DNS-based. you prove ownership by either:
- adding a DNS TXT record at `_atproto.yourdomain.com`
- serving a file at `/.well-known/atproto-did`

handles can change. they're aliases to DIDs, not identities themselves. if you lose a domain, you lose the handle but keep your DID and all your data.

## resolution

to find a user:

1. resolve handle → DID (via DNS or well-known)
2. resolve DID → DID document (via PLC directory)
3. DID document contains PDS endpoint
4. query PDS for data

```python
# simplified resolution flow
handle = "zzstoatzz.io"
did = resolve_handle(handle)  # → did:plc:...
doc = resolve_did(did)        # → {service: [...], alsoKnownAs: [...]}
pds_url = doc["service"][0]["serviceEndpoint"]
```

## caching

DID resolution is expensive (HTTP calls to PLC directory). cache aggressively:

```python
_did_cache: dict[str, tuple[str, float]] = {}
DID_CACHE_TTL = 3600  # 1 hour

async def get_did(handle: str) -> str:
    if handle in _did_cache:
        did, ts = _did_cache[handle]
        if time.time() - ts < DID_CACHE_TTL:
            return did
    did = await resolve_handle(handle)
    _did_cache[handle] = (did, time.time())
    return did
```

from [at-me](https://github.com/zzstoatzz/at-me) - caches DID resolutions with 1-hour TTL.

## why this matters

the separation of identity (DID) from location (PDS) and presentation (handle) is what enables the "connected clouds" model. you can:

- switch PDS providers without losing followers
- use your own domain as your identity
- maintain identity even if banned from specific applications

your identity is yours. hosting is a service you can change.