Version0.9.2Verifiednot yet verifiedLicenseBSD-3-Clause

sigil-oauth

OAuth 2.0 client library for Sigil

Report a bug or suggest a feature
Readme

sigil-oauth

OAuth 2.0 client library for Sigil — shared auth for YouTube, Twitch, Wise, and other API clients.

Modules

(sigil oauth) — Core OAuth2 client

Records, authorization URL generation with PKCE, token exchange, token refresh, token validation, and provider presets.

(sigil oauth store) — Token persistence

Save and load tokens as JSON files under ~/.config/sigil/<service>/tokens.json.

(sigil oauth server) — Local callback server

Temporary localhost HTTP server that captures the OAuth redirect, exchanges the authorization code for tokens, and shuts down.

Quick Start

(import (sigil oauth)
        (sigil oauth store)
        (sigil oauth server))

;; 1. Create a provider config
(define config
  (oauth-google-config
    "your-client-id"
    "your-client-secret"
    '("https://www.googleapis.com/auth/youtube")))

;; 2. Run the full authorization flow (opens browser, waits for callback)
(define tokens
  (oauth-run-authorization-flow config (current-second)))

;; 3. Save tokens for later
(oauth-save-tokens "youtube" tokens)

;; 4. Load tokens in a future session
(define tokens (oauth-load-tokens "youtube"))

;; 5. Ensure token is valid before making API calls (auto-refreshes if expired)
(define tokens (oauth-ensure-valid-token config tokens (current-second)))

Manual Flow

For more control over the authorization flow:

Read the rest
;; Generate state and PKCE
(define state (oauth-generate-state))
(define pkce (oauth-generate-pkce))

;; Build the authorization URL
(define auth-url
  (oauth-authorization-url config state #{ pkce: pkce }))

;; Display URL for user to visit...
;; Then start the callback server to capture the redirect:
(define tokens
  (oauth-start-callback-server config state (current-second)
    #{ pkce-verifier: (oauth-pkce-verifier pkce) }))

Provider Presets

Google / YouTube

(oauth-google-config client-id client-secret scopes)
(oauth-google-config client-id client-secret scopes #{ redirect-uri: "..." })

Sets access_type=offline and prompt=consent automatically to ensure refresh tokens are issued.

Twitch

(oauth-twitch-config client-id client-secret scopes)
(oauth-twitch-config client-id client-secret scopes #{ redirect-uri: "..." })

Custom Provider

(oauth-config
  client-id:     "..."
  client-secret: "..."
  auth-url:      "https://provider.com/oauth2/authorize"
  token-url:     "https://provider.com/oauth2/token"
  scopes:        '("scope1" "scope2")
  redirect-uri:  "http://localhost:8085/callback"
  extra-params:  #{ custom_param: "value" })

Token Management

;; Check if a token has expired (with 60s grace period)
(oauth-token-expired? tokens (current-second))

;; Custom grace period (300 seconds)
(oauth-token-expired? tokens (current-second) 300)

;; Refresh manually
(define new-tokens
  (oauth-refresh-token config (oauth-tokens-refresh-token tokens) (current-second)))

;; Auto-refresh: returns existing tokens if valid, refreshes if expired
(define valid-tokens
  (oauth-ensure-valid-token config tokens (current-second)))

;; Validate against a provider endpoint
(oauth-validate-token tokens "https://id.twitch.tv/oauth2/validate")

Token Storage

Tokens are stored as JSON in ~/.config/sigil/<service-name>/tokens.json:

(oauth-save-tokens "youtube" tokens)           ;; default path
(oauth-save-tokens "youtube" tokens "/custom/path.json")  ;; custom path

(oauth-load-tokens "youtube")      ;; returns oauth-tokens or #f
(oauth-clear-tokens "youtube")     ;; returns #t if deleted, #f if missing

Dependencies

  • sigil-stdlib
  • sigil-http
  • sigil-json
  • sigil-log

Building

sigil deps install
sigil build
sigil test
Clone

$ git clone https://codeberg.org/sigil/sigil-oauth

Releases

v0.9.2 — latest by version, released 2 Sep 2026

All releases — 3 tags in this repository.

Source

Browse the latest source

One page per file, and every line has a permalink.

Recent commitsAtom
3 Sepcommit

Relock: record the >= pin form

6c9e56c8

3 Sepcommit

Pin monorepo packages with >= instead of caret

16b83500

2 Sepcommit

Relock monorepo pins to ^0.21

d2345ab8

2 Sepcommit

Relock onto sigil 0.20 and add the standard pipeline

8fd36cb6

2 Sepcommit

Release v0.9.2: make the package resolvable again

762bd8da

1 Augcommit

Add docket repo descriptor (status/summary/group) for the Azoth estate render

a052e8bf

1 Aprcommit

Migrate to 0.9.1 transitive deps with version ranges and lockfile

b924a7d1

29 Marcommit

Pin dependencies to version tags

96bb961d

25 Marcommit

Add .mcp.json to gitignore

49fa7c68

25 Marcommit

Implement OAuth 2.0 client library

59e67b56

25 Marcommit

Initial package scaffolding

dfb6598f

25 Marcommit

Initial commit

6e8676dc

The last 20 commits keep a page here. Everything older lives in the clone.