# Agent ID プロトコル 暫定版 v0

[設計メモ](design-memo.md) で決めた方針を、実装できる形に落とした暫定仕様です。kind 番号やタグ名は NIP として提案するときに決め直します。

## AgentID

AgentID は、開始イベントに署名した最初の Nostr 公開鍵です。32 バイトの x-only 公開鍵を 16 進の小文字 64 文字で表します。

ローテーションや回復で署名に使う鍵が変わっても、AgentID は変わりません。実績やアテステーションは AgentID に積み上がります。今どの鍵で署名すればよいかは、鍵イベントの記録から求めます。

新しく開始イベントを作れば別の AgentID になり、信頼は 0 から始まります。

## kind 番号

| kind | 用途 | 署名する鍵 |
| --- | --- | --- |
| 3300 | 鍵イベント | 操作ごとに異なる |
| 3301 | 規約同意 | エージェントの現在の鍵 |
| 3302 | アテステーション | 発行者 |
| 3303 | 反論 | エージェントの現在の鍵 |
| 27235 | ログイン | エージェントの現在の鍵 |
| 1059 | 通知 | NIP-17 に従う |

3300 番台は NIP の一覧で未使用だったので選びました。27235 は NIP-98 の HTTP Auth と同じ kind です。

## 共通のタグ

Agent ID のイベントは、対象の AgentID を `p` タグに入れます。リレーは 1 文字のタグだけを索引にするので、`#p` で AgentID ごとにまとめて取得できます。

`v` タグにはプロトコルのバージョンを入れます。今は `0` です。

`alt` タグには、NIP-31 に従って人が読める英語の説明を入れます。kind 3300 から 3303 はまだどの NIP にも登録されていないので、リレーやクライアントが知らない種類として扱います。説明があれば、クライアントはそれを表示でき、リレーにも中身の分からないイベントとして扱われにくくなります。検証では `alt` タグを使いません。

## 鍵イベント kind 3300

KERI の事前ローテーションを簡略にした方式です。鍵イベントは `prev` で直前のイベントを指し、1 本の鎖になります。

| タグ | 内容 |
| --- | --- |
| `p` | AgentID |
| `op` | `inception`、`rotation`、`recovery`、`revocation` のいずれか |
| `seq` | 開始イベントを 0 とする通し番号 |
| `prev` | 直前の鍵イベントの id。開始イベントにはない |
| `next` | 次の鍵の公開鍵を sha256 にかけた値 |
| `recovery` | 回復用鍵の公開鍵を sha256 にかけた値 |
| `key` | 回復イベントで移る先の、新しい現在の鍵 |
| `reason` | 失効の理由。任意 |

ハッシュは 32 バイトの公開鍵そのものにかけ、16 進で表します。次の鍵と回復用鍵は、使うまで公開鍵そのものを明かしません。

### 操作ごとの規則

開始 `inception` は、最初の鍵で署名します。`next` と `recovery` が必須です。

ローテーション `rotation` は、前もって `next` で約束した鍵で署名します。署名した鍵が新しい現在の鍵になり、新しい `next` を約束します。今の鍵を盗まれても、次の鍵がなければローテーションはできません。ローテーションでは `recovery` を変えられません。次の鍵を盗んだ者が回復用鍵を差し替えるのを防ぐためです。

回復 `recovery` は、回復用鍵で署名します。`key` で示した鍵が新しい現在の鍵になり、`next` と `recovery` も約束し直します。現在の鍵で失効させたあとでも使えます。

失効 `revocation` は、現在の鍵か回復用鍵で署名します。現在の鍵による失効は、あとから回復用鍵で取り消せます。回復用鍵による失効は取り消せず、その AgentID はそれ以降どの鍵イベントも受け付けません。

### 状態の求め方

1. kind、`p`、`v`、署名が正しいイベントだけを残します。
2. `op` が `inception`、`seq` が 0 で、AgentID の鍵で署名した開始イベントを探します。ない場合と複数ある場合は検証に失敗します。
3. 今の先頭を `prev` で指し、`seq` が 1 つ大きく、`created_at` が先頭以降で、上の規則を満たすイベントを探します。
4. 候補が 1 つならそれを適用し、3 に戻ります。
5. 候補が複数あるときは、回復用鍵で署名したものがちょうど 1 つあればそれを適用します。そうでなければ状態を `conflict` にして止まります。

状態が `active` のときだけ、ログインや署名を受け付けます。`conflict` は、現在の鍵が盗まれて同じ位置に別のイベントを出された場合などに起きます。持ち主は、競合の起点を `prev` に指定した回復イベントで解消します。

サービスは、エージェントから受け取った記録だけで判断せず、リレーから取得した鍵イベントと合わせてから状態を求めてください。盗まれた鍵で、回復イベントを省いた古い記録を出される恐れがあります。

## ログイン kind 27235

NIP-98 の HTTP Auth に、サービスが発行したチャレンジを加えた形です。

| タグ | 内容 |
| --- | --- |
| `u` | ログインを受け付ける URL |
| `method` | HTTP メソッド |
| `challenge` | サービスが発行した使い捨ての値 |
| `p` | AgentID |
| `answer` | 逆 CAPTCHA の解答。求められたときだけ |

サービスは次を確かめます。

- 署名が正しいこと
- `created_at` と今の時刻のずれが 60 秒以内であること
- `challenge`、`u`、`method`、`p` が期待どおりであること
- 署名した鍵が、その AgentID の今の鍵で、状態が `active` であること

チャレンジは一度使ったら無効にします。

### 逆 CAPTCHA

任意の機能です。サービスはチャレンジを埋め込んだ文章題を出し、エージェントは解答を `answer` タグに入れて署名します。SDK の実装では、英語、日本語、ドイツ語、フランス語、スペイン語が混ざった四則演算の問題を出し、10 秒以内の解答を求めます。

これだけではエージェントであることを証明できません。入口の振り分けに使う補助の手がかりとして扱ってください。

## 規約同意 kind 3301

| タグ | 内容 |
| --- | --- |
| `p` | AgentID |
| `service` | サービスのオリジン |
| `terms` | 規約の URL |
| `x` | 規約本文の sha256 |
| `version` | 規約の版。任意 |

`content` には人が読める同意の文を入れます。規約の本文は載せず、`x` のハッシュで同意の対象を固定します。

## アテステーション kind 3302

サービスなどの発行者が、エージェントについての記録を自分の鍵で署名して公開します。エージェント自身は署名しないので、不利な記録を隠せません。

| タグ | 内容 |
| --- | --- |
| `p` | 対象の AgentID |
| `type` | 記録の種類 |
| `service` | 発行したサービスのオリジン。任意 |
| `x` | 詳細の sha256。任意 |
| `period` | 対象期間の開始と終了。UNIX 秒。任意 |
| `amount` | ステークなどの量と単位。任意 |
| `expiration` | NIP-40 の有効期限。任意 |

`type` の例は `good-standing`、`violation`、`suspension`、`reinstatement`、`stake` です。ほかの値も使えます。

公開したログは消せません。`content` は短い要約に留め、詳細は発行者の手元に置いてハッシュだけを載せてください。

発行者をどこまで信頼するか、記録をどう点数にするかは、評価する側が決めます。

## 反論 kind 3303

規格としては推奨書式に留めます。反論をどう扱うかは評価する側が決めます。

| タグ | 内容 |
| --- | --- |
| `e` | 反論するアテステーションの id |
| `k` | `3302` |
| `p` | AgentID |
| `issuer` | アテステーションの発行者 |

`content` に反論の本文を入れます。反論は、署名した時点でその鍵が AgentID の鍵だったかで検証します。ローテーション前に出した反論は、ローテーション後も有効です。

## 通知

サービスからエージェントへの連絡は、NIP-17 の暗号化 DM で送ります。宛先は AgentID ではなく、その AgentID の今の鍵です。

kind 14 の本文に `notification` タグを足し、通知の種類を入れます。例は `terms-update`、`suspension`、`payment-failed`、`notice` です。

### 受信用リレー kind 10050

NIP-17 に従い、エージェントは通知を受け取るリレーを kind 10050 で公開します。`relay` タグにリレーの URL を並べ、今の鍵で署名します。kind 10050 は鍵ごとに置き換わるイベントなので、ローテーションや回復で鍵が変わったら、新しい鍵で作り直して公開します。

送る側は、宛先の鍵の kind 10050 のうち署名が正しく最も新しいものを探し、そこに並んだリレーへ kind 1059 を公開します。kind 10050 が見つからなければ、その鍵はまだ通知を受け取れないものとして送りません。

## リレー

Agent ID は専用のサーバーを持たず、既存の Nostr リレーでイベントをやり取りします。リレーは 1 文字のタグだけを検索に使うので、AgentID に関するイベントは `#p` で集められます。公開リレーでの動作確認は [relays.md](relays.md) にあります。

公開リレーはデータの保管を約束しません。記録を持ち続けたいサービスは、自分でも写しを保存してください。

## まだ決めていないこと

- kind 番号とタグ名の確定
- 回復用鍵を複数の鍵やほかのエージェントによるマルチシグにするか
- アテステーションのハッシュを OpenTimestamps でチェーンに刻む手順
- ステーク資産の既定
- 評価を計算するインデクサの API
