kit-oauth

Biblioteca cliente OAuth 2.0 para aplicações Kit

[TOC]

Arquivos

Dependências

Nenhuma dependência de pacote Kit.

Este pacote utiliza os módulos HTTP e Time embutidos do Kit. O manifesto do pacote solicita a capacidade net porque os auxiliares de troca de token e requisições autenticadas realizam chamadas HTTP.

Instalação

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 Autorização

Após o provedor redirecionar de volta para sua URL de callback, valide que o state retornado corresponde ao state que você gerou, então troque o código de autorização 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 Autorização com PKCE

Use PKCE para clientes públicos, como aplicativos desktop, aplicativos móveis e fluxos baseados em 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}"

O auxiliar PKCE atual usa o método de desafio plain. Ele está estruturado para poder migrar para S256 assim que um auxiliar de string SHA256 estiver disponível.

Credenciais de Cliente

Use credenciais de cliente para autenticação 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 Atualização

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

Requisições 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}"

Predefinições de Provedores

Os auxiliares de provedor embutidos retornam um OAuthConfig com os endpoints de autorização e token do provedor preenchidos:

Notas de Segurança

• Sempre valide o valor do state do callback antes de trocar um código de autorização.
• Use URIs de redirecionamento HTTPS em produção.
• Não registre tokens de acesso, tokens de atualização, códigos de autorização ou segredos de cliente.
• Armazene tokens de atualização em armazenamento seguro apropriado para sua aplicação.
• Use variáveis de ambiente ou um gerenciador de segredos para segredos de cliente.
• Trate os exemplos incluídos como exemplos de execução simulada. Eles são projetados para serem seguros para paridade e não contatam provedores OAuth reais.

Desenvolvimento

Executando Exemplos

Execute exemplos com o interpretador:

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

Compile um exemplo para um binário nativo:

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

Executando Testes

Execute a suíte de testes:

kit test

Execute a suíte de testes com cobertura:

kit test --coverage

Executando kit dev

Execute o fluxo de trabalho padrão de desenvolvimento:

kit dev

Isso irá:

1. Verificar formatação
2. Verificar tipos dos arquivos fonte em src/
3. Verificar tipos dos exemplos em examples/
4. Executar testes em tests/ com cobertura

Executando Paridade

Execute verificações de paridade entre interpretador/compilador para os exemplos:

kit parity --failures-only

Os exemplos usam saída determinística e evitam chamadas de rede ao vivo para que a paridade possa comparar a saída do interpretador e do executável compilado de forma confiável.

Gerando Documentação

Gere documentação da API a partir de comentários de documentação:

kit doc

Nota: Fontes Kit com comentários de documentação (##) gerarão documentos HTML em docs/*.html.

Limpando Artefatos de Build

Remova arquivos gerados, caches, resultados de paridade, documentação, arquivos de bloqueio e artefatos de build nativos:

kit task clean

Nota: Definição em kit.toml.

Instalação Local

Para instalar este pacote localmente para desenvolvimento:

kit install

Isso instala o pacote em ~/.kit/packages/@kit/oauth/, tornando-o disponível para importação como Kit.Oauth em outros projetos.

Licença

Este pacote é lançado sob a Licença MIT - veja LICENSE para detalhes.