@throng/cli 0.1.0

package/dist/graphql.js

@@ -0,0 +1,129 @@
+import { AuthRequiredError, SIGN_IN_COMMAND } from "./errors.js";
+import { getAccessToken } from "./oauth/session.js";
+import { printable } from "./oauth/token-request.js";
+/** A data query can legitimately run long, so this is well above the 15 s a token exchange gets. */
+export const GRAPHQL_TIMEOUT_MS = 60 * 1000;
+/** The server answered, but not with data: a transport failure or a refusal on the merits. */
+export class ApiError extends Error {
+    code;
+    name = "ApiError";
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** `x-throng-organisation` was rejected as malformed (`ORGANISATION_INVALID`). */
+export class OrgInvalidError extends ApiError {
+    name = "OrgInvalidError";
+}
+/** The signed-in user is not a member of the selected organisation (`ORGANISATION_ACCESS_DENIED`). */
+export class OrgAccessDeniedError extends ApiError {
+    name = "OrgAccessDeniedError";
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The error entries of a GraphQL-shaped `errors` array; anything else yields none. */
+function errorEntries(value) {
+    return Array.isArray(value) ? value.filter(isObject) : [];
+}
+function codeOf(entries) {
+    for (const entry of entries) {
+        const code = isObject(entry.extensions) ? entry.extensions.code : undefined;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}
+/**
+ * Mutations answer refusals on the merits as `{ result, errors }` payloads with
+ * HTTP 200. Gather the entries of every payload among the root fields of `data`.
+ */
+function payloadErrors(data) {
+    if (!isObject(data))
+        return [];
+    return Object.values(data).flatMap((field) => (isObject(field) ? errorEntries(field.errors) : []));
+}
+/**
+ * POST `document` to `${host}/api/graphql` as the signed-in user and return its `data`.
+ *
+ * Failures map as follows, and the access token never reaches a message:
+ * - HTTP 401, by status alone (the body is not GraphQL-shaped): `AuthRequiredError`.
+ * - `extensions.code` of the first coded entry of `errors[]` is `ApiError.code`;
+ *   `ORGANISATION_INVALID` and `ORGANISATION_ACCESS_DENIED` select their own classes.
+ * - Any other `errors[]`, top-level (a validation error arrives with HTTP 200 and no
+ *   `data`) or in a mutation payload, becomes one `ApiError` listing every message.
+ * - A non-2xx without GraphQL errors, or a body that is not JSON, becomes an `ApiError`
+ *   naming the status.
+ */
+export async function graphql(host, document, opts = {}) {
+    const token = await getAccessToken(host);
+    const headers = {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+    };
+    if (opts.orgId !== undefined)
+        headers["x-throng-organisation"] = opts.orgId;
+    const payload = { query: document };
+    if (opts.variables !== undefined)
+        payload.variables = opts.variables;
+    const signal = AbortSignal.timeout(GRAPHQL_TIMEOUT_MS);
+    let status;
+    let ok;
+    let text;
+    try {
+        const response = await fetch(`${host}/api/graphql`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            signal,
+        });
+        ({ status, ok } = response);
+        // A stall after the headers must be reported as a timeout, never as a malformed answer.
+        text = await response.text();
+    }
+    catch (error) {
+        if (signal.aborted) {
+            throw new ApiError(`Request to ${host} timed out after ${GRAPHQL_TIMEOUT_MS / 1000} seconds`);
+        }
+        throw error;
+    }
+    if (status === 401) {
+        throw new AuthRequiredError(`${host} rejected your session. Run \`${SIGN_IN_COMMAND}\` to sign in again.`);
+    }
+    // Server text lands in a terminal: drop the token should it be echoed, then sanitise.
+    const clean = (value) => printable(token === "" ? value : value.replaceAll(token, "[redacted]"));
+    const messagesOf = (entries) => entries.map((entry) => clean(typeof entry.message === "string" ? entry.message : "unknown error")).join("; ");
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new ApiError(`GraphQL request to ${host} returned HTTP ${status} and a body that is not JSON`);
+    }
+    if (!isObject(body)) {
+        throw new ApiError(`GraphQL request to ${host} returned HTTP ${status} and an unexpected body`);
+    }
+    const topLevel = errorEntries(body.errors);
+    const code = codeOf(topLevel);
+    const safeCode = code === undefined ? undefined : clean(code);
+    if (code === "ORGANISATION_INVALID") {
+        const named = opts.orgId === undefined ? "" : ` (${clean(opts.orgId)})`;
+        throw new OrgInvalidError(`Invalid organisation${named}: ${messagesOf(topLevel)}`, safeCode);
+    }
+    if (code === "ORGANISATION_ACCESS_DENIED") {
+        throw new OrgAccessDeniedError(messagesOf(topLevel), safeCode);
+    }
+    if (topLevel.length > 0) {
+        const prefix = ok ? "" : `GraphQL request failed (HTTP ${status}): `;
+        throw new ApiError(`${prefix}${messagesOf(topLevel)}`, safeCode);
+    }
+    if (!ok) {
+        throw new ApiError(`GraphQL request to ${host} failed (HTTP ${status})`);
+    }
+    const refusals = payloadErrors(body.data);
+    if (refusals.length > 0)
+        throw new ApiError(messagesOf(refusals));
+    if (body.data === undefined || body.data === null) {
+        throw new ApiError(`GraphQL response from ${host} carried neither data nor errors`);
+    }
+    return body.data;
+}

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Command, CommanderError } from "commander";
+import { registerApi } from "./commands/api.js";
+import { registerAuth } from "./commands/auth.js";
+import { registerOrg } from "./commands/org.js";
+import { registerToken } from "./commands/token.js";
+import { resolveHost } from "./config.js";
+import { AuthRequiredError } from "./errors.js";
+import { describeError, info } from "./output.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+/** Exit codes: 0 success, 1 API error or refused mutation, 2 usage error, 3 authentication required. */
+export function exitCodeFor(error) {
+    if (error instanceof AuthRequiredError)
+        return 3;
+    // Commander reports --help and --version through the same channel as its usage errors.
+    if (error instanceof CommanderError)
+        return error.exitCode === 0 ? 0 : 2;
+    // ApiError and every other failure (a raw network TypeError, a lock timeout, ...).
+    return 1;
+}
+export function buildProgram(deps = {}) {
+    const program = new Command();
+    program
+        .name("throng")
+        .version(version)
+        .option("--host <url>", "Throng host (default: $THRONG_HOST, then https://app.throng.dev)")
+        .option("--org <id>", "organisation id to act in, overriding the one chosen with `org use`")
+        .option("--json", "print machine-readable JSON where a command has a table form")
+        // Throw instead of exiting, so one handler owns the exit code. Set before the
+        // subcommands exist: they copy this setting when created.
+        .exitOverride();
+    // Resolved on first use, after the command line has been parsed, and only once.
+    let resolved;
+    const ctx = () => {
+        if (resolved)
+            return resolved;
+        const opts = program.opts();
+        let host;
+        try {
+            host = resolveHost(opts.host, process.env);
+        }
+        catch (error) {
+            return program.error(`error: ${error.message}`, { exitCode: 2 });
+        }
+        resolved = {
+            host,
+            org: opts.org,
+            json: opts.json === true,
+            stdin: deps.stdin ?? process.stdin,
+            openBrowser: deps.openBrowser,
+            exitCode: 0,
+        };
+        return resolved;
+    };
+    registerAuth(program, ctx);
+    registerToken(program, ctx);
+    registerOrg(program, ctx);
+    registerApi(program, ctx);
+    return { program, exitCode: () => resolved?.exitCode ?? 0 };
+}
+/** Run the CLI and return its exit code. Never throws and never exits the process. */
+export async function run(args, deps = {}) {
+    const { program, exitCode } = buildProgram(deps);
+    try {
+        await program.parseAsync(args, { from: "user" });
+        return exitCode();
+    }
+    catch (error) {
+        // Commander has already written its own usage errors.
+        if (!(error instanceof CommanderError))
+            info(describeError(error));
+        return exitCodeFor(error);
+    }
+}
+// Only the real entry point exits the process. Resolve symlinks: `npm` installs `throng` as one.
+if (isEntryPoint(process.argv[1])) {
+    quietOnBrokenPipe();
+    process.exitCode = await run(process.argv.slice(2));
+}
+/**
+ * `throng api | head`, `| jq ... | head` and `| less` then `q` all close the pipe while we
+ * are still writing. Node reports that as an `error` event on stdout, and unhandled it
+ * prints a stack trace. The reader has gone, so there is nobody to tell: stop quietly,
+ * with 141 (128 + SIGPIPE), the status a shell reports for a process killed that way.
+ * Any other stdout error is a real failure and is rethrown.
+ */
+function quietOnBrokenPipe() {
+    process.stdout.on("error", (error) => {
+        if (error.code === "EPIPE")
+            process.exit(141);
+        throw error;
+    });
+}
+function isEntryPoint(invokedAs) {
+    if (!invokedAs)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(invokedAs)).href;
+    }
+    catch {
+        // `node dist/index` names a path that does not exist as written: Node appended the
+        // extension itself. Not being the entry point would make the CLI silently do nothing,
+        // so accept "this module is that path plus an extension".
+        return fileURLToPath(import.meta.url).startsWith(`${resolve(invokedAs)}.`);
+    }
+}

package/dist/oauth/login.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import open from "open";
+import { generatePkce } from "./pkce.js";
+import { postToken, printable } from "./token-request.js";
+export const CLIENT_ID = "01993b1c-8f42-7c00-9a1e-4d5f6a7b8c90";
+const SCOPE = "account";
+const CALLBACK_PATH = "/auth/callback";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+// The token exchange has not run when this is served, so it must not claim success.
+const SUCCESS_PAGE = page("Authorization received", "You can close this tab and return to your terminal.");
+const FAILURE_PAGE = page("Sign-in failed", "Authorization was not completed. Return to your terminal for details.");
+// Fixed strings only: nothing from the callback query is ever written into a page.
+function page(title, message) {
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title></head><body><h1>${title}</h1><p>${message}</p></body></html>`;
+}
+/**
+ * Sign in with the OAuth 2.1 authorization code flow and PKCE: open the browser at
+ * the host's authorize endpoint, receive the redirect on a loopback server bound to
+ * an ephemeral port, then exchange the code for tokens. Every failing callback is
+ * rejected before the code is exchanged.
+ */
+export async function login(host, opts = {}) {
+    const openBrowser = opts.openBrowser ??
+        (async (url) => {
+            await open(url);
+        });
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const { verifier, challenge } = generatePkce();
+    const state = randomBytes(16).toString("base64url");
+    const server = createServer();
+    let timer;
+    const callback = new Promise((resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`Login timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser`)), timeoutMs);
+        server.on("request", (req, res) => {
+            const reply = (status, text, extra = {}) => {
+                res.writeHead(status, { "content-type": "text/plain; charset=utf-8", connection: "close", ...extra });
+                res.end(text);
+            };
+            // A malformed request target makes `new URL` throw; that must not escape the handler.
+            let url;
+            try {
+                url = new URL(req.url ?? "/", "http://127.0.0.1");
+            }
+            catch {
+                reply(400, "Bad request");
+                return;
+            }
+            if (url.pathname !== CALLBACK_PATH) {
+                reply(404, "Not found");
+                return;
+            }
+            if (req.method !== "GET") {
+                reply(405, "Method not allowed", { allow: "GET" });
+                return;
+            }
+            const params = url.searchParams;
+            const failure = checkCallback(params, state, host);
+            res.writeHead(failure ? 400 : 200, {
+                "content-type": "text/html; charset=utf-8",
+                "x-content-type-options": "nosniff",
+                connection: "close",
+            });
+            res.end(failure ? FAILURE_PAGE : SUCCESS_PAGE);
+            if (failure)
+                reject(failure);
+            else
+                resolve(params.get("code"));
+        });
+    });
+    // The callback can settle while we are still awaiting `openBrowser`; the real
+    // handler is attached below, so keep that window from raising an unhandled rejection.
+    callback.catch(() => { });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", resolve);
+        });
+        const { port } = server.address();
+        const redirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+        const authorizeUrl = new URL(`${host}/oauth/authorize`);
+        authorizeUrl.search = new URLSearchParams({
+            response_type: "code",
+            client_id: CLIENT_ID,
+            redirect_uri: redirectUri,
+            scope: SCOPE,
+            state,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+        }).toString();
+        await openBrowser(authorizeUrl.toString());
+        const code = await callback;
+        return await exchangeCode(host, { code, verifier, redirectUri });
+    }
+    finally {
+        clearTimeout(timer);
+        server.close();
+        server.closeAllConnections();
+    }
+}
+/** Returns the reason the callback must be rejected, or null if it is acceptable. */
+function checkCallback(params, state, host) {
+    const error = params.get("error");
+    if (error !== null) {
+        const reason = printable(error);
+        return new Error(error === "access_denied"
+            ? "Login was declined (access_denied)"
+            : `Authorization failed: ${reason}`);
+    }
+    if (params.get("state") !== state) {
+        return new Error("Callback state did not match the request; aborting (possible CSRF)");
+    }
+    // RFC 9207: an absent iss is tolerated, a present-and-wrong one is not. The server's
+    // issuer is a bare origin, but the host may carry a subpath, so accept either form.
+    const iss = params.get("iss");
+    if (iss !== null && !acceptedIssuers(host).includes(iss.replace(/\/+$/, ""))) {
+        return new Error(`Callback issuer ${JSON.stringify(printable(iss))} did not match ${host}; aborting`);
+    }
+    if (!params.get("code")) {
+        return new Error("Callback did not include an authorization code");
+    }
+    return null;
+}
+function acceptedIssuers(host) {
+    return [host, new URL(host).origin];
+}
+function exchangeCode(host, { code, verifier, redirectUri }) {
+    return postToken(host, {
+        grant_type: "authorization_code",
+        code,
+        code_verifier: verifier,
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri,
+    }, [code, verifier], "Token exchange");
+}

package/dist/oauth/pkce.js

@@ -0,0 +1,14 @@
+import { createHash, randomBytes } from "node:crypto";
+/**
+ * Generate a PKCE (Proof Key for Code Exchange) pair for OAuth 2.1 authorization
+ * code flow with S256 challenge method.
+ *
+ * The verifier is a base64url-encoded random 32 bytes, which produces a 43-character
+ * string that falls within RFC 7636's 43–128 character range and unreserved-character
+ * set. The challenge is the base64url-encoded SHA-256 hash of the verifier.
+ */
+export function generatePkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}

package/dist/oauth/refresh.js

@@ -0,0 +1,24 @@
+import { AuthRequiredError, SIGN_IN_COMMAND } from "../errors.js";
+import { CLIENT_ID } from "./login.js";
+import { TokenEndpointError, postToken } from "./token-request.js";
+/**
+ * Exchange a refresh token for a new token pair.
+ *
+ * Refresh tokens rotate: the one passed in is spent by this call, and the
+ * caller must persist the returned pair before doing anything else. A 400 or
+ * 401 means the server rejected the token, which is never retryable, so it is
+ * an `AuthRequiredError`. Any other failure (5xx, network, timeout) is a plain
+ * `Error` because signing in again would not help. No error message carries
+ * either token.
+ */
+export async function refresh(host, refreshToken) {
+    try {
+        return await postToken(host, { grant_type: "refresh_token", refresh_token: refreshToken, client_id: CLIENT_ID }, [refreshToken], "Token refresh");
+    }
+    catch (error) {
+        if (error instanceof TokenEndpointError && (error.status === 400 || error.status === 401)) {
+            throw new AuthRequiredError(`The server rejected your session for ${host}. Run \`${SIGN_IN_COMMAND}\` to sign in again.`);
+        }
+        throw error;
+    }
+}

package/dist/oauth/revoke.js

@@ -0,0 +1,33 @@
+import { CLIENT_ID } from "./login.js";
+import { TOKEN_REQUEST_TIMEOUT_MS } from "./token-request.js";
+/**
+ * Ask the server to revoke a refresh token (RFC 7009) by POSTing it to
+ * `${host}/oauth/revoke`, which ends the whole grant.
+ *
+ * RFC 7009 answers 200 whether or not the token was valid, so the body carries
+ * nothing and is not read for meaning. Anything but a 200, a network failure or
+ * the timeout rejects with a message that names no token and no server text.
+ * Callers treat that as non-fatal: logging out must work offline.
+ */
+export async function revoke(host, refreshToken) {
+    const signal = AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS);
+    let status;
+    try {
+        const response = await fetch(`${host}/oauth/revoke`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ token: refreshToken, client_id: CLIENT_ID }),
+            signal,
+        });
+        ({ status } = response);
+        // Drain the body inside the timeout so the connection is released; its content is irrelevant.
+        await response.text();
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new Error("timed out waiting for the server");
+        throw error;
+    }
+    if (status !== 200)
+        throw new Error(`the server answered HTTP ${status}`);
+}

package/dist/oauth/session.js

@@ -0,0 +1,117 @@
+import { deleteCredentials, readCredentials, withLock, writeCredentials, } from "../credentials.js";
+import { AuthRequiredError, SIGN_IN_COMMAND } from "../errors.js";
+import { describeError } from "../output.js";
+import { refresh } from "./refresh.js";
+import { revoke } from "./revoke.js";
+export const REFRESH_THRESHOLD_SECONDS = 60;
+function notSignedIn(host) {
+    return new AuthRequiredError(`Not signed in to ${host}. Run \`${SIGN_IN_COMMAND}\` first.`);
+}
+function isFresh(creds) {
+    return creds.expires_at - Math.floor(Date.now() / 1000) > REFRESH_THRESHOLD_SECONDS;
+}
+/**
+ * A usable access token for the host, refreshing it first if fewer than
+ * `REFRESH_THRESHOLD_SECONDS` remain.
+ *
+ * Refresh tokens rotate on every use and the server treats a replayed one as
+ * theft, revoking the whole chain. So the refresh runs under the credentials
+ * lock, re-reads inside it (another process may have just renewed them), and
+ * persists the rotated pair before the new token is returned. If another
+ * process holds the lock for the whole wait, `LockTimeoutError` propagates; its
+ * message already says another command is probably refreshing.
+ */
+export async function getAccessToken(host) {
+    const stored = await readCredentials(host);
+    if (!stored)
+        throw notSignedIn(host);
+    if (isFresh(stored))
+        return stored.access_token;
+    return withLock(async () => {
+        // Re-read under the lock: whoever held it before us may already have rotated the token.
+        const current = await readCredentials(host);
+        if (!current)
+            throw notSignedIn(host);
+        if (isFresh(current))
+            return current.access_token;
+        // Dead credentials are deliberately kept when this throws AuthRequiredError;
+        // signing in again overwrites them.
+        const pair = await refresh(host, current.refresh_token);
+        try {
+            await writeCredentials(host, { ...current, ...pair });
+        }
+        catch (cause) {
+            // The server has already rotated the token, so the one still on disk is dead.
+            // Say so, naming the errno only: nothing from the tokens may reach the message.
+            const code = cause.code ?? "unknown error";
+            throw new Error(`Your session was refreshed but could not be saved (${code}), so it is no longer valid. Run \`${SIGN_IN_COMMAND}\` to sign in again.`, { cause });
+        }
+        return pair.access_token;
+    });
+}
+export async function getOrgId(host) {
+    return (await readCredentials(host))?.org_id;
+}
+/** When the stored access token expires, in epoch seconds. Reads only: it never refreshes. */
+export async function getExpiresAt(host) {
+    return (await readCredentials(host))?.expires_at;
+}
+/**
+ * Read-modify-write of the whole record, so it takes the lock: an unlocked
+ * write racing a refresh could put back a stale refresh token over a rotated one.
+ */
+export async function setOrgId(host, orgId) {
+    await withLock(async () => {
+        const current = await readCredentials(host);
+        if (!current)
+            throw notSignedIn(host);
+        await writeCredentials(host, { ...current, org_id: orgId });
+    });
+}
+export async function clearOrgId(host) {
+    await withLock(async () => {
+        const current = await readCredentials(host);
+        if (!current)
+            return;
+        const { org_id: _dropped, ...rest } = current;
+        await writeCredentials(host, rest);
+    });
+}
+/**
+ * Persist the tokens a sign-in just produced, replacing the whole record.
+ *
+ * Any previously stored `org_id` is dropped on purpose: a fresh sign-in may be a
+ * different user, and carrying over an organisation they are not a member of
+ * would make their very first command fail with `ORGANISATION_ACCESS_DENIED`, a
+ * confusing failure manufactured by our own bookkeeping. Signing in again as the
+ * same person costs one `throng org use`.
+ */
+export async function saveLogin(host, pair) {
+    await withLock(() => writeCredentials(host, { ...pair }));
+}
+/**
+ * Revoke the stored grant on the server, then forget it locally. A no-op when
+ * there are no stored credentials.
+ *
+ * Revocation is best-effort: forgetting the file is not enough, since a refresh
+ * token already copied elsewhere would stay valid for its full lifetime, but a
+ * user who cannot reach the server still needs to be signed out here. A failure
+ * is reported in the result, never thrown. It runs under the lock so the token
+ * revoked is the current one, not one a concurrent refresh has just rotated.
+ */
+export async function logout(host) {
+    return withLock(async () => {
+        const stored = await readCredentials(host);
+        let revokeFailure;
+        if (stored) {
+            try {
+                await revoke(host, stored.refresh_token);
+            }
+            catch (error) {
+                revokeFailure = describeError(error);
+            }
+        }
+        await deleteCredentials(host);
+        return revokeFailure === undefined ? {} : { revokeFailure };
+    });
+}

package/dist/oauth/token-request.js

@@ -0,0 +1,87 @@
+export const TOKEN_REQUEST_TIMEOUT_MS = 15 * 1000;
+/** The token endpoint answered with a non-2xx status. The message never carries the secrets sent. */
+export class TokenEndpointError extends Error {
+    status;
+    name = "TokenEndpointError";
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+// Server and callback text ends up in terminal output, so strip control
+// characters (escape sequences) and bound the length.
+export function printable(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?").slice(0, 200);
+}
+/**
+ * Every spelling in which a server might echo `secret` back: as-is,
+ * percent-encoded, and as `URLSearchParams` form-encodes it (which differs
+ * from `encodeURIComponent` for `~!'()*` and space).
+ */
+function spellings(secret) {
+    return [
+        secret,
+        encodeURIComponent(secret),
+        new URLSearchParams({ x: secret }).toString().slice(2),
+    ];
+}
+function redact(text, secrets) {
+    // Longest first, so a secret that contains another is not left half-redacted.
+    const variants = secrets
+        .filter((secret) => secret !== "")
+        .flatMap(spellings)
+        .sort((a, b) => b.length - a.length);
+    for (const variant of variants)
+        text = text.replaceAll(variant, "[redacted]");
+    return text;
+}
+/**
+ * POST a form to `${host}/oauth/token` and return the token pair it issues.
+ *
+ * The whole exchange, including reading the body, is bounded by one timeout.
+ * Non-2xx answers throw `TokenEndpointError` with the body redacted of every
+ * entry in `secrets` and sanitised. `label` names the operation in messages.
+ */
+export async function postToken(host, params, secrets, label) {
+    const signal = AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS);
+    let status;
+    let ok;
+    let text;
+    try {
+        const response = await fetch(`${host}/oauth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams(params),
+            signal,
+        });
+        ({ status, ok } = response);
+        // A stall after the headers must be reported as a timeout, never as a malformed answer.
+        text = await response.text();
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new Error(`${label} timed out waiting for the server`);
+        throw error;
+    }
+    if (!ok) {
+        throw new TokenEndpointError(`${label} failed (HTTP ${status}): ${printable(redact(text, secrets))}`, status);
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = null;
+    }
+    const { access_token, refresh_token, expires_in } = body ?? {};
+    if (typeof access_token !== "string" ||
+        typeof refresh_token !== "string" ||
+        typeof expires_in !== "number") {
+        throw new Error(`${label} returned a malformed response (missing tokens or expiry)`);
+    }
+    return {
+        refresh_token,
+        access_token,
+        expires_at: Math.floor(Date.now() / 1000) + expires_in,
+    };
+}