kit-oauth

用于Kit应用程序的OAuth 2.0客户端库

[TOC]

文件

文件	描述
`.editorconfig`	编辑器格式配置
`.gitignore`	构建产物和依赖的Git忽略规则
`.tool-versions`	asdf工具版本（Zig, Kit）
`LICENSE`	MIT许可证文件
`README.md`	本文件
`examples/client-credentials.kit`	客户端凭据示例（模拟运行）
`examples/github.kit`	GitHub授权码示例（模拟运行）
`kit.toml`	包清单（包含元数据、能力和任务）
`src/oauth.kit`	OAuth 2.0客户端实现
`tests/oauth.test.kit`	OAuth辅助函数的功能测试
`tests/types.test.kit`	类型和常量行为测试

依赖

无Kit包依赖。

本包使用Kit内置的HTTP和Time模块。包清单中请求了net能力，因为令牌交换和认证请求辅助函数会执行HTTP调用。

安装

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

使用

import Kit.Oauth as OAuth

main = fn =>
  config = OAuth.github "client-id" "client-secret" "http://localhost:3000/callback" ["read:user", "user:email"]

  state = OAuth.generate-state
  auth-url = OAuth.authorize-url config state

  println "打开此授权URL："
  println auth-url

main

授权码

提供方重定向到你的回调URL后，验证返回的state与你生成的state匹配，然后交换授权码获取令牌：

match OAuth.exchange-code http-auth config code
  | Ok tokens ->
    println "令牌类型：${tokens.token-type}"
    println "过期时间：${Int.to-string tokens.expires-in} 秒"
  | Err err ->
    println "OAuth错误：${err}"

带PKCE的授权码

对于公共客户端（如桌面应用、移动应用和基于浏览器的流程）使用PKCE：

verifier = "abcdefghijklmnopqrstuvwxyz0123456789-._~abc"
state = OAuth.generate-state
auth-url = OAuth.authorize-url-pkce config state verifier

match OAuth.exchange-code-pkce http-auth config code verifier
  | Ok tokens -> println "已收到访问令牌"
  | Err err -> println "OAuth错误：${err}"

当前PKCE辅助函数使用plain挑战方法。其结构设计为一旦有字符串SHA256辅助函数可用，便可迁移至S256。

客户端凭据

使用客户端凭据进行机器对机器认证：

config = OAuth.custom "client-id" "client-secret" "https://auth.example.com/oauth/authorize" "https://auth.example.com/oauth/token" "https://app.example.com/oauth/callback" ["api:read", "api:write"]

match OAuth.client-credentials http-auth config
  | Ok tokens ->
    println "已收到访问令牌"
  | Err err ->
    println "OAuth错误：${err}"

刷新令牌

match OAuth.refresh-token http-auth config refresh-token
  | Ok tokens -> println "已刷新访问令牌"
  | Err err -> println "刷新失败：${err}"

认证请求

match OAuth.get http-auth "https://api.example.com/user" tokens.access-token
  | Ok response ->
    println "状态码：${Int.to-string response.status}"
    println response.body
  | Error err ->
    println "API错误：${err}"

json-body = "{\"name\":\"Kit\"}"

match OAuth.post http-auth "https://api.example.com/resources" json-body tokens.access-token
  | Ok response -> println "已创建：${Int.to-string response.status}"
  | Error err -> println "API错误：${err}"

提供方预设

内置的提供方辅助函数返回一个OAuthConfig，其中已填好对应提供方的授权端点和令牌端点：

辅助函数	提供方
`OAuth.github`	GitHub
`OAuth.google`	Google
`OAuth.microsoft`	Microsoft Entra ID / Azure AD
`OAuth.discord`	Discord
`OAuth.slack`	Slack
`OAuth.gitlab`	GitLab
`OAuth.custom`	任意OAuth 2.0提供方

安全说明

始终在交换授权码之前验证回调中的state值。
生产环境中使用HTTPS重定向URI。
不要记录访问令牌、刷新令牌、授权码或客户端密钥。
将刷新令牌存储在适合你应用的安全存储中。
使用环境变量或密钥管理器来管理客户端密钥。
将检入仓库的示例视为模拟运行示例。它们被设计为对等安全，不会连接真实OAuth提供方。

开发

运行示例

使用解释器运行示例：

kit run examples/github.kit
kit run examples/client-credentials.kit

编译示例为原生二进制：

kit build examples/github.kit && ./github

运行测试

运行测试套件：

kit test

带覆盖率运行测试套件：

kit test --coverage

运行kit dev

运行标准开发工作流：

kit dev

这将执行：

检查格式
类型检查src/中的源文件
类型检查examples/中的示例
带覆盖率运行tests/中的测试

运行对等检查

对示例执行解释器/编译器的对等性检查：

kit parity --failures-only

示例使用确定性输出并避免实时网络调用，以便对等检查可以可靠地比较解释器输出和编译后可执行文件的输出。

生成文档

从文档注释生成API文档：

kit doc

注意：包含文档注释（##）的Kit源文件将在docs/*.html生成HTML文档。

清理构建产物

移除生成的文件、缓存、对等检查结果、文档、锁文件和原生构建产物：

kit task clean

注意：在kit.toml中定义。

本地安装

为开发目的在本地安装本包：

kit install

这将安装包到~/.kit/packages/@kit/oauth/，使其可在其他项目中作为Kit.Oauth导入。

许可证

本包基于MIT许可证发布 - 详见LICENSE。

kit-oauth v2026.7.12

分类