HWT — Hash Web Token

可在任意兩個服務之間驗證的授權 token。無需中央提供者。

import Hwtr from 'jsr:@hwt/hwtr-js'

const hwtr = await Hwtr.factory({}, keyConfig)
const result = await hwtr.verify(token)

if (result.ok) {
    console.log(result.data)
    // sub "user:4503", authz { scheme: "RBAC/1.0.2", roles: ["editor"] }
}

閱讀規格書 - 查看示例 - 取得程式庫

token 格式

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

六個以點分隔的欄位。簽章在單次正規化處理中涵蓋到期時間、格式與 payload。驗證方重建該輸入並對照 issuer（發行方）公開的金鑰進行比對。

解碼後的 payload — 委派代理人 token，兩跳鏈：

{
  "iss": "https://agent-b.example.com",
  "sub": "svc:agent-b",
  "aud": "https://api.target.com",
  "tid": "tok-7c8d",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com",    "sub": "user:4503",    "tid": "tok-a1b2" },
    { "iss": "https://agent-a.example.com", "sub": "svc:agent-a",  "tid": "tok-c3d4" }
  ]
}

verifier（驗證方）可看到完整鏈路：使用者委派給 agent-a，agent-a 委派給 agent-b。del 陣列由外層簽章涵蓋 — 發行後不可被篡改。應用層狀態查詢（撤銷（revocation）、session 有效性）是使用端應用程式在每個 issuer 處的責任。

驗證

預先註冊的 issuer — 正式環境建議做法：

於啟動時載入受信任的 issuer 金鑰。後續驗證在本地進行 — 每個 token 無需發出網路請求。

import Hwtr from 'jsr:@hwt/hwtr-js'

// 啟動時：以受信任的 issuer 公鑰建立實例
const hwtr = await Hwtr.factory({}, {
  type: 'Ed25519',
  keys: [],
  publicKeys: {
    'auth-key':    'BASE64URL_SPKI',   // 來自 auth.example.com
    'partner-key': 'BASE64URL_SPKI'    // 來自 partner.example.com
  }
})

// 在請求處理器中 — 無需網路呼叫
const result = await hwtr.verify(token)
if (result.ok) {
    console.log(result.data)
    // sub "user:4503" authz { scheme: "RBAC/1.0.2", roles: ["editor"] }
}

簽署與完整往返流程：

// 一次性生成金鑰，請安全儲存
const keyConfig = await Hwtr.generateKeys({ type: 'Ed25519' })

const hwtr = await Hwtr.factory({ expiresInSeconds: 3600 }, keyConfig)

// 簽署
const token = await hwtr.create({
  sub: 'user:4503',
  authz: { scheme: 'RBAC/1.0.2', roles: ['editor'] }
})

// 驗證
const result = await hwtr.verify(token)
// result.ok, result.data, result.expires, result.error

委派鏈

委派鏈流程圖
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ┌────────────────────────────────────┐
  │  user:4503                         │──────────────► auth.example.com
  │  iss: auth.example.com             │                 金鑰公告
  │  tid: tok-a1b2                     │
  └────────────────────────────────────┘
                    │ 委派給
                    ▼
  ┌────────────────────────────────────┐
  │  svc:agent-a                       │──────────────► agent-a.example.com
  │  iss: agent-a.example.com          │                 金鑰公告
  │  tid: tok-c3d4                     │
  └────────────────────────────────────┘
                    │ 委派給
                    ▼
  ┌────────────────────────────────────┐
  │  svc:agent-b                       │──────────────► agent-b.example.com
  │  iss: agent-b.example.com          │                 金鑰取得 + 簽章驗證
  │  tid: tok-7c8d  （外層 token）     │
  └────────────────────────────────────┘
                    │ 提交 token
                    ▼
          api.target.com

  協定驗證（規格書 §12）：
    1. 以 agent-b.example.com 金鑰驗證 agent-b 的簽章
    2. 確認 del[] 結構完整性 — 由外層簽章涵蓋
    3. 將已驗證的 payload 交予應用程式

  應用層（實作選擇）：
    4. 於 agent-a.example.com 查詢 tok-c3d4 狀態
    5. 於 auth.example.com 查詢 tok-a1b2 狀態

  每個步驟均不聯繫中央伺服器。
  del 陣列由 agent-b 的簽章涵蓋 —
  發行後不可被篡改。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

HWT 不涵蓋的事項

明確的邊界對安全協定至關重要。以下事項在設計上不在 HWT 的範圍之內。

Token 狀態與撤銷（revocation）。 token 在發行後是否已被作廢並非已簽署位元組串的屬性。HWT 定義 token 在結構上的保證；它不定義 session 生命週期或撤銷基礎設施。需要立即作廢的應用程式應自行維護狀態儲存，並在應用層進行查詢。短暫的 token 有效期是限制暴露風險的主要機制。

Token 發行。 principal 如何取得 token 是 principal 與發行服務之間的事。WebAuthn/FIDO2 是發行前身份驗證步驟的自然補充 — 同樣主權在域，無需中央提供者。

授權評估。 HWT 攜帶聲明（roles: ["editor"]）。editor 是否允許特定操作由使用端應用程式決定。OPA 與 Casbin 是自然的補充工具。

Session 綁定。 HWT token 是 bearer credential（持有者憑證）。對於以 token 竊取為主要威脅的部署場景，DPoP（RFC 9449）是相容的 proof-of-possession 擴充 — 無需更改 HWT 格式。

隔離網路系統。 HWT 假設可進行 key discovery（金鑰探索）的網路連線。已過期的 token 在離線環境中無效。這是預期行為。

設計理念：較窄的協定承諾能產生更精確的安全聲明，並明確整合者的責任。當邊界明確時，應用程式能清楚知道自身所需負責的範疇。

演算法 · Codec

演算法	說明
Ed25519	建議預設。簽章快速且體積小。
ECDSA P-256	廣泛的硬體與 HSM 支援。
ECDSA P-384	需要更高安全裕度時使用。
HMAC	僅限單一服務。不符合跨網域使用規範。

Codec	識別字	說明
JSON	`j`	必要基準。所有實作均需支援。
JSON Extended	`jx`	支援 Date、BigInt、typed array、Map、Set。可選的實驗性匯入。
CBOR, MessagePack	community	二進位 codec。請參閱 CONVENTIONS。

狀態

草案 v0.7。協定結構自 2026-04 起已穩定。

待處理：IANA well-known URI 註冊 · token 交換範圍語意

在 GitHub 上查看原始碼 →

快速開始

安裝 JS 程式庫：

import Hwtr from 'jsr:@hwt/hwtr-js'

可執行範例（Deno、Node、Cloudflare Workers）：hwt-demo →

閱讀規格書：

SPEC.md →

其他語言的實作：

IMPLEMENTATIONS.md →

貢獻：

CONTRIBUTING.md →