kit-oauth

Biblioteca cliente OAuth 2.0 para aplicaciones Kit

[TOC]

Archivos

Dependencias

No hay dependencias de paquetes Kit.

Este paquete utiliza los módulos integrados HTTP y Time de Kit. El manifiesto del paquete solicita la capacidad net porque los ayudantes de intercambio de tokens y solicitudes autenticadas realizan llamadas HTTP.

Instalación

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

Uso

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 "Open this authorization URL:"
  println auth-url

main

Código de Autorización

Después de que el proveedor redirija de vuelta a tu URL de callback, valida que el state devuelto coincida con el estado que generaste, luego intercambia el código de autorización por tokens:

match OAuth.exchange-code http-auth config code
  | Ok tokens ->
    println "Token type: ${tokens.token-type}"
    println "Expires in: ${Int.to-string tokens.expires-in} seconds"
  | Err err ->
    println "OAuth error: ${err}"

Código de Autorización con PKCE

Usa PKCE para clientes públicos como aplicaciones de escritorio, aplicaciones móviles y flujos basados en navegador:

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 "Access token received"
  | Err err -> println "OAuth error: ${err}"

El ayudante PKCE actual utiliza el método de desafío plain. Está estructurado para poder migrar a S256 una vez que esté disponible un ayudante SHA256 para cadenas.

Credenciales de Cliente

Usa credenciales de cliente para autenticación máquina a máquina:

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 "Access token received"
  | Err err ->
    println "OAuth error: ${err}"

Tokens de Refresco

match OAuth.refresh-token http-auth config refresh-token
  | Ok tokens -> println "Refreshed access token"
  | Err err -> println "Refresh failed: ${err}"

Solicitudes Autenticadas

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

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

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

Predefiniciones de Proveedores

Los ayudantes de proveedores integrados devuelven un OAuthConfig con los endpoints de autorización y token del proveedor completados:

Notas de Seguridad

• Valida siempre el valor de state en el callback antes de intercambiar un código de autorización.
• Usa URIs de redirección HTTPS en producción.
• No registres tokens de acceso, tokens de refresco, códigos de autorización ni secretos de cliente.
• Almacena los tokens de refresco en un almacenamiento seguro adecuado para tu aplicación.
• Usa variables de entorno o un gestor de secretos para los secretos de cliente.
• Trata los ejemplos incluidos en el repositorio como ejemplos de prueba (dry-run). Están diseñados para ser seguros en cuanto a paridad y no contactan proveedores OAuth reales.

Desarrollo

Ejecutar Ejemplos

Ejecuta los ejemplos con el intérprete:

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

Compila un ejemplo a un binario nativo:

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

Ejecutar Pruebas

Ejecuta el conjunto de pruebas:

kit test

Ejecuta el conjunto de pruebas con cobertura:

kit test --coverage

Ejecutar kit dev

Ejecuta el flujo de trabajo de desarrollo estándar:

kit dev

Esto hará:

1. Verificar formato
2. Verificar tipos de archivos fuente en src/
3. Verificar tipos de ejemplos en examples/
4. Ejecutar pruebas en tests/ con cobertura

Ejecutar Paridad

Ejecuta verificaciones de paridad intérprete/compilador para los ejemplos:

kit parity --failures-only

Los ejemplos usan salida determinista y evitan llamadas de red en vivo para que la paridad pueda comparar de manera confiable la salida del intérprete y del ejecutable compilado.

Generar Documentación

Genera documentación de API a partir de comentarios de documentación:

kit doc

Nota: Los fuentes Kit con comentarios de documentación (##) generarán documentos HTML en docs/*.html.

Limpiar Artefactos de Compilación

Elimina archivos generados, cachés, resultados de paridad, docs, archivos de bloqueo y artefactos de compilación nativos:

kit task clean

Nota: Definido en kit.toml.

Instalación Local

Para instalar este paquete localmente para desarrollo:

kit install

Esto instala el paquete en ~/.kit/packages/@kit/oauth/, haciéndolo disponible para importar como Kit.Oauth en otros proyectos.

Licencia

Este paquete se publica bajo la Licencia MIT - consulta LICENSE para más detalles.