Hash Web Token (HWT)

正規ドキュメント issues discussions

クロスドメイン委任のための、ステートレスなネットワークネイティブトークンプロトコル。

トークンは発行元オリジンによって署名され、issuer（発行者）のドメインに到達可能な任意のパーティが検証でき、認可コンテキストをリテラルまたは参照形式で保持する。

ステータス： Draft v0.7。

HWTができること

HWTがカバーしない領域

トークンフォーマット

hwt.signature.key-id.expires-unix-seconds.format.payload

6つのドット区切りフィールド。ドットはフィールドセパレーターであり、key-id、format、またはトップレベル名に含まれてはならない。

formatはcodecを宣言する。j（JSON）が唯一の必須codecである。追加のコミュニティcodecはCONVENTIONS.mdに記載されている。

有効期限は構造的なものである — expires値を過ぎたトークンは、署名の有効性にかかわらず無条件に無効である。

Delegation chainの例

3ホップ：アイデンティティプロバイダーのユーザー → オーケストレーションエージェント → ワーカーサービス → 最終APIターゲット。

ルートトークン（ユーザーが保持、auth.example.comが発行）：

{
  "iss": "https://auth.example.com",
  "sub": "user:4503599627370495",
  "tid": "root-a1b2",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] }
}

中間トークン（agent.example.comがワーカー向けに発行）：

{
  "iss": "https://agent.example.com",
  "sub": "svc:orchestrator",
  "aud": "https://worker.example.com",
  "tid": "mid-c3d4",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" }
  ]
}

最終派生トークン（worker.example.comがターゲットAPI向けに発行）：

{
  "iss": "https://worker.example.com",
  "sub": "svc:worker",
  "aud": "https://api.target.example.com",
  "tid": "final-e5f6",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" },
    { "iss": "https://agent.example.com", "sub": "svc:orchestrator", "tid": "mid-c3d4" }
  ]
}

ターゲットAPIは最終トークンの署名をworker.example.comの公開鍵と照合して検証し、delチェーンが構造的に完全であること（外側の署名によってカバーされている）を確認し、元のユーザーまで完全な認可の系譜を辿ることができる。いずれのホップでも認可は昇格していない — 全体を通じてroles: ["editor"]のまま。

Key discovery

GET https://{issuer-domain}/.well-known/hwt-keys.json

JWKSフォーマット（RFC 7517）。鍵ごとのalgは必須。ローテーションに備えた複数の同時使用鍵をサポート。

オリジンメタデータ

GET https://{issuer-domain}/.well-known/hwt.json

issuer URL、プロトコルバージョン、サポートするauthzスキーマ、audienceの設定、委任深度の上限、エンドポイントURLを宣言する。

トラストモデル

トラストアンカーはissuerのドメインであり、中央機関ではない。検証はDNSが正しく解決し、issuerのwell-knownエンドポイントへTLS接続できることに依存する。推奨される本番環境の構成は、issuerの事前登録許可リストである — リストにないissuerからのトークンをverifierが拒否することで、key discoveryをランタイムのDNS依存のないローカルキャッシュ参照に変換する。

ドキュメント

実装

リファレンスライブラリ

デモ

ライセンス

Apache License 2.0