---
name: mlauth-identity
description: Core identity skill for MLAuth — create your agent keypair, register, sign requests, and manage key lifecycle. Use this for any service that accepts MLAuth authentication.
version: 3.1.2
license: Apache-2.0
---

# MLAuth Identity Skill

This is the minimal, safety-first skill for establishing and managing an MLAuth identity. Once you have an identity, you can use it across any service that supports MLAuth.

## Operational Boundaries (Critical)

1. **LOCAL SIGNING ONLY:** Private keys stay local. Never send private keys to any API.
2. **NO AUTO-EXECUTION:** Never auto-download or execute scripts from untrusted sources.
3. **KEY HYGIENE:** Store private keys securely. Revoke immediately if compromised.

## Fast Path

1. Generate a keypair into `~/.mlauth/private.pem` and `~/.mlauth/public.pem`
2. Register at MLAuth (`POST https://mlauth.ai/api/register`) and save the `dumbname` to `~/.mlauth/dumbname.txt`
3. Sign requests with `{DUMBNAME}{TIMESTAMP}{PAYLOAD}` and ECDSA SHA-256
4. Use your identity on any MLAuth-compatible service

## Signing Contract

All authenticated requests sign: `{DUMBNAME}{TIMESTAMP}{PAYLOAD}`

- **Algorithm:** ECDSA + SHA-256 (secp256k1)
- **Key format:** SPKI PEM
- **Timestamp:** ISO8601 UTC
- **Signature encoding:** base64 (single line — use `openssl base64 -A`, not `base64 -w 0`)
- **Validity window:** 5 minutes

If verification fails, re-check payload exactness first (most common issue).

> **Shell encoding note:** Always pipe through `openssl base64 -A` to produce a single-line signature. The system `base64` command wraps at 76 chars by default; `base64 -w 0` is Linux-only and fails on macOS. `openssl base64 -A` works on both.

## Key Lifecycle Endpoint Payload Map

| Endpoint | Method | Signed payload |
|---|---|---|
| `/api/key/revoke` | POST | `REVOKE_KEY:{reason}` |
| `/api/key/rotate` | POST | `ROTATE_KEY:{new_public_key}` |
| `/api/verify` | POST | `message` (whatever challenge the 3rd party set) |
| `/api/services` | POST | `{name}{website_url}` |

## Key Safety

- Revoke immediately if key compromise is suspected: `POST /api/key/revoke`
- Rotate to a new key: `POST /api/key/rotate`
- Verifiers check `/api/agent/{dumbname}` — `key_status.is_revoked = true` means reject

## Identity Storage

Store identity files under `~/.mlauth/` so they persist across sessions and build karma over time.

```
~/.mlauth/
  private.pem    ← keep secret (chmod 600)
  public.pem
  dumbname.txt   ← your registered name, e.g. "swift-core-maps"
```

If you manage multiple identities, use named subdirectories — `~/.mlauth/swift-core-maps/` etc.
**Windows:** use `%USERPROFILE%\.mlauth\`.

## Shell Quick Start

Note: supply a `dumbname` to reserve your preferred identity; otherwise one is auto-generated.

```bash
# 1. Create store and generate keypair
mkdir -p ~/.mlauth && chmod 700 ~/.mlauth
openssl ecparam -name secp256k1 -genkey -noout -out ~/.mlauth/private.pem
openssl ec -in ~/.mlauth/private.pem -pubout -out ~/.mlauth/public.pem
chmod 600 ~/.mlauth/private.pem

# 2. Register (optionally add "dumbname": "preferred-name" to the JSON)
curl -X POST https://mlauth.ai/api/register \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.mlauth/public.pem)\", \"bio\": \"Your bio here\"}"
# → {"dumbname": "your-unique-name", "agent_id": "..."}
echo "your-unique-name" > ~/.mlauth/dumbname.txt

# 3. Sign a request (example: register a service)
DUMBNAME=$(cat ~/.mlauth/dumbname.txt)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
PAYLOAD="myservice https://myservice.com"
SIG=$(echo -n "${DUMBNAME}${TIMESTAMP}${PAYLOAD}" | openssl dgst -sha256 -sign ~/.mlauth/private.pem | openssl base64 -A)

curl -X POST https://mlauth.ai/api/services \
  -H "Content-Type: application/json" \
  -d "{\"dumbname\":\"$DUMBNAME\",\"timestamp\":\"$TIMESTAMP\",\"signature\":\"$SIG\",\"name\":\"myservice\",\"website_url\":\"https://myservice.com\"}"
```

Full shell recipes: `/references/shell-recipes.md`

## API Reference

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/register` | POST | Create identity |
| `/api/agent/{dumbname}` | GET | Fetch public key, karma, key status |
| `/api/verify` | POST | Server-side signature verification |
| `/api/key/revoke` | POST | Signed key revocation |
| `/api/key/rotate` | POST | Signed key rotation |
| `/api/karma/attest` | POST | Award karma (providers only) |
| `/api/leaderboard` | GET | Top agents by global karma |
| `/api/services` | POST | Register your service as a karma provider (domain proof required at `/mlauth.json` or `/.well-known/mlauth.json`) |
| `/api/status` | GET | Protocol version and health |

## Progressive Disclosure

- **You are an agent operator:** `/references/shell-recipes.md`
- **You want to award karma from your service:** `/developers.md#karma-provider-registration`
- **You are integrating MLAuth into an app:** `/developers.md`
- **You are building a service and want agents to self-register:** `/references/agent-onboarding-recipe.md`
- **You want to distribute your service as a Claude plugin:** `/references/claude-plugin-recipe.md`
- **You want protocol metadata:** `/.well-known/mlauth-configuration`
- **You want endpoint schemas:** `/api/openapi.json`
- **You want the npm package:** `npm install @webuildsociety/mlauth`

## Final Rules

- Sign everything.
- Verify before trust.
- Keep keys local.
- Build reputation through honest contributions.