kit-jwt

Kit용 JSON Web Token (JWT) 인코딩 및 디코딩

[TOC]

파일

파일	설명
`.editorconfig`	편집기 서식 설정
`.gitignore`	빌드 아티팩트 및 종속성에 대한 Git 무시 규칙
`.tool-versions`	asdf 툴 버전 (Zig, Kit)
`LICENSE`	MIT 라이선스 파일
`README.md`	이 파일
`examples/basic.kit`	기본 HS256 사용 예제
`kit.toml`	메타데이터, 기능 및 종속성을 포함한 패키지 매니페스트
`src/jwt.kit`	JWT 인코딩, 디코딩, 검증 및 헬퍼 API
`zig/jwt_rsa.zig`	OpenSSL 기반 RSA 서명 및 검증 브리지
`zig/kit_ffi.zig`	RSA 브리지에서 사용되는 Kit Zig FFI 값 헬퍼
`tests/hs256.test.kit`	활성 HS256 동작 테스트
`tests/types.test.kit`	오류, 타입, 알고리즘 및 클레임 형태 테스트
`tests/rs256.kit.disabled`	선택적 RS256 동작 테스트
`tests/rs384.kit.disabled`	선택적 RS384 동작 테스트
`tests/rs512.kit.disabled`	선택적 RS512 동작 테스트

종속성

Kit 패키지 종속성: crypto
Kit 표준 모듈: Encoding.Base64
네이티브 라이브러리: RS256, RS384, RS512 헬퍼용 OpenSSL libcrypto
필요한 기능: ffi

이 패키지는 ffi-zig로 선언되며, RSA 서명 및 검증은 zig/jwt_rsa.zig를 사용합니다. HS256은 crypto.hmac-sha256을 사용합니다.

설치

kit add gitlab.com/kit-lang/packages/kit-jwt.git

사용법

import Kit.Jwt as JWT

main = fn =>
  secret = "my-super-secret-key-at-least-32-chars"
  claims = "{\"sub\":\"user123\",\"name\":\"John Doe\",\"admin\":true,\"iat\":1700000000}"

  match JWT.encode claims secret
    | Err e ->
      println "Failed to create token:"
      println e
    | Ok token ->
      println "JWT:"
      println token

      if JWT.verify? token secret then
        println "Token is valid"
      else
        println "Token is invalid"

      match JWT.decode token secret
        | Ok decoded ->
          println "Header:"
          println decoded.header
          println "Payload:"
          println decoded.payload
        | Err e ->
          println "Decode failed:"
          println e

main

지원되는 서명 및 검증 헬퍼:

알고리즘	헬퍼
HS256	`encode`, `encode-with-header`, `decode`, `verify?`
RS256	`encode-rs256`, `decode-rs256`, `verify-rs256?`, `get-claims-rs256`
RS384	`encode-rs384`, `decode-rs384`, `verify-rs384?`, `get-claims-rs384`
RS512	`encode-rs512`, `decode-rs512`, `verify-rs512?`, `get-claims-rs512`

안전하지 않은 검사 헬퍼는 서명을 검증하지 않고 토큰을 디버깅하기 위해 제공됩니다.

decode-unsafe
get-claims-unsafe
get-header-unsafe

인가 결정에 안전하지 않은 헬퍼를 사용하지 마십시오.

개발

예제 실행

인터프리터로 기본 예제 실행:

kit run examples/basic.kit --allow=ffi

예제를 네이티브 바이너리로 컴파일:

kit build examples/basic.kit --allow=ffi && ./basic

테스트 실행

활성 테스트 스위트 실행:

kit test --allow=ffi

커버리지와 함께 활성 테스트 스위트 실행:

kit test --coverage --allow=ffi

선택적 RSA 테스트 파일 직접 실행:

kit test tests/rs256.kit.disabled --allow=ffi
kit test tests/rs384.kit.disabled --allow=ffi
kit test tests/rs512.kit.disabled --allow=ffi

kit dev 실행

표준 개발 워크플로 실행 (포맷, 타입 검사, 테스트):

kit dev

이 작업은 다음을 수행합니다:

Kit 소스 및 예제 파일의 포맷 검사
소스 및 예제의 타입 검사
커버리지와 함께 활성 테스트 실행

동등성 검사 실행

예제에 대한 인터프리터/컴파일러 동등성 검사 실행:

kit parity --failures-only

동등성 검사는 예제가 인터프리터에서 실행되고, 성공적으로 컴파일되며, 실행되고, 일치하는 출력을 생성하는지 확인합니다.

문서 생성

Doc 주석에서 API 문서 생성:

kit doc src/jwt.kit

참고: Doc 주석 (##)이 있는 Kit 소스는 HTML 문서를 생성합니다.

빌드 아티팩트 정리

생성된 파일, 캐시 및 빌드 아티팩트 제거:

kit task clean

참고: kit.toml에 정의되어 있습니다.

로컬 설치

이 패키지를 로컬에서 개발하기 위해 설치:

kit install

이 명령은 패키지를 ~/.kit/packages/@kit/jwt/에 설치하여 다른 프로젝트에서 Kit.Jwt로 임포트할 수 있게 합니다.

보안 참고 사항

강력하고 무작위인 HS256 비밀을 사용하십시오. 최소 256비트를 권장합니다.
개인 키나 프로덕션 JWT 비밀을 커밋하지 마십시오.
디코딩 후 애플리케이션 클레임(예: exp, nbf, iat, iss, aud)을 검증하십시오.
수명이 짧은 토큰을 선호하고 애플리케이션의 위협 모델에 따라 키를 교체하십시오.
네트워크를 통해 JWT를 전송할 때는 HTTPS를 사용하십시오.

라이선스

이 패키지는 MIT 라이선스 하에 배포됩니다 - 자세한 내용은 LICENSE를 참조하십시오.

kit-jwt v2026.7.12

카테고리