README.md — sigil-oauth

1# sigil-oauth

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

5## Modules

7### `(sigil oauth)` — Core OAuth2 client

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

11### `(sigil oauth store)` — Token persistence

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

15### `(sigil oauth server)` — Local callback server

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

19## Quick Start

21```scheme

22(import (sigil oauth)

23 (sigil oauth store)

24 (sigil oauth server))

26;; 1. Create a provider config

27(define config

28 (oauth-google-config

29 "your-client-id"

30 "your-client-secret"

31 '("https://www.googleapis.com/auth/youtube")))

33;; 2. Run the full authorization flow (opens browser, waits for callback)

34(define tokens

35 (oauth-run-authorization-flow config (current-second)))

37;; 3. Save tokens for later

38(oauth-save-tokens "youtube" tokens)

40;; 4. Load tokens in a future session

41(define tokens (oauth-load-tokens "youtube"))

43;; 5. Ensure token is valid before making API calls (auto-refreshes if expired)

44(define tokens (oauth-ensure-valid-token config tokens (current-second)))

45```

47## Manual Flow

49For more control over the authorization flow:

51```scheme

52;; Generate state and PKCE

53(define state (oauth-generate-state))

54(define pkce (oauth-generate-pkce))

56;; Build the authorization URL

57(define auth-url

58 (oauth-authorization-url config state #{ pkce: pkce }))

60;; Display URL for user to visit...

61;; Then start the callback server to capture the redirect:

62(define tokens

63 (oauth-start-callback-server config state (current-second)

64 #{ pkce-verifier: (oauth-pkce-verifier pkce) }))

65```

67## Provider Presets

69### Google / YouTube

71```scheme

72(oauth-google-config client-id client-secret scopes)

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

74```

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

78### Twitch

80```scheme

81(oauth-twitch-config client-id client-secret scopes)

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

83```

85### Custom Provider

87```scheme

88(oauth-config

89 client-id: "..."

90 client-secret: "..."

91 auth-url: "https://provider.com/oauth2/authorize"

92 token-url: "https://provider.com/oauth2/token"

93 scopes: '("scope1" "scope2")

94 redirect-uri: "http://localhost:8085/callback"

95 extra-params: #{ custom_param: "value" })

96```

98## Token Management

100```scheme

101;; Check if a token has expired (with 60s grace period)

102(oauth-token-expired? tokens (current-second))

103

104;; Custom grace period (300 seconds)

105(oauth-token-expired? tokens (current-second) 300)

106

107;; Refresh manually

108(define new-tokens

109 (oauth-refresh-token config (oauth-tokens-refresh-token tokens) (current-second)))

110

111;; Auto-refresh: returns existing tokens if valid, refreshes if expired

112(define valid-tokens

113 (oauth-ensure-valid-token config tokens (current-second)))

114

115;; Validate against a provider endpoint

116(oauth-validate-token tokens "https://id.twitch.tv/oauth2/validate")

117```

118

119## Token Storage

120

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

122

123```scheme

124(oauth-save-tokens "youtube" tokens) ;; default path

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

126

127(oauth-load-tokens "youtube") ;; returns oauth-tokens or #f

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

129```

130

131## Dependencies

132

133- sigil-stdlib

134- sigil-http

135- sigil-json

136- sigil-log

137

138## Building

139

140```bash

141sigil deps install

142sigil build

143sigil test

144```