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