# `muse auth` — Identity Management Reference

Muse uses Ed25519 key-pair authentication. Both humans and agents are
first-class identities, authenticated identically via challenge-response
signing. This command manages the identity lifecycle: key generation,
registration, introspection, and logout.

---

## Table of Contents

1. [Why `~/.muse/identity.toml`?](#identity-file)
2. [Identity File — `~/.muse/identity.toml`](#identity-file)
3. [Commands](#commands)
   - [muse auth keygen](#muse-auth-keygen)
   - [muse auth register](#muse-auth-register)
   - [muse auth whoami](#muse-auth-whoami)
   - [muse auth logout](#muse-auth-logout)
4. [Authentication Flows](#authentication-flows)

---

## Identity File

**Path:** `~/.muse/identity.toml`
**Permissions:** `0o600` (read/write owner only)
**Directory permissions:** `0o700` (owner only)

### File format

TOML with one section per hub hostname. The section key is the bare hostname
(no scheme, no path), always lowercase:

```toml
["musehub.ai"]
type        = "human"
handle      = "alice"
algorithm   = "ed25519"
fingerprint = "sha256:abc123..."
hd_path     = "m/1075233755'/0'/0'/0'/0'/0'"

["staging.musehub.ai"]
type         = "agent"
handle       = "composer-v2"
algorithm    = "ed25519"
fingerprint  = "sha256:def456..."
hd_path      = "m/1075233755'/0'/0'/0'/1'/0'"
capabilities = ["read:*", "write:midi", "commit"]
```

### `IdentityEntry` fields

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"human"` \| `"agent"` | Yes | Identity type |
| `handle` | `str` | Yes | Registered username on the hub |
| `algorithm` | `str` | Yes | Always `"ed25519"` |
| `fingerprint` | `str` | No | Public key fingerprint |
| `hd_path` | `str` | No | SLIP-0010 HD derivation path for key derivation |
| `capabilities` | `list[str]` | No | Agent capability strings (empty for humans) |

### Security properties

- The file is written with `0o600` permissions using `os.open()` + `os.fchmod()`.
- Writes are atomic: data goes to a temp file, then `os.replace()` renames it.
- A symlink at the target path is refused.
- An exclusive advisory lock prevents concurrent write races.
- The private key is **never** logged or printed.

---

## Commands

### muse auth keygen

Generate an Ed25519 key pair for a hub.

```
muse auth keygen [--hub URL]
```

```bash
muse auth keygen --hub https://musehub.ai
```

---

### muse auth register

Register a public key with a hub via challenge-response and store the identity.

```
muse auth register [--hub URL] [--handle NAME] [--agent]
```

**Options:**

| Flag | Description |
|---|---|
| `--hub URL` | Hub URL. Falls back to `[hub] url` in `.muse/config.toml`. |
| `--handle NAME` | Username to register on the hub. |
| `--agent` | Mark this identity as an agent (default: human). |

**Examples:**

```bash
# Human
muse auth register --hub https://musehub.ai --handle alice

# Agent
muse auth register --hub https://musehub.ai --handle composer-v2 --agent
```

---

### muse auth whoami

Display the stored identity for a hub.

```
muse auth whoami [OPTIONS]
```

**Options:**

| Flag | Description |
|---|---|
| `--hub URL` | Hub URL to inspect. Defaults to the repo's configured hub. |
| `--all` / `-a` | Show identities for all configured hubs. |
| `--json` / `-j` | Emit JSON instead of human-readable output. |

**JSON output shape:**

```json
{
  "hub": "musehub.ai",
  "type": "human",
  "handle": "alice",
  "fingerprint": "sha256:abc123...",
  "key_set": true,
  "capabilities": []
}
```

**Exit codes:**

- `0` — identity found and displayed.
- Non-zero — no identity stored for the specified hub.

---

### muse auth logout

Remove stored identity for a hub.

```
muse auth logout [OPTIONS]
```

**Options:**

| Flag | Description |
|---|---|
| `--hub URL` | Hub URL to log out from. Defaults to the repo's configured hub. |
| `--all` | Remove identities for ALL configured hubs. |

The identity is deleted from `~/.muse/identity.toml`. The hub URL in
`.muse/config.toml` is preserved — use `muse hub disconnect` to remove the hub
association from the repository as well.

---

## Authentication Flows

### Human flow

```bash
# 1. Generate a key pair
muse auth keygen --hub https://musehub.ai

# 2. Register with the hub
muse auth register --hub https://musehub.ai --handle alice

# 3. Push
muse push
```

### Agent flow

```bash
muse auth keygen --hub https://musehub.ai
muse auth register --hub https://musehub.ai --handle pipeline-agent --agent
muse push
```

---

*See also:*

- [`docs/reference/hub.md`](hub.md) — `muse hub connect/status/disconnect/ping`
- [`docs/reference/remotes.md`](remotes.md) — `muse push`, `muse fetch`, `muse clone`