Connect a server integration with OAuth and keep its token fresh

# once: a PKCE pair and the URL to open in a private window
VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n')
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
echo "https://www.example.com/oauth/authorize?response_type=code&client_id=$COREDNA_CLIENT_ID&redirect_uri=https%3A%2F%2Fsync.example.org%2Foauth%2Fcallback&scope=offline&state=$(openssl rand -hex 16)&code_challenge=$CHALLENGE&code_challenge_method=S256"

# then, within five minutes of approving: exchange the code
curl https://www.example.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://sync.example.org/oauth/callback \
  -d client_id="$COREDNA_CLIENT_ID" \
  -d client_secret="$COREDNA_CLIENT_SECRET" \
  -d code_verifier="$VERIFIER"

{
  "access_token": "CDNA-A-…",
  "expires_at": 0,
  "refresh_token": "…"
}

// coredna.js: the one module that holds the integration's credentials (Node 18 or later)
import { readFile, writeFile, rename } from 'node:fs/promises';

const SITE = process.env.COREDNA_URL;                 // https://www.example.com
const CLIENT_ID = process.env.COREDNA_CLIENT_ID;
const CLIENT_SECRET = process.env.COREDNA_CLIENT_SECRET;
const STORE = process.env.COREDNA_TOKEN_FILE;         // readable by this service only

let tokens = null;
let refreshing = null;                                // one refresh at a time in this process

async function load() {
  tokens ??= JSON.parse(await readFile(STORE, 'utf8'));
  return tokens;
}

async function save(next) {
  await writeFile(STORE + '.tmp', JSON.stringify(next), { mode: 0o600 });
  await rename(STORE + '.tmp', STORE);                // never a half-written file
  tokens = next;
}

async function refresh() {
  const { refresh_token } = await load();
  const response = await fetch(SITE + '/oauth/token', {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,                   // in the body: a Basic header is refused
    }),
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw new Error('OAuth refresh failed (' + (data.error ?? response.status) + '): sign in as the integration user again');
  }
  await save({
    access_token: data.access_token,
    expires_at: Date.now() + data.expires_in * 1000,
    refresh_token: data.refresh_token ?? refresh_token, // a new one on the fiftieth exchange
  });
}

async function accessToken(force = false) {
  const t = await load();
  if (force || t.expires_at - Date.now() < 5 * 60 * 1000) {
    refreshing ??= refresh().finally(() => { refreshing = null; });
    await refreshing;
  }
  return tokens.access_token;
}

export async function coredna(method, path, { query, body } = {}, retried = false) {
  const url = new URL(SITE + '/cdna-api/' + path);
  for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, v);
  const response = await fetch(url, {
    method,
    headers: {
      Authorization: 'Bearer ' + await accessToken(retried),
      Accept: 'application/json',
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await response.json().catch(() => ({}));
  if (response.status === 403 && !retried && /Token doesn't exist or is not valid/.test(data.message ?? '')) {
    return coredna(method, path, { query, body }, true);   // refresh once and send it again
  }
  if (!response.ok) throw new Error(method + ' ' + path + ': ' + response.status + ' ' + (data.message ?? ''));
  return data;
}