# github-oauth

GitHub OAuth URL generation and token exchange helpers for OCaml.

## Overview

This library provides helpers for implementing GitHub OAuth 2.0 authorization flows. It supports both GitHub Apps (with token expiry and refresh tokens) and traditional OAuth Apps.

## Features

- Cryptographically secure state generation for CSRF protection
- Authorization URL generation with scope support
- Token exchange request body generation (JSON)
- Token response parsing (access tokens, refresh tokens, expiry)
- Refresh token request body generation

## Installation

```
opam install github-oauth
```

## Usage

```ocaml
(* Generate authorization URL *)
let state = Github_oauth.generate_state () in
let url =
  Github_oauth.authorization_url ~client_id:"your_client_id"
    ~callback_url:"https://yourapp.com/callback" ~state ~scope:[ "repo" ]
in

(* After user authorizes, exchange code for token *)
let body =
  Github_oauth.exchange_request_body ~client_id:"your_client_id"
    ~client_secret:"your_secret" ~code ~redirect_uri:"https://yourapp.com/callback"
in
(* POST body to Github_oauth.access_token_url with headers:
   Content-Type: application/json
   Accept: application/json *)

(* Parse the response *)
match Github_oauth.parse_token_response response_body with
| Ok token ->
    Printf.printf "Access token: %s\n" token.access_token;
    (* For GitHub Apps, handle refresh *)
    (match token.refresh_token with
     | Some rt -> (* store for later refresh *)
     | None -> (* OAuth App, no refresh needed *))
| Error e ->
    Printf.eprintf "Error: %a\n" Github_oauth.pp_parse_token_error e
```

## API

- `Github_oauth.generate_state` - Generate CSRF protection state
- `Github_oauth.authorization_url` - Build GitHub authorization URL
- `Github_oauth.access_token_url` - Token exchange endpoint URL
- `Github_oauth.exchange_request_body` - Build token exchange request
- `Github_oauth.parse_token_response` - Parse token response JSON
- `Github_oauth.refresh_request_body` - Build refresh token request

## Standards

- [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) - OAuth 2.0
- [GitHub OAuth Documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)

## Related Work

- [github-oauth2](https://github.com/tmattio/ocaml-github-oauth2) - Full OAuth2 client with HTTP handling
- [oauth2](https://opam.ocaml.org/packages/oauth2/) - Generic OAuth2 library

This library focuses on URL and request body generation without HTTP dependencies, allowing integration with any HTTP client (Cohttp, Dream, Eio, etc.).

## Licence

MIT License. See [LICENSE.md](LICENSE.md) for details.