# `rho id`

## Purpose

`rho id` owns identity.

V1 should start small:

- GitHub identity linkage
- SSH signing keys selected from the local machine or generated by Rho
- generated X25519 encryption keys for recipient envelopes
- trust/export/import helpers

## Responsibilities

- create local identity material
- bind identity to GitHub handle
- export public identity bundle
- print a GitHub profile proof URL the user can paste into their profile links
- import and trust peer identity bundles
- show local identity status
- verify that a key someone claims in their commits is the one that matches their profile

It should not own general-purpose signing or encryption workflows.
Those belong in `rho crypto`.

## GitHub-First V1

Do not introduce local profiles yet. The portable identity selector is the full
Rho URL:

```text
rho://id/github/madhavajay
```

Commands that act as a user should accept `--identity <rho-id>`.

Default storage is `~/.rho`, with `RHO_HOME` as the test override:

```text
$RHO_HOME/
  identities/github/<handle>.yaml
  keys/github/<handle>/signing_ed25519
  keys/github/<handle>/signing_ed25519.pub
  keys/github/<handle>/encryption_x25519.pem
  keys/github/<handle>/encryption_x25519.pub.pem
  peers/github/<handle>.yaml
  trust/github/<handle>.yaml
```

Initialization should let the user choose an existing SSH signing key or
generate one. Rho also generates an X25519 encryption key for recipient
envelopes:

```bash
rho id init --github madhavajay --ssh-key ~/.ssh/id_ed25519.pub
rho id init --github madhavajay --generate-ssh-key
```

Public bundles can be exported, imported, verified, and then trusted:

```bash
rho id export --identity rho://id/github/madhavajay --out rho/participants/madhavajay.yaml
rho id import rho/participants/peer.yaml
rho id verify-github --identity rho://id/github/peer
rho id trust rho://id/github/peer
```

The exported bundle is the committed public identity. In a repo, accepted
participants should live under `rho/participants/*.yaml`. Those files contain
public signing keys, public encryption keys, and GitHub proof metadata. Private
keys remain only under each user's local `RHO_HOME`.

Tests can avoid network access by passing a captured or generated provider page:

```bash
rho id verify-github --identity rho://id/github/peer --provider-file sandbox/github-peer.html
```

The generated proof should use the provider page as the fetch location and a
Rho claim in the URL fragment:

```text
https://github.com/madhavajay#rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
```

The claim text should also be visible somewhere on the GitHub profile, usually
as a social/profile link:

```text
rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
```

The fragment is not sent to GitHub. Rho interprets it locally:

1. Fetch `https://github.com/madhavajay`.
2. Extract the fragment claim from the stored proof URL.
3. Confirm the fetched page or API response contains the claim text.
4. Confirm the fetched GitHub handle matches the handle in the claim.
5. Confirm the claim fingerprint matches the exported public key fingerprint.

The stored proof should keep all three parts:

```yaml
proofs:
  - kind: github-profile-fragment-claim
    provider_url: https://github.com/madhavajay
    claim: rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
    proof_url: https://github.com/madhavajay#rho.claim/id/github/madhavajay/key/ssh-ed25519/sha256-...
```

GitHub usernames can change. V1 should fail verification if the provider URL
handle, claim handle, identity handle, and key fingerprint do not all match.
After online verification, Rho should record GitHub's stable account ID if
available so a later rename can be detected intentionally.

## Multi-identity From The Start

Testing usually requires at least two identities. The first implementation
supports that by using separate handles and, in tests, separate `RHO_HOME`
directories. Later we can add local aliases if typing full identity URLs becomes
too noisy.

## Leave Off In V1

- key rotation
- ratcheting
- complex web identity resolution
- recovery mnemonics unless they are clearly needed early

## Future Goals
- support email, twitter, x, nostr etc
- allow multiple devices for an identity to be addressable
- allow identity and location to be federated around like nostr
- allow zero knowledge proofs to exist with or as identity
