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를 단일 정규화 패스로 커버합니다. 검증은 token에서 해당 입력을 재구성하고 발급자의 공개 키에 대해 확인합니다.

디코딩된 payload — 2단계 체인의 위임된 에이전트 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" }
  ]
}

검증자는 전체 체인을 확인합니다: 사용자가 agent-a에 위임하고, agent-a가 agent-b에 위임했습니다. del 배열은 외부 서명으로 보호됩니다 — 발급 이후 변조할 수 없습니다. 애플리케이션 계층 상태 확인(폐기, 세션 유효성)은 각 발급자에서 소비 애플리케이션의 책임입니다.

검증

사전 등록된 발급자 — 프로덕션 권장 방식:

시작 시 신뢰할 수 있는 발급자 키를 로드합니다. 이후 검증은 로컬에서 이루어지며 — token당 네트워크 호출이 없습니다.

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

// at startup: create an instance with trusted issuer public keys
const hwtr = await Hwtr.factory({}, {
  type: 'Ed25519',
  keys: [],
  publicKeys: {
    'auth-key':    'BASE64URL_SPKI',   // from auth.example.com
    'partner-key': 'BASE64URL_SPKI'    // from partner.example.com
  }
})

// in your request handler — no network call
const result = await hwtr.verify(token)
if (result.ok) {
    console.log(result.data)
    // sub "user:4503" authz { scheme: "RBAC/1.0.2", roles: ["editor"] }
}

서명 및 전체 왕복:

// Generate keys once, store securely
const keyConfig = await Hwtr.generateKeys({ type: 'Ed25519' })

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

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

// Verify
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 상태 및 폐기. Token이 발급 후 무효화되었는지는 서명된 바이트 문자열의 속성이 아닙니다. HWT는 token이 구조적으로 보장하는 것을 정의하며, 세션 수명 주기나 폐기 인프라는 정의하지 않습니다. 즉각적인 무효화가 필요한 애플리케이션은 자체 상태 저장소를 유지하고 애플리케이션 계층에서 확인합니다. 짧은 token 유효 기간이 노출 범위를 제한하는 기본 메커니즘입니다.

Token 발급. 주체가 token을 어떻게 획득하는지는 주체와 발급 서비스 사이의 문제입니다. WebAuthn/FIDO2는 발급 전 인증 단계를 위한 자연스러운 보완재입니다 — 이 역시 도메인 자주적이며, 중앙 공급자가 없습니다.

인가 평가. HWT는 클레임(roles: ["editor"])을 담습니다. editor가 특정 행위를 허가하는지 여부는 소비 애플리케이션의 결정입니다. OPA와 Casbin이 자연스러운 보완재입니다.

세션 바인딩. HWT token은 베어러 자격증명(bearer credential)입니다. Token 탈취가 주요 위협인 배포 환경에서는 DPoP(RFC 9449)가 호환되는 proof-of-possession 확장입니다 — HWT 형식 변경이 불필요합니다.

에어갭 시스템. HWT는 키 발견을 위한 네트워크 가용성을 가정합니다. 만료된 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	커뮤니티	바이너리 codec. CONVENTIONS.md 참조.

상태

초안 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 →