@apex-actions/cli 0.74.0 → 0.76.0

package/dist/cli/whoami/main.js

@@ -1,7 +1,8 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { whoami } from '../../src/application/authenticate.js';
-import { describeSource } from '../../src/domain/credentials.js';
+import { listTokens } from '../../src/application/manage-tokens.js';
+import { describeGrants, describeSource } from '../../src/domain/credentials.js';
 import { credentialsPath } from '../../src/infrastructure/credentials.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
 const credentialLine = (credential) => {
@@ -22,9 +23,21 @@ const credentialLine = (credential) => {
  * `apex whoami`: who the control plane thinks this CLI is, and which
  * credential got it there. The answer is the server's (`GET /api/v1/me`), not
  * a guess from the local file; the credential itself is never printed.
+ *
+ * It also names any credential that was present and lost (ADR-0005: the
+ * environment outranks the saved login), because the surprise this command
+ * exists to prevent is acting as somebody other than the one you meant.
+ *
+ * When the credential is a token it also says what the token may do and which
+ * Account it belongs to — the list of the person's tokens marks it `current`.
  */
 export default new Command('whoami')
     .description('Who the CLI is acting as, with which credential, and where it found it')
+    .addHelpText('after', '\nWhich credential is used, first match wins:\n' +
+    '  1. APEX_TOKEN in the environment\n' +
+    '  2. APEX_ADMIN_TOKEN in the environment (operators)\n' +
+    '  3. the token `apex login` saved\n' +
+    'A variable you exported outranks a saved login. Unset it to use the login.')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     let client;
@@ -42,7 +55,14 @@ export default new Command('whoami')
         process.exitCode = 1;
         return;
     }
-    const { identity, source } = outcome;
+    const { identity, source, alsoPresent } = outcome;
+    // The token's grants and Account: best effort, since the identity above is the answer this command owes.
+    let token;
+    if (identity.credential?.kind === 'token') {
+        const listed = await listTokens(client, false);
+        if (listed.kind === 'listed')
+            token = listed.tokens.find((t) => t.current === true);
+    }
     const login = identity.actor.kind === 'user' ? identity.actor.login : undefined;
     const foundIn = source === 'login' ? `${describeSource(source)} (${credentialsPath()})` : describeSource(source);
     if (opts.json === true) {
@@ -57,13 +77,35 @@ export default new Command('whoami')
                     ...(identity.credential.source === undefined ? {} : { source: identity.credential.source }),
                     ...(identity.credential.expiresAt === undefined ? {} : { expiresAt: identity.credential.expiresAt }),
                 },
+            ...(token === undefined
+                ? {}
+                : {
+                    token: {
+                        id: token.id,
+                        name: token.name,
+                        permissions: token.permissions ?? [],
+                        repos: token.repos ?? null,
+                        accountId: token.accountId ?? null,
+                    },
+                }),
             foundIn: source,
+            notUsed: alsoPresent,
             apiUrl: client.baseUrl,
         }, null, 2));
         return;
     }
     console.log(`${'acting as'.padEnd(14)}${login ?? 'the machine principal'}`);
     console.log(`${'credential'.padEnd(14)}${credentialLine(identity.credential)}`);
+    if (token !== undefined) {
+        console.log(`${'token'.padEnd(14)}${token.name} (${token.id})`);
+        console.log(`${'permissions'.padEnd(14)}${describeGrants(token.permissions)}`);
+        console.log(`${'repositories'.padEnd(14)}${token.repos === undefined || token.repos.length === 0 ? 'every repository you reach in its Account' : token.repos.join(', ')}`);
+        console.log(`${'account'.padEnd(14)}${token.accountId ?? 'none — this token reaches nothing; create a new one'}`);
+    }
     console.log(`${'found in'.padEnd(14)}${foundIn}`);
+    for (const other of alsoPresent) {
+        const where = other === 'login' ? `${describeSource(other)} (${credentialsPath()})` : describeSource(other);
+        console.log(`${'not used'.padEnd(14)}${where} — outranked by the credential above`);
+    }
     console.log(`${'control plane'.padEnd(14)}${client.baseUrl}`);
 });

package/dist/src/application/authenticate.js

@@ -1,35 +1,132 @@
-import { authorizeUrl } from '../domain/credentials.js';
+import { authorizeUrl, doneUrl } from '../domain/credentials.js';
 /**
  * The loopback flow itself: open the consent page, wait for the one callback,
  * redeem its code with the verifier. Shared by `apex login`, which saves what
  * it gets, and `apex token create`, which hands it back to be printed once.
  */
-export const approveInBrowser = async (deps, token) => {
+export const approveInBrowser = async (deps, token, accountId) => {
     const pair = deps.pkce();
     const listener = await deps.listen(pair.state);
     try {
-        const url = authorizeUrl(deps.webBase, { port: listener.port, state: pair.state, codeChallenge: pair.challenge, name: deps.name, token });
+        const url = authorizeUrl(deps.webBase, { port: listener.port, state: pair.state, codeChallenge: pair.challenge, name: deps.name, token, accountId });
         deps.announce(url);
         deps.openBrowser?.(url);
         const callback = await listener.wait();
+        const purpose = token === undefined ? 'login' : (token.purpose ?? 'token');
+        if (callback.kind === 'denied')
+            await listener.conclude(doneUrl(deps.webBase, 'denied', purpose));
         if (callback.kind !== 'code')
             return callback;
+        // Redeem first, then hand the tab to the done page: its words must match what actually happened.
+        let outcome;
         try {
-            return { kind: 'minted', minted: await deps.exchange.redeem(callback.code, pair.verifier) };
+            outcome = { kind: 'minted', minted: await deps.exchange.redeem(callback.code, pair.verifier) };
         }
         catch (err) {
-            return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+            outcome = { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
         }
+        await listener.conclude(doneUrl(deps.webBase, outcome.kind === 'minted' ? 'approved' : 'failed', purpose));
+        return outcome;
     }
     finally {
         await listener.close();
     }
 };
+/** RFC 8628 §3.2's default when a server names no interval. */
+const DEFAULT_INTERVAL_SECONDS = 5;
+/**
+ * The device flow (control-plane ADR-0075, RFC 8628 run by Apex): ask for a request, show the code, and
+ * poll with the device code — which never leaves this process — every `interval` seconds, slowing down
+ * when told, until the person approves or denies on any device, or the code's ten minutes pass.
+ */
+export const approveOnDevice = async (deps, token, accountId) => {
+    const { device } = deps;
+    const purpose = token === undefined ? 'login' : (token.purpose ?? 'token');
+    let start;
+    try {
+        start = await device.exchange.start({
+            name: deps.name,
+            purpose,
+            ...(token?.days === undefined ? {} : { days: token.days }),
+            ...(token?.allRepos === true ? { allRepositories: true } : token?.repos !== undefined && token.repos.length > 0 ? { repos: token.repos } : {}),
+            ...(token?.permissions === undefined ? {} : { permissions: token.permissions }),
+            ...((token?.accountId ?? accountId) === undefined ? {} : { accountId: token?.accountId ?? accountId }),
+            ...(token?.tokenId === undefined ? {} : { tokenId: token.tokenId }),
+            ...(device.os === undefined ? {} : { os: device.os }),
+            ...(device.hostname === undefined ? {} : { hostname: device.hostname }),
+        });
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+    device.announceCode(start, device.why);
+    let interval = Number.isFinite(start.interval) && start.interval >= 0 ? start.interval : DEFAULT_INTERVAL_SECONDS;
+    const deadline = device.now() + start.expiresIn * 1000;
+    for (;;) {
+        await device.sleep(interval * 1000);
+        let answer;
+        try {
+            answer = await device.exchange.poll(start.deviceCode);
+        }
+        catch (err) {
+            return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+        }
+        switch (answer.kind) {
+            case 'minted':
+                return { kind: 'minted', minted: answer.minted };
+            case 'slow_down':
+                // RFC 8628 §3.5: add five seconds — or keep to what the server now says.
+                interval = answer.interval ?? interval + 5;
+                break;
+            case 'authorization_pending':
+                if (answer.interval !== undefined)
+                    interval = answer.interval;
+                break;
+            case 'access_denied':
+                return { kind: 'denied', detail: 'denied on the approval page' };
+            case 'expired_token':
+                return { kind: 'expired' };
+            case 'invalid_grant':
+                return { kind: 'refused', detail: 'the control plane does not know this device request — run the command again' };
+        }
+        if (device.now() >= deadline)
+            return { kind: 'expired' };
+    }
+};
+/** The approval, by whichever flow was chosen: the loopback unless `flow` is `device`. */
+export const approve = async (deps, token, accountId) => deps.flow === 'device' && deps.device !== undefined ? await approveOnDevice({ ...deps, device: deps.device }, token, accountId) : await approveInBrowser(deps, token, accountId);
 export const login = async (deps) => {
-    const approval = await approveInBrowser(deps);
+    const approval = await approve(deps, undefined, deps.accountId);
+    if (approval.kind !== 'minted')
+        return approval;
+    const { minted } = approval;
+    if (minted.token === undefined)
+        return { kind: 'refused', detail: 'the control plane answered the login without a token' };
+    await deps.store.save({ token: minted.token, login: minted.login, apiUrl: deps.apiUrl, expiresAt: minted.expiresAt });
+    return {
+        kind: 'logged-in',
+        login: minted.login,
+        expiresAt: minted.expiresAt,
+        location: deps.store.location,
+        permissions: minted.permissions,
+        accountId: minted.accountId,
+    };
+};
+/**
+ * `apex login --console` (control-plane ADR-0079): the same loopback + PKCE approval, opened on the Admin
+ * Console's bare page rather than the app's — `deps.webBase` is the Console's — and redeemed at the same
+ * control plane, for an **operator token**. Only the loopback: an operator approves in the Console's own
+ * browser session. What comes back must be an operator token, or nothing is saved.
+ */
+export const consoleLogin = async (deps) => {
+    const approval = await approveInBrowser({ ...deps, flow: 'loopback' });
     if (approval.kind !== 'minted')
         return approval;
     const { minted } = approval;
+    if (minted.token === undefined)
+        return { kind: 'refused', detail: 'the control plane answered the login without a token' };
+    if (!minted.token.startsWith(deps.operatorPrefix))
+        return { kind: 'refused', detail: 'the control plane answered with an Account token, not an operator token — nothing was saved' };
     await deps.store.save({ token: minted.token, login: minted.login, apiUrl: deps.apiUrl, expiresAt: minted.expiresAt });
     return { kind: 'logged-in', login: minted.login, expiresAt: minted.expiresAt, location: deps.store.location };
 };
@@ -58,7 +155,7 @@ export const logout = async (store, revoke) => {
 };
 export const whoami = async (api) => {
     try {
-        return { kind: 'identified', identity: await api.whoami(), source: api.credentialSource };
+        return { kind: 'identified', identity: await api.whoami(), source: api.credentialSource, alsoPresent: api.credentialsAlsoPresent ?? [] };
     }
     catch (err) {
         return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };

package/dist/src/application/manage-grants.js

@@ -0,0 +1,21 @@
+import { withOperatorHint } from '../domain/grants.js';
+const attempt = async (fn) => {
+    try {
+        return { kind: 'ok', value: await fn() };
+    }
+    catch (err) {
+        return { kind: 'refused', message: withOperatorHint(err instanceof Error ? err.message : String(err)) };
+    }
+};
+/** Every grant ever made, newest first. The control plane decides who may read them. */
+export const listGrants = async (api) => await attempt(() => api.listGrants());
+/**
+ * Grant an installation complimentary access, replacing any open grant it holds. Only a person may: the
+ * control plane records the operator the token belongs to, and refuses the machine token.
+ */
+export const createGrant = async (api, body) => await attempt(() => api.createGrant(body));
+export const updateGrant = async (api, id, body) => await attempt(() => api.updateGrant(id, body));
+/** End a grant now; its queued free work is cancelled with a reason on each check run. */
+export const revokeGrant = async (api, id) => await attempt(() => api.revokeGrant(id));
+/** Every installation GitHub lists for the App — `fresh` keeps only those the tenants list never shows. */
+export const listInstallations = async (api, fresh) => await attempt(async () => (await api.listInstallations()).filter((i) => !fresh || !i.listedAsTenant));

package/dist/src/application/manage-tokens.js

@@ -1,6 +1,6 @@
 // application layer — see ../../../../docs/conventions.md §1
-import { tokenRequestProblem } from '../domain/credentials.js';
-import { approveInBrowser } from './authenticate.js';
+import { editedPermissions, tokenEditProblem, tokenRequestProblem } from '../domain/credentials.js';
+import { approve } from './authenticate.js';
 const detail = (err) => (err instanceof Error ? err.message : String(err));
 /**
  * Mint a token through the browser. The flags are checked before a browser
@@ -8,13 +8,21 @@ const detail = (err) => (err instanceof Error ? err.message : String(err));
  */
 export const createToken = async (deps, input) => {
     const name = input.name.trim();
-    const problem = tokenRequestProblem(name, input.days, input.repos);
+    const problem = tokenRequestProblem(name, input.days, input.repos, input.permissions);
     if (problem !== undefined)
         return { kind: 'invalid', detail: problem };
-    const approval = await approveInBrowser({ ...deps, name }, { ...(input.days === undefined ? {} : { days: input.days }), ...(input.repos.length === 0 ? {} : { repos: input.repos }) });
+    const approval = await approve({ ...deps, name }, {
+        purpose: 'token',
+        permissions: [...new Set(input.permissions)],
+        ...(input.days === undefined ? {} : { days: input.days }),
+        ...(input.repos.length === 0 ? {} : { repos: input.repos }),
+        ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+    });
     if (approval.kind !== 'minted')
         return approval;
     const { minted } = approval;
+    if (minted.token === undefined)
+        return { kind: 'refused', detail: 'the control plane answered without a token' };
     return {
         kind: 'created',
         token: minted.token,
@@ -23,6 +31,78 @@ export const createToken = async (deps, input) => {
         id: minted.id,
         name: minted.name ?? name,
         repos: minted.repos,
+        permissions: minted.permissions,
+        accountId: minted.accountId,
+    };
+};
+const sameSet = (a, b) => (a ?? []).length === (b ?? []).length && (a ?? []).every((x) => (b ?? []).includes(x));
+/**
+ * Edit a token's grants or repositories. The token is read first — `--add-permission` needs its current grants, and a
+ * browser approval must carry the repositories unchanged when only the grants change, because an approval that names
+ * none means every repository. Then the edit is asked for directly: a narrowing applies at once. The control plane
+ * refuses a widening to anything but a signed-in person (403), so that one goes through the approval page, whose
+ * redeemed code applies the edit and mints nothing.
+ */
+export const editToken = async (api, approval, id, edit) => {
+    const problem = tokenEditProblem(edit);
+    if (problem !== undefined)
+        return { kind: 'invalid', detail: problem };
+    let target;
+    try {
+        target = (await api.listTokens()).find((t) => t.id === id && t.state === 'active');
+    }
+    catch (err) {
+        return { kind: 'refused', detail: detail(err) };
+    }
+    if (target === undefined)
+        return { kind: 'not-found', id };
+    const permissions = editedPermissions(target.permissions ?? [], edit);
+    if (permissions.length === 0)
+        return { kind: 'invalid', detail: 'that would leave the token no permission — revoke it instead' };
+    const repos = edit.repos === 'all' ? undefined : (edit.repos ?? target.repos);
+    const permissionsChange = !sameSet(permissions, target.permissions);
+    const reposChange = edit.repos !== undefined && !(edit.repos === 'all' ? (target.repos ?? []).length === 0 : sameSet(edit.repos, target.repos));
+    if (!permissionsChange && !reposChange)
+        return { kind: 'unchanged', token: target };
+    let answer;
+    try {
+        answer = await api.editToken(id, {
+            ...(permissionsChange ? { permissions } : {}),
+            ...(reposChange ? { repos: repos === undefined || repos.length === 0 ? null : repos } : {}),
+        });
+    }
+    catch (err) {
+        return { kind: 'refused', detail: detail(err) };
+    }
+    if (answer.kind === 'edited')
+        return { kind: 'edited', token: answer.token, via: 'direct' };
+    if (answer.kind === 'not-found')
+        return { kind: 'not-found', id };
+    if (answer.status !== 403)
+        return { kind: 'refused', detail: answer.detail };
+    // A widening: a person approves it in the browser, within the Account's policy.
+    const approved = await approve({ ...approval, name: target.name }, {
+        purpose: 'edit',
+        tokenId: id,
+        permissions,
+        // No repositories keeps the token's own; every repository has to be asked for outright.
+        ...(edit.repos === 'all' ? { allRepos: true } : repos === undefined || repos.length === 0 ? {} : { repos }),
+    });
+    if (approved.kind !== 'minted')
+        return approved;
+    const m = approved.minted;
+    return {
+        kind: 'edited',
+        via: 'browser',
+        token: {
+            ...target,
+            ...(m.name === undefined ? {} : { name: m.name }),
+            expiresAt: m.expiresAt,
+            permissions: m.permissions ?? permissions,
+            // The control plane's view is the answer: no repositories there means every repository.
+            repos: m.repos,
+            ...(m.accountId === undefined ? {} : { accountId: m.accountId }),
+        },
     };
 };
 /** The person's tokens, newest first; only the active ones unless `all`. */

package/dist/src/domain/credentials.js

@@ -19,7 +19,30 @@ export const describeSource = (source) => {
         case 'login':
             return 'the token `apex login` saved';
         case 'operator':
-            return 'APEX_ADMIN_TOKEN, the operator token';
+            return 'APEX_ADMIN_TOKEN, the machine token';
+        case 'console':
+            return 'the operator token `apex login --console` saved';
+    }
+};
+/** An operator token's prefix (control-plane ADR-0079); an Account token's is `apex_pat_`. */
+export const OPERATOR_TOKEN_PREFIX = 'apex_opt_';
+/**
+ * The Admin Console's base URL, where `apex login --console` is approved (control-plane ADR-0079):
+ * `APEX_CONSOLE_URL` when set, else the API's host with `app.` read as `admin.` — the hosted service's
+ * pair — else `undefined`, and the command asks for `APEX_CONSOLE_URL`.
+ */
+export const consoleBaseFor = (apiUrl, consoleUrl) => {
+    if (consoleUrl !== undefined && consoleUrl !== '')
+        return normaliseUrl(consoleUrl);
+    try {
+        const url = new URL(apiUrl);
+        if (!url.hostname.startsWith('app.'))
+            return undefined;
+        url.hostname = `admin.${url.hostname.slice('app.'.length)}`;
+        return normaliseUrl(url.origin);
+    }
+    catch {
+        return undefined;
     }
 };
 /** A URL without its trailing slash, so two spellings of one origin compare equal. */
@@ -51,9 +74,18 @@ export const parseSavedCredential = (raw) => {
     return { token: r['token'], login: r['login'], apiUrl: r['apiUrl'], expiresAt: r['expiresAt'] };
 };
 /**
- * The consent page `apex login` and `apex token create` open (RFC 8252
- * loopback, RFC 7636 S256). A token request adds `purpose=token` and what the
- * person is approving, so the page can show it and the code carries it.
+ * The consent page `apex login`, `apex token create` and a widening `apex token
+ * edit` open (RFC 8252 loopback, RFC 7636 S256). The query is the contract with
+ * the web app's `/cli/authorize` page:
+ *
+ * - `port`, `state`, `code_challenge`, `name` — always;
+ * - `purpose` — `token` or `edit` (absent for a login);
+ * - `days`, `repos` (comma-separated `owner/repo`) — a token's lifetime and scope; for an edit, `repos` absent
+ *   keeps the token's own repositories;
+ * - `all_repos=1` — an edit that widens to every repository (never sent with `repos`);
+ * - `permission` — repeated, once per grant (`actions:read`, `secrets:write`, …);
+ * - `account` — the Account id, for a login or a token;
+ * - `token` — the token id an edit widens.
  */
 export const authorizeUrl = (webBase, request) => {
     const query = new URLSearchParams({
@@ -62,27 +94,55 @@ export const authorizeUrl = (webBase, request) => {
         code_challenge: request.codeChallenge,
         name: request.name,
     });
-    if (request.token !== undefined) {
-        query.set('purpose', 'token');
-        if (request.token.days !== undefined)
-            query.set('days', String(request.token.days));
-        if (request.token.repos !== undefined && request.token.repos.length > 0)
-            query.set('repos', request.token.repos.join(','));
+    const t = request.token;
+    if (t !== undefined) {
+        query.set('purpose', t.purpose ?? 'token');
+        if (t.days !== undefined)
+            query.set('days', String(t.days));
+        if (t.allRepos === true)
+            query.set('all_repos', '1');
+        else if (t.repos !== undefined && t.repos.length > 0)
+            query.set('repos', t.repos.join(','));
+        for (const p of t.permissions ?? [])
+            query.append('permission', p);
+        if (t.accountId !== undefined)
+            query.set('account', t.accountId);
+        if (t.tokenId !== undefined)
+            query.set('token', t.tokenId);
+    }
+    else if (request.accountId !== undefined) {
+        query.set('account', request.accountId);
     }
     return `${normaliseUrl(webBase)}/cli/authorize?${query.toString()}`;
 };
+/**
+ * Where the loopback callback sends the browser once the code is redeemed (control-plane ADR-0075): the
+ * web app's bare `/cli/done`, so the tab ends on our domain rather than on this process's `127.0.0.1`.
+ * The page is copy only and confirms nothing server-side, so it carries only the outcome and the purpose
+ * — never the code, the state or anything else the callback held.
+ */
+export const doneUrl = (webBase, outcome, purpose) => `${normaliseUrl(webBase)}/cli/done?${new URLSearchParams({ outcome, purpose }).toString()}`;
 /** A token's lifetime bounds (control-plane ADR-0064): every token expires, 90 days at most. */
 export const MAX_TOKEN_DAYS = 90;
 /** Repositories one token may be held to. */
 export const MAX_TOKEN_REPOS = 100;
 const REPO = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
-/** `apex token create`'s flags, checked before a browser opens — the control plane checks them again. */
-export const tokenRequestProblem = (name, days, repos) => {
-    if (name.trim() === '' || name.trim().length > 100)
-        return 'a token needs a name of 1 to 100 characters';
-    if (days !== undefined && !(Number.isInteger(days) && days >= 1 && days <= MAX_TOKEN_DAYS)) {
-        return `--expires-in-days must be a whole number from 1 to ${MAX_TOKEN_DAYS}`;
-    }
+/**
+ * What a token may be granted (context ADR-0038): `resource:read|write`, write implying read. The control plane's
+ * `RepoPermission`, in the order a person reads them.
+ */
+export const TOKEN_RESOURCES = ['actions', 'approvals', 'deployments', 'secrets', 'variables', 'environments', 'notifications', 'administration'];
+export const TOKEN_PERMISSIONS = TOKEN_RESOURCES.flatMap((r) => [`${r}:read`, `${r}:write`]);
+/** `--permission`'s values: at least one when `required`, each one a known grant. */
+export const permissionsProblem = (permissions, required) => {
+    if (required && permissions.length === 0)
+        return 'a token needs at least one --permission, e.g. --permission actions:read';
+    const bad = permissions.filter((p) => !TOKEN_PERMISSIONS.includes(p));
+    if (bad.length > 0)
+        return `not a permission: ${bad.join(', ')} — each is resource:read or resource:write, resource one of ${TOKEN_RESOURCES.join(', ')}`;
+    return undefined;
+};
+const reposProblem = (repos) => {
     if (repos.length > MAX_TOKEN_REPOS)
         return `a token may name at most ${MAX_TOKEN_REPOS} repositories`;
     const bad = repos.filter((r) => !REPO.test(r));
@@ -90,6 +150,68 @@ export const tokenRequestProblem = (name, days, repos) => {
         return `not owner/repo: ${bad.join(', ')}`;
     return undefined;
 };
+/**
+ * `apex token create`'s flags, checked before a browser opens — the control plane checks them again. `permissions`,
+ * when given, must name at least one grant.
+ */
+export const tokenRequestProblem = (name, days, repos, permissions) => {
+    if (name.trim() === '' || name.trim().length > 100)
+        return 'a token needs a name of 1 to 100 characters';
+    if (days !== undefined && !(Number.isInteger(days) && days >= 1 && days <= MAX_TOKEN_DAYS)) {
+        return `--expires-in-days must be a whole number from 1 to ${MAX_TOKEN_DAYS}`;
+    }
+    return reposProblem(repos) ?? (permissions === undefined ? undefined : permissionsProblem(permissions, true));
+};
+/** `apex token edit`'s flags: something to change, and each change well-formed. */
+export const tokenEditProblem = (edit) => {
+    if (edit.permissions === undefined && edit.add.length === 0 && edit.remove.length === 0 && edit.repos === undefined) {
+        return 'nothing to change: pass --permission, --add-permission, --remove-permission, --repo or --all-repos';
+    }
+    if (edit.permissions !== undefined && (edit.add.length > 0 || edit.remove.length > 0))
+        return 'pass --permission for the whole set, or --add-permission/--remove-permission, not both';
+    return ((edit.permissions === undefined ? undefined : permissionsProblem(edit.permissions, true)) ??
+        permissionsProblem([...edit.add, ...edit.remove], false) ??
+        (edit.repos === undefined || edit.repos === 'all' ? undefined : reposProblem(edit.repos)));
+};
+/** Whether `current` already grants `asked` — itself, or its write when a read is asked (write implies read). */
+export const covers = (current, asked) => {
+    if (current.includes(asked))
+        return true;
+    const [resource, level] = asked.split(':');
+    return level === 'read' && current.includes(`${resource ?? ''}:write`);
+};
+/**
+ * The grants an edit asks for: the whole new set, or the current set with additions (skipping any already covered)
+ * and removals. Removing a write keeps nothing of it — ask for the read to keep reading.
+ */
+export const editedPermissions = (current, edit) => {
+    if (edit.permissions !== undefined)
+        return [...new Set(edit.permissions)];
+    const out = current.filter((p) => !edit.remove.includes(p));
+    for (const p of edit.add)
+        if (!covers(out, p))
+            out.push(p);
+    return out;
+};
+/** A grant set as one short phrase: `every permission` for all of them, otherwise the grants as given. */
+export const describeGrants = (permissions) => {
+    if (permissions === undefined || permissions.length === 0)
+        return 'none';
+    if (TOKEN_RESOURCES.every((r) => permissions.includes(`${r}:write`)))
+        return 'every permission';
+    return [...permissions].sort((a, b) => TOKEN_PERMISSIONS.indexOf(a) - TOKEN_PERMISSIONS.indexOf(b)).join(', ');
+};
+const NEEDS = /^this token needs ([a-z]+:(?:read|write))$/;
+/**
+ * The control plane refuses a token a route its grants do not cover with `this token needs <permission>`. Say how to
+ * get it — an edit that adds the grant, which a browser approves — naming the token when the CLI knows which it is.
+ */
+export const withPermissionHint = (message, tokenId) => {
+    const m = NEEDS.exec(message);
+    if (m === null)
+        return message;
+    return `${message} — add it with: apex token edit ${tokenId ?? '<id>'} --add-permission ${m[1] ?? ''}${tokenId === undefined ? ' (apex token list shows the id)' : ''}`;
+};
 /**
  * Judge what arrived at the loopback callback.
  *
@@ -110,3 +232,49 @@ export const judgeCallback = (params, expectedState) => {
         return { kind: 'malformed' };
     return { kind: 'code', code };
 };
+const set = (v) => v !== undefined && v !== '';
+/**
+ * Why no browser can open on this machine, in words for the terminal — or `undefined` when one can.
+ * ADR-0075's list: an SSH session, a Codespace, a dev container, a container, or Linux with no display.
+ */
+export const headlessReason = ({ env, platform, dockerenv }) => {
+    if (set(env['SSH_CONNECTION']) || set(env['SSH_TTY']))
+        return 'this is an SSH session';
+    if (set(env['CODESPACES']))
+        return 'this is a Codespace';
+    if (set(env['REMOTE_CONTAINERS']))
+        return 'this is a dev container';
+    if (dockerenv)
+        return 'this is a container';
+    if (platform === 'linux' && !set(env['DISPLAY']) && !set(env['WAYLAND_DISPLAY']))
+        return 'this Linux machine has no display';
+    return undefined;
+};
+/**
+ * Which flow to use. `--device` and `--no-browser` ask for the device flow (`--no-browser` once printed a
+ * loopback URL, which only ever worked on this same machine); `--browser` insists on the loopback;
+ * otherwise a headless environment chooses the device flow and says why.
+ */
+export const chooseFlow = (flags, headless) => {
+    if (flags.device === true && flags.browser === true)
+        return { problem: 'pass --device or --browser, not both' };
+    if (flags.device === true || flags.browser === false)
+        return { flow: 'device' };
+    if (flags.browser === true)
+        return { flow: 'loopback' };
+    return headless === undefined ? { flow: 'loopback' } : { flow: 'device', why: headless };
+};
+/** The lines the terminal shows for a device approval — the code, where to enter it, and for how long. */
+export const deviceInstructions = (start, why) => {
+    const minutes = Math.max(1, Math.round(start.expiresIn / 60));
+    return [
+        ...(why === undefined ? [] : [`No browser can open here (${why}), so approve with a code instead.`]),
+        `Open ${start.verificationUri} on any device and enter ${start.userCode}`,
+        `The code expires in ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}. Enter it only on that page — Apex never asks for it anywhere else.`,
+    ];
+};
+/** RFC 8628 §3.5's answers to a poll that minted nothing, plus `invalid_grant` for a code never issued. */
+export const DEVICE_POLL_ERRORS = ['authorization_pending', 'slow_down', 'access_denied', 'expired_token', 'invalid_grant'];
+export const isDevicePollError = (v) => typeof v === 'string' && DEVICE_POLL_ERRORS.includes(v);
+/** What a loopback timeout says: most likely the browser is on another machine, and there is a flow for that. */
+export const loopbackTimeoutHint = (command) => `No approval arrived. If your browser is on another machine, run \`${command} --device\`.`;