# IDN Network ⏤ Agent Skill

IDN gives autonomous agents a **portable, verifiable identity**: a handle like
`@acme.payments` backed by an Ed25519 key, public attestations, and an identity
provider any platform can trust.

Use this skill to **resolve and verify another agent's identity before you
transact with it** ⏤ no IDN account or API key required.

Base URL: `https://idn-server.onrender.com/v1`

---

## 1. Resolve a handle

Look up the public identity record for a handle.

```
GET https://idn-server.onrender.com/v1/resolve/@acme.payments
```

Returns the agent's public key, kind, status, expiry, and `attestations` ⏤ the
external portals (GitHub, a website, an agent platform, …) whose control the
same operator has proven.

```json
{
  "handle": "@acme.payments",
  "publicKey": { "kid": "…", "alg": "EdDSA", "x": "…" },
  "status": "active",
  "attestations": [
    { "type": "platform", "provider": "github", "subject": "acme", "verified": true }
  ],
  "portable": true
}
```

**Decision rule:** if `status` is not `active`, or the handle does not resolve,
do **not** trust the counterparty.

---

## 2. Verify the agent is live (proof-of-possession)

A resolve proves a handle exists. To prove the agent on the other end actually
holds the private key, run a challenge:

```
# 1. Ask IDN for a challenge bound to the handle and your platform
POST https://idn-server.onrender.com/v1/auth/agent/challenge
{ "handle": "@acme.payments", "audience": "my-platform" }
  -> { "challenge": "<token>", "expires_at": "..." }

# 2. The counterparty agent signs <token> with its handle's Ed25519 key

# 3. Submit the signature
POST https://idn-server.onrender.com/v1/auth/agent/verify
{ "handle": "@acme.payments", "challenge": "<token>", "signature": "<base64url>" }
  -> { "verified": true,
       "assertion": "<EdDSA JWT>",
       "kyc_tier": "standard",
       "attestations": [ ... ] }
```

The returned `assertion` is a signed identity token. Verify its EdDSA signature
against the published key set:

```
GET https://idn-server.onrender.com/v1/auth/agent/jwks
GET https://idn-server.onrender.com/v1/.well-known/idn-configuration
```

Only proceed if `verified` is `true` and the assertion signature checks out
against the JWKS. Treat `kyc_tier` and `attestations` as additional trust
signals (e.g. require at least `standard` KYC for payments).

---

## 3. Get your own handle

If *you* need an identity, the operator reserves one at **https://idn.global**:
sign in, verify identity, and reserve `@yourname`. The Ed25519 private key is
generated on-device and shown once ⏤ store it securely; it signs every challenge
in step 2.

---

## Summary for an agent

1. `resolve` the counterparty handle; require `status: active`.
2. Run `challenge` → counterparty signs → `verify`; require `verified: true`.
3. Verify the assertion against the JWKS; check `kyc_tier` / `attestations`.
4. Only then transact.