@apex-actions/cli 0.67.0

package/dist/src/infrastructure/control-plane-http.js

@@ -0,0 +1,458 @@
+// infrastructure layer — see ../../../../docs/conventions.md §1
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { NotConfiguredError, apiUrlFrom, resolveCredential } from './credentials.js';
+export { NotConfiguredError } from './credentials.js';
+/** The API refused, with its status, so a use case can tell a 403 from a 500. */
+export class HttpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+    }
+}
+/**
+ * Adapter: the control-plane REST API over the platform's `fetch`.
+ *
+ * The credential is resolved in control-plane ADR-0064's order (see
+ * `credentials.ts`): a customer's `APEX_TOKEN`, then the token `apex login`
+ * saved, then the operator's `APEX_ADMIN_TOKEN` — the machine principal, which
+ * keeps scripts and boot paths working when GitHub is unreachable (ADR-0006).
+ * A customer token reaches only the secrets and variables routes and `/me`;
+ * every other command answers with the server's 403, which says so.
+ *
+ * The token goes in the `authorization` header and nowhere else: not in a
+ * URL, not in an error, not in anything this class returns.
+ */
+export class HttpControlPlane {
+    #baseUrl;
+    #token;
+    #fetch;
+    /** Where the credential came from — for `apex whoami`, which never shows the credential. */
+    credentialSource;
+    constructor(config = {}) {
+        if (config.token !== undefined) {
+            if (config.token === '')
+                throw new NotConfiguredError();
+            this.#token = config.token;
+            this.#baseUrl = (config.baseUrl ?? apiUrlFrom()).replace(/\/$/, '');
+            this.credentialSource = 'env';
+        }
+        else {
+            const resolved = resolveCredential();
+            this.#token = resolved.token;
+            this.#baseUrl = (config.baseUrl ?? resolved.apiUrl).replace(/\/$/, '');
+            this.credentialSource = resolved.source;
+        }
+        this.#fetch = config.fetchImpl ?? fetch;
+    }
+    /** The control plane this client talks to. */
+    get baseUrl() {
+        return this.#baseUrl;
+    }
+    async whoami() {
+        return await this.#json('GET', '/api/v1/me');
+    }
+    // ── secrets and variables (values are write-only) ──
+    async listSecrets(target) {
+        const body = await this.#json('GET', `${this.#scopePath(target)}/secrets`);
+        return body.secrets;
+    }
+    async setSecret(target, name, value) {
+        await this.#noContent('PUT', `${this.#scopePath(target)}/secrets/${encodeURIComponent(name)}`, { value });
+    }
+    /**
+     * `apex logout`: revoke the token this client authenticates with. A 401 means
+     * it no longer counts anyway — expired or already revoked — which is the
+     * outcome logout wants, so it is not an error.
+     */
+    async revokeCurrentToken() {
+        const response = await this.#request('DELETE', '/api/v1/me/token');
+        if (response.ok || response.status === 401)
+            return;
+        throw new HttpError(await this.#errorMessage(response), response.status);
+    }
+    async deleteSecret(target, name) {
+        return await this.#deleted(`${this.#scopePath(target)}/secrets/${encodeURIComponent(name)}`);
+    }
+    async listVariables(target) {
+        const body = await this.#json('GET', `${this.#scopePath(target)}/variables`);
+        return body.variables;
+    }
+    async setVariable(target, name, value) {
+        await this.#noContent('PUT', `${this.#scopePath(target)}/variables/${encodeURIComponent(name)}`, { value });
+    }
+    async deleteVariable(target, name) {
+        return await this.#deleted(`${this.#scopePath(target)}/variables/${encodeURIComponent(name)}`);
+    }
+    #scopePath(target) {
+        return target.kind === 'org' ? '/api/v1/org' : this.#repoPath(target.owner, target.repo);
+    }
+    async #noContent(method, path, body) {
+        const response = await this.#request(method, path, body);
+        if (!response.ok)
+            throw new HttpError(await this.#errorMessage(response), response.status);
+    }
+    /**
+     * A bare 404 is "no such name"; a 404 that explains itself ("repository not
+     * found") is a refusal, and reporting it as a missing secret would send
+     * somebody looking for the wrong thing.
+     */
+    async #deleted(path) {
+        const response = await this.#request('DELETE', path);
+        if (response.status === 404) {
+            const text = await response.text();
+            let problem = {};
+            try {
+                problem = JSON.parse(text) ?? {};
+            }
+            catch {
+                // no body: the name was not there
+            }
+            if (typeof problem.error === 'string')
+                throw new HttpError(problem.error, 404);
+            return false;
+        }
+        if (!response.ok)
+            throw new HttpError(await this.#errorMessage(response), response.status);
+        return true;
+    }
+    async listRuns(repository) {
+        const path = repository === undefined
+            ? '/api/v1/runs?limit=100'
+            : `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/runs`;
+        const body = await this.#json('GET', path);
+        return body.runs;
+    }
+    async getRun(id) {
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(id)}`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async explainRun(runId) {
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/explain`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async explainDelivery(deliveryId) {
+        const response = await this.#request('GET', `/api/v1/deliveries/${encodeURIComponent(deliveryId)}/explain`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async reproduction(runId, job) {
+        const query = job === undefined ? '' : `?job=${encodeURIComponent(job)}`;
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/reproduction${query}`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async runTiming(runId) {
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/timing`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async runTests(runId) {
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/tests`);
+        if (response.status === 404)
+            return undefined;
+        return (await this.#decode(response));
+    }
+    async flakyTests(owner, repo) {
+        const body = await this.#json('GET', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/flaky-tests`);
+        return body.tests;
+    }
+    async runSnapshots(runId) {
+        const body = await this.#json('GET', `/api/v1/runs/${encodeURIComponent(runId)}/snapshots`);
+        return body.snapshots;
+    }
+    async rerun(runId, request) {
+        return await this.#json('POST', `/api/v1/runs/${encodeURIComponent(runId)}/rerun`, request);
+    }
+    async spend(repository, days) {
+        const query = days === undefined ? '' : `?days=${encodeURIComponent(String(days))}`;
+        const path = repository === undefined
+            ? `/api/v1/spend${query}`
+            : `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/spend${query}`;
+        return await this.#json('GET', path);
+    }
+    async actionInventory(repository) {
+        return await this.#json('GET', `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/actions`);
+    }
+    /**
+     * The terms in force and who owes an acceptance, read from `/me`.
+     *
+     * It rides on `/me` in the API because the remedy is at somebody's next
+     * sign-in and that is the call every screen makes (control-plane ADR-0039
+     * amendment 1); here it means one request answers both halves.
+     */
+    async termsStanding() {
+        const body = await this.#json('GET', '/api/v1/me');
+        return { version: body.termsVersion ?? '', pending: body.termsPending ?? [] };
+    }
+    async acceptTerms(installationId, version) {
+        const body = await this.#json('POST', '/api/v1/terms/acceptance', { installationId, termsVersion: version });
+        return body.accepted;
+    }
+    async actionPolicy(owner) {
+        return await this.#json('GET', `/api/v1/orgs/${encodeURIComponent(owner)}/action-policy`);
+    }
+    async setActionPolicy(owner, policy) {
+        return await this.#json('PUT', `/api/v1/orgs/${encodeURIComponent(owner)}/action-policy`, policy);
+    }
+    async pinActions(repository, apply) {
+        return await this.#json('POST', `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/actions/pin`, { apply });
+    }
+    async listNotificationRules(repository) {
+        const body = await this.#json('GET', `${this.#repoPath(repository.owner, repository.repo)}/notifications`);
+        return body.rules;
+    }
+    async putNotificationRule(repository, name, input) {
+        return await this.#json('PUT', `${this.#repoPath(repository.owner, repository.repo)}/notifications/${encodeURIComponent(name)}`, input);
+    }
+    async deleteNotificationRule(repository, name) {
+        const response = await this.#request('DELETE', `${this.#repoPath(repository.owner, repository.repo)}/notifications/${encodeURIComponent(name)}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return true;
+    }
+    async testNotificationRule(repository, name) {
+        return await this.#json('POST', `${this.#repoPath(repository.owner, repository.repo)}/notifications/${encodeURIComponent(name)}/test`);
+    }
+    async listNotificationDeliveries(repository, limit) {
+        const body = await this.#json('GET', `${this.#repoPath(repository.owner, repository.repo)}/notification-deliveries?limit=${String(limit)}`);
+        return body.deliveries;
+    }
+    async searchLogs(repository, request) {
+        const params = new URLSearchParams({ q: request.query });
+        if (request.workflow !== undefined)
+            params.set('workflow', request.workflow);
+        if (request.branch !== undefined)
+            params.set('branch', request.branch);
+        if (request.conclusion !== undefined)
+            params.set('conclusion', request.conclusion);
+        if (request.job !== undefined)
+            params.set('job', request.job);
+        if (request.caseSensitive === true)
+            params.set('case', 'true');
+        if (request.days !== undefined)
+            params.set('days', String(request.days));
+        if (request.limit !== undefined)
+            params.set('limit', String(request.limit));
+        const path = `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/logs/search?${params.toString()}`;
+        return await this.#json('GET', path);
+    }
+    async jobLogView(jobId) {
+        return await this.#json('GET', `/api/v1/jobs/${encodeURIComponent(jobId)}/log-view`);
+    }
+    async jobLogs(jobId) {
+        const response = await this.#request('GET', `/api/v1/jobs/${encodeURIComponent(jobId)}/logs`, undefined, 'text/plain');
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return await response.text();
+    }
+    async dispatch(owner, repo, workflow, ref, inputs) {
+        return await this.#json('POST', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/workflows/${encodeURIComponent(workflow)}/dispatches`, { ref, inputs });
+    }
+    async setCoexistence(owner, repo, enabled) {
+        await this.#json('PUT', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/coexistence`, { enabled });
+    }
+    async setWorkflowOptIn(owner, repo, workflow, optedIn) {
+        await this.#json('PUT', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/workflows/${encodeURIComponent(workflow)}/opt-in`, { optedIn });
+    }
+    async coexistenceDiff(owner, repo, sha) {
+        const q = new URLSearchParams({ sha });
+        return await this.#json('GET', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/coexistence/diff?${q.toString()}`);
+    }
+    async listRunners() {
+        const body = await this.#json('GET', '/api/v1/runners');
+        return body.runners;
+    }
+    async mintRegistrationToken(options) {
+        return await this.#json('POST', '/api/v1/runners/registration-tokens', { uses: options.uses ?? 1 });
+    }
+    async removeRunner(id) {
+        const response = await this.#request('DELETE', `/api/v1/runners/${encodeURIComponent(id)}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return true;
+    }
+    async fleetDemand() {
+        return await this.#json('GET', '/api/v1/fleet/demand');
+    }
+    async fleetHistory(window) {
+        const query = new URLSearchParams({ since: window.since, until: window.until });
+        return await this.#json('GET', `/api/v1/fleet/history?${query.toString()}`);
+    }
+    async listCaches(owner, repo) {
+        return await this.#json('GET', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/caches`);
+    }
+    async deleteCache(owner, repo, id) {
+        const response = await this.#request('DELETE', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/caches/${id}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return true;
+    }
+    async listRunArtifacts(runId) {
+        return await this.#json('GET', `/api/v1/runs/${encodeURIComponent(runId)}/artifacts`);
+    }
+    async listRepoArtifacts(owner, repo) {
+        return await this.#json('GET', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/artifacts`);
+    }
+    /**
+     * The API answers with a 302 to a presigned object URL. `fetch` follows it
+     * by default, and following it is the point: the bytes come from the bucket
+     * rather than through the control plane, and this process never holds a
+     * credential for that bucket.
+     */
+    async downloadArtifact(runId, id) {
+        const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/artifacts/${id}/download`, undefined, '*/*');
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        // Node's `fetch` body is async-iterable; the DOM type it is declared as is
+        // not, which is a gap in the declarations rather than in the runtime.
+        return response.body ?? undefined;
+    }
+    async deleteArtifact(runId, id) {
+        const response = await this.#request('DELETE', `/api/v1/runs/${encodeURIComponent(runId)}/artifacts/${id}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return true;
+    }
+    // ── environments, deployments, schedules, OIDC ──
+    async listEnvironments(owner, repo) {
+        return await this.#json('GET', `${this.#repoPath(owner, repo)}/environments`);
+    }
+    async putEnvironment(owner, repo, name, input) {
+        return await this.#json('PUT', `${this.#repoPath(owner, repo)}/environments/${encodeURIComponent(name)}`, input);
+    }
+    async deleteEnvironment(owner, repo, name) {
+        const response = await this.#request('DELETE', `${this.#repoPath(owner, repo)}/environments/${encodeURIComponent(name)}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return true;
+    }
+    async listWaitingDeployments() {
+        return await this.#json('GET', '/api/v1/deployments');
+    }
+    async listRunDeployments(runId) {
+        return await this.#json('GET', `/api/v1/runs/${encodeURIComponent(runId)}/deployments`);
+    }
+    async decideDeployment(id, decision, comment) {
+        const response = await this.#request('POST', `/api/v1/deployments/${encodeURIComponent(id)}/decision`, {
+            decision,
+            ...(comment !== undefined && comment !== '' ? { comment } : {}),
+        });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return (await this.#decode(response));
+    }
+    async listWaitingRuns() {
+        return await this.#json('GET', '/api/v1/approvals');
+    }
+    async decideRun(runId, decision, comment) {
+        const response = await this.#request('POST', `/api/v1/runs/${encodeURIComponent(runId)}/approval`, {
+            decision,
+            ...(comment !== undefined && comment !== '' ? { comment } : {}),
+        });
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return (await this.#decode(response));
+    }
+    async listSchedules(owner, repo) {
+        return await this.#json('GET', `${this.#repoPath(owner, repo)}/schedules`);
+    }
+    /**
+     * The discovery document, unauthenticated — the same request a cloud
+     * provider makes, which is the point of reading it from here: if this
+     * answers, federation's first step works.
+     */
+    async oidcDiscovery() {
+        const response = await this.#request('GET', '/.well-known/openid-configuration');
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok)
+            throw new Error(await this.#errorMessage(response));
+        return (await this.#decode(response));
+    }
+    async getOidcSubject(owner, repo) {
+        return await this.#json('GET', `${this.#repoPath(owner, repo)}/oidc/subject`);
+    }
+    async putOidcSubject(owner, repo, keys) {
+        return await this.#json('PUT', `${this.#repoPath(owner, repo)}/oidc/subject`, { includeClaimKeys: keys });
+    }
+    #repoPath(owner, repo) {
+        return `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+    }
+    async #json(method, path, body) {
+        const response = await this.#request(method, path, body);
+        if (!response.ok)
+            throw new HttpError(await this.#errorMessage(response), response.status);
+        return (await this.#decode(response));
+    }
+    async #request(method, path, body, accept = 'application/json') {
+        try {
+            return await this.#fetch(`${this.#baseUrl}${path}`, {
+                method,
+                headers: {
+                    accept,
+                    authorization: `Bearer ${this.#token}`,
+                    ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (err) {
+            throw new Error(`${this.#baseUrl} is unreachable: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+    }
+    async #decode(response) {
+        return await response.json();
+    }
+    /** The API's own message, so a refusal explains itself. */
+    async #errorMessage(response) {
+        try {
+            const problem = (await response.json());
+            if (typeof problem.error === 'string')
+                return problem.error;
+        }
+        catch {
+            // a non-JSON body leaves the status
+        }
+        return `request failed with ${response.status}`;
+    }
+}
+/** Adapter: real time, injected so following a run is testable without it. */
+export class RealSleeper {
+    async sleep(ms) {
+        await delay(ms);
+    }
+}
+/** Writes a file relative to the working directory the command was run from. */
+export class WorkingDirectoryWriter {
+    async write(path, contents) {
+        await writeFile(resolve(process.cwd(), path), contents, 'utf8');
+    }
+}

package/dist/src/infrastructure/credentials.js

@@ -0,0 +1,134 @@
+// infrastructure layer — see ../../../../docs/conventions.md §1
+import { closeSync, openSync, readFileSync, statSync, writeSync } from 'node:fs';
+import { chmod, mkdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { DEFAULT_API_URL, TOKENS_PAGE, hasExpired, isPrivateMode, normaliseUrl, parseSavedCredential, } from '../domain/credentials.js';
+export const URL_ENV = 'APEX_API_URL';
+export const WEB_URL_ENV = 'APEX_WEB_URL';
+export const TOKEN_ENV = 'APEX_TOKEN';
+export const ADMIN_TOKEN_ENV = 'APEX_ADMIN_TOKEN';
+const set = (value) => value !== undefined && value !== '';
+/** The control plane: `APEX_API_URL`, or the hosted service. */
+export const apiUrlFrom = (env = process.env) => normaliseUrl(set(env[URL_ENV]) ? env[URL_ENV] : DEFAULT_API_URL);
+/**
+ * No credential at all, or one the CLI will not use. Exit 2 (§7): it is
+ * configuration, not a refusal by the server. The message names what to set
+ * and never a value.
+ */
+export class NotConfiguredError extends Error {
+    constructor(message) {
+        super(message ??
+            `no credential for the control plane: set ${TOKEN_ENV} to a token from the dashboard (${TOKENS_PAGE}), ` +
+                `or run \`apex login\`; operators set ${ADMIN_TOKEN_ENV}. ${URL_ENV} selects the control plane (default ${DEFAULT_API_URL})`);
+        this.name = 'NotConfiguredError';
+    }
+}
+/** `ssh`'s refusal: a credentials file others can read is not used. */
+export class InsecureCredentialsError extends NotConfiguredError {
+    constructor(path, mode) {
+        super(`${path} is readable by others (mode ${(mode & 0o777).toString(8).padStart(3, '0')}), so it is not used: ` +
+            `run \`chmod 600 ${path}\`, or \`apex logout\` and \`apex login\` again`);
+        this.name = 'InsecureCredentialsError';
+    }
+}
+/** `$XDG_CONFIG_HOME/apex/credentials`, defaulting to `~/.config`. */
+export const credentialsPath = (env = process.env) => join(set(env['XDG_CONFIG_HOME']) ? env['XDG_CONFIG_HOME'] : join(homedir(), '.config'), 'apex', 'credentials');
+/**
+ * Adapter: the credentials file `apex login` writes.
+ *
+ * The file is `0600` in a `0700` directory, and it is written to a temporary
+ * name and renamed, so a crash half-way leaves the old file or none — never a
+ * truncated one, and never a moment where the token sits in a file with the
+ * process's default mode.
+ */
+export class FileCredentialStore {
+    location;
+    constructor(path = credentialsPath()) {
+        this.location = path;
+    }
+    /** The saved credential, or undefined when there is none. Throws when the file is not private. */
+    read() {
+        let mode;
+        try {
+            mode = statSync(this.location).mode;
+        }
+        catch {
+            return undefined;
+        }
+        if (!isPrivateMode(mode))
+            throw new InsecureCredentialsError(this.location, mode);
+        try {
+            return parseSavedCredential(JSON.parse(readFileSync(this.location, 'utf8')));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(credential) {
+        const dir = dirname(this.location);
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        await chmod(dir, 0o700);
+        const temp = `${this.location}.${randomBytes(6).toString('hex')}.tmp`;
+        // `wx` and the mode at creation: the token is never in a file anybody else could open.
+        const fd = openSync(temp, 'wx', 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify(credential, null, 2)}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            await rename(temp, this.location);
+        }
+        catch (err) {
+            await rm(temp, { force: true });
+            throw err;
+        }
+    }
+    async remove() {
+        try {
+            statSync(this.location);
+        }
+        catch {
+            return false;
+        }
+        await rm(this.location, { force: true });
+        return true;
+    }
+}
+/**
+ * Which credential the CLI uses, in ADR-0064's order:
+ *
+ * 1. `APEX_TOKEN` — a dashboard token, for CI and scripts;
+ * 2. the token `apex login` saved — refused outright if the file is readable
+ *    by others, skipped if it has expired or was minted by a different
+ *    control plane than the one `APEX_API_URL` names (a token is only ever
+ *    sent to the server that issued it);
+ * 3. `APEX_ADMIN_TOKEN` — the operator's, unchanged;
+ * 4. nothing: `NotConfiguredError`, naming `APEX_TOKEN` and `apex login`.
+ */
+export const resolveCredential = (env = process.env, store = new FileCredentialStore(credentialsPath(env)), now = new Date()) => {
+    const explicitUrl = set(env[URL_ENV]) ? normaliseUrl(env[URL_ENV]) : undefined;
+    const token = env[TOKEN_ENV];
+    if (set(token))
+        return { token, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'env' };
+    const saved = store.read();
+    if (saved !== undefined && !hasExpired(saved, now)) {
+        const mintedBy = normaliseUrl(saved.apiUrl);
+        if (explicitUrl === undefined || explicitUrl === mintedBy)
+            return { token: saved.token, apiUrl: mintedBy, source: 'login' };
+    }
+    const admin = env[ADMIN_TOKEN_ENV];
+    if (set(admin))
+        return { token: admin, apiUrl: explicitUrl ?? DEFAULT_API_URL, source: 'operator' };
+    if (saved !== undefined && hasExpired(saved, now)) {
+        throw new NotConfiguredError(`the token \`apex login\` saved expired at ${saved.expiresAt}: run \`apex login\` again, or set ${TOKEN_ENV}`);
+    }
+    if (saved !== undefined) {
+        throw new NotConfiguredError(`the token \`apex login\` saved was issued by ${normaliseUrl(saved.apiUrl)}, and ${URL_ENV} names ${explicitUrl ?? ''}: ` +
+            `it is not sent anywhere else — run \`apex login\` against this control plane, or set ${TOKEN_ENV}`);
+    }
+    throw new NotConfiguredError();
+};