GitHub App authentication: sign an app JWT with the App's RSA private
key, then mint short-lived installation tokens with it. Built on
hot.dev/jwt and the ::hot::crypto RS256 natives.
Example
::app ::github::app
app-id 12345
private-key-pem ::hot::ctx/get("acme.github-app-key")
installation-id 678
token ::app/installation-token(app-id, private-key-pem, installation-id)
// Tokens live ~1 hour. Set the runtime-minted secret for this run;
// every ::github wrapper then authenticates with it.
::hot::ctx/set-secret("github.token", token.token)
issues ::github::issues/list-issues("acme", "api")
// Or act for one installation on one call. The token is minted once
// and cached for the run, keyed by a hash of the identity.
tenant {app-id: app-id, private-key: private-key-pem, installation-id: installation-id}
issues ::github::issues/list-issues("acme", "api", {}, tenant)
Values
TOKEN_CACHE_PREFIX
TOKEN_CACHE_PREFIX: Str "github.app-token."
TOKEN_TTL_MS
TOKEN_TTL_MS: Int 3300000
Functions
app-jwt
fn (app-id: Any, private-key-pem: Str): Str
Sign a GitHub App JWT (RS256) from the App id and its PEM private key
(the .pem GitHub generates — PKCS#1 BEGIN RSA PRIVATE KEY — or a
PKCS#8 conversion).
Example
jwt ::github::app/app-jwt(12345, ::hot::ctx/get("acme.github-app-key"))
::github::api/json("GET", "/app", {}, "", jwt).slug
build-app-claims
fn (app-id: Any): Map
Build the app JWT claims per GitHub's spec: iat 60s in the past (clock
drift), exp at most 10 minutes out, iss = the App id.
Example
::github::app/build-app-claims(12345).iss // "12345"
cached-installation-token
fn (identity: Map, settings: Map): Str
An installation token for identity ({app-id, private-key, installation-id}), minted once and cached with
::hot::ctx/set-secret under token-cache-key until 5 minutes before
it expires. Each identity has its own entry, so tenants and parallel
flows can't pick up each other's token, and github.token is left
alone. settings carries base-url and api-version. Returns the
token, or the Err from signing or minting.
Example
identity {
app-id: 12345,
private-key: ::hot::ctx/get("acme.github-app-key"),
installation-id: 678
}
token ::github::app/cached-installation-token(identity, ::github::api/settings-from({}))
::github::users/get-user("octocat", {token: token}).login
installation-token
fn (app-id: Any, private-key-pem: Str, installation-id: Any): Map
fn (app-id: Any, private-key-pem: Str, installation-id: Any, opts: Map): Map
POST /app/installations/{id}/access_tokens - Mint an installation
access token (~1 hour). Returns {token, expires_at, permissions}.
Set token.token as the github.token context variable
(::hot::ctx/set-secret("github.token", token.token) for
runtime-minted tokens) so the endpoint wrappers pick it up, or pass
it explicitly via the final arity of ::github::api/request/json.
To act for many installations in one run, pass app-id, private-key
and installation-id in any function's opts instead. opts here
takes base-url and api-version. The minted token is masked in the
run's call records.
Example
minted ::github::app/installation-token(12345, ::hot::ctx/get("acme.github-app-key"), 678)
::hot::ctx/set-secret("github.token", minted.token)
minted.expires_at
is-fresh
fn (entry: Any, now: Int): Bool
True when a cache entry holds a token that has not reached its expiry.
Example
::github::app/is-fresh({token: "test-token", expires-at: 2000}, 1000) // true
::github::app/is-fresh({token: "test-token", expires-at: 2000}, 3000) // false
list-installations
fn (app-id: Any, private-key-pem: Str): Any
fn (app-id: Any, private-key-pem: Str, opts: Map): Any
GET /app/installations - The installations of your App (authenticated with the app JWT).
Example
installations ::github::app/list-installations(12345, ::hot::ctx/get("acme.github-app-key"))
map(installations, %.account.login)
token-cache-key
fn (identity: Map, base-url: Str): Str
The context key an installation token is cached under: a SHA-256 of the App id, installation id, private key and API root, so neither the key nor any id appears in it.
Example
identity {app-id: 12345, installation-id: 678, private-key: "sample-key"}
key ::github::app/token-cache-key(identity, "https://api.github.com")
starts-with(key, "github.app-token.") // true