@apex-actions/cli 0.75.0 → 0.76.1

package/dist/cli/token/main.js

@@ -1,10 +1,11 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { createToken, editToken, listTokens, revokeTokens } from '../../src/application/manage-tokens.js';
-import { MAX_TOKEN_DAYS, TOKENS_PAGE, TOKEN_RESOURCES, describeGrants, webBaseFor } from '../../src/domain/credentials.js';
+import { MAX_TOKEN_DAYS, TOKENS_PAGE, TOKEN_RESOURCES, describeGrants, loopbackTimeoutHint, webBaseFor } from '../../src/domain/credentials.js';
 import { TOKEN_ENV, WEB_URL_ENV, apiUrlFrom } from '../../src/infrastructure/credentials.js';
 import { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from '../../src/infrastructure/loopback-login.js';
 import { api, collect, usage } from '../secret/shared.js';
+import { approvalFlow, withFlowOptions } from '../login/device.js';
 /**
  * `apex token`: the person's API tokens from the terminal (control-plane
  * ADR-0064, amended 2026-09-27).
@@ -22,38 +23,49 @@ import { api, collect, usage } from '../secret/shared.js';
  * Exit codes follow §7: 0 done · 1 refused or declined · 2 usage · 3 no such token.
  */
 const PERMISSION_HELP = `resource:read or resource:write (write implies read); resource is one of ${TOKEN_RESOURCES.join(', ')}`;
-/** The browser half `create` and a widening `edit` share. */
-const approvalDeps = (browser, what) => {
+/**
+ * The approval half `create` and a widening `edit` share — the loopback on this machine, or a device code
+ * (control-plane ADR-0075). Everything a person reads goes to stderr: stdout is the token's alone.
+ */
+const approvalDeps = (flags, what) => {
     const apiUrl = apiUrlFrom();
+    const chosen = approvalFlow(flags, apiUrl, (line) => console.error(line));
+    if ('problem' in chosen)
+        return chosen;
     return {
         pkce: newPkcePair,
         listen: (state) => listenForCallback(state),
-        openBrowser: browser ? (url) => openInBrowser(url) : undefined,
+        openBrowser: (url) => openInBrowser(url),
         announce: (url) => {
-            console.error(browser ? `Opening the browser to approve ${what}. If it does not open, visit:` : `Open this URL to approve ${what}:`);
+            console.error(`Opening the browser to approve ${what}. If it does not open, visit:`);
             console.error(`  ${url}`);
             console.error(chalk.dim('Waiting for the approval (5 minutes)…'));
         },
         exchange: new HttpLoginExchange(apiUrl),
         webBase: webBaseFor(apiUrl, process.env[WEB_URL_ENV]),
+        flow: chosen.flow,
+        device: chosen.device,
     };
 };
 const refused = (message) => {
     console.error(chalk.red(message));
     process.exitCode = 1;
 };
-const createCommand = new Command('create')
-    .description('Create an API token for a script or CI system, approved in the browser; the token is printed once and not saved')
+const createCommand = withFlowOptions(new Command('create')
+    .description('Create an API token for a script or CI system, approved in the browser — here, or on any device with a code; the token is printed once and not saved')
     .argument('<name>', 'what the token is for, as the token list will show it (1–100 characters)')
     .option('--permission <permission>', `what the token may do, repeatable and at least one: ${PERMISSION_HELP}`, collect, [])
     .option('--account <id>', 'the Account the token belongs to — needed when you belong to more than one')
     .option('--expires-in-days <days>', `days until the token expires, 1–${MAX_TOKEN_DAYS} (default 30)`)
     .option('--repo <owner/repo>', 'hold the token to this repository (repeatable, up to 100); omit for every repository you reach in the Account', collect, [])
-    .option('--no-browser', 'print the approval URL instead of opening a browser')
-    .option('--json', 'print the token and its details as JSON on stdout')
-    .action(async (name, opts) => {
+    .option('--json', 'print the token and its details as JSON on stdout')).action(async (name, opts) => {
     const days = opts.expiresInDays === undefined ? undefined : /^[0-9]+$/.test(opts.expiresInDays) ? Number(opts.expiresInDays) : Number.NaN;
-    const outcome = await createToken(approvalDeps(opts.browser, 'this token'), {
+    const deps = approvalDeps(opts, 'this token');
+    if ('problem' in deps) {
+        usage(deps.problem);
+        return;
+    }
+    const outcome = await createToken(deps, {
         name,
         days,
         repos: opts.repo,
@@ -96,7 +108,10 @@ const createCommand = new Command('create')
             refused('the browser came back without a code; run apex token create again');
             return;
         case 'timeout':
-            refused('no approval arrived within 5 minutes; the approval page must be opened in a browser on this machine — run apex token create again');
+            refused(loopbackTimeoutHint('apex token create'));
+            return;
+        case 'expired':
+            refused('the code expired before anyone approved it; run apex token create again for a new one');
             return;
         case 'refused':
             refused(outcome.detail);
@@ -105,25 +120,28 @@ const createCommand = new Command('create')
 });
 const reachOf = (t) => (t.repos === undefined || t.repos.length === 0 ? 'all' : t.repos.join(', '));
 const day = (iso) => (iso === undefined ? '—' : iso.slice(0, 10));
-const editCommand = new Command('edit')
-    .description('Change what a token may do or which repositories it reaches; narrowing applies at once, widening is approved in the browser')
+const editCommand = withFlowOptions(new Command('edit')
+    .description('Change what a token may do or which repositories it reaches; narrowing applies at once, widening is approved in the browser — here, or on any device with a code')
     .argument('<id>', 'the token id, from apex token list')
     .option('--permission <permission>', `the token's whole new set of permissions, repeatable: ${PERMISSION_HELP}`, collect, [])
     .option('--add-permission <permission>', 'add one permission to what the token holds (repeatable)', collect, [])
     .option('--remove-permission <permission>', 'take one permission away (repeatable)', collect, [])
     .option('--repo <owner/repo>', "the token's new list of repositories (repeatable, up to 100)", collect, [])
     .option('--all-repos', 'let the token reach every repository you reach in its Account')
-    .option('--no-browser', 'if the edit widens the token, print the approval URL instead of opening a browser')
-    .option('--json', 'print the edited token as JSON')
-    .action(async (id, opts) => {
+    .option('--json', 'print the edited token as JSON')).action(async (id, opts) => {
     if (opts.allRepos === true && opts.repo.length > 0) {
         usage('pass --repo or --all-repos, not both');
         return;
     }
+    const deps = approvalDeps(opts, 'widening this token');
+    if ('problem' in deps) {
+        usage(deps.problem);
+        return;
+    }
     const client = api();
     if (!client)
         return;
-    const outcome = await editToken(client, approvalDeps(opts.browser, 'widening this token'), id, {
+    const outcome = await editToken(client, deps, id, {
         ...(opts.permission.length > 0 ? { permissions: opts.permission } : {}),
         add: opts.addPermission,
         remove: opts.removePermission,
@@ -164,7 +182,10 @@ const editCommand = new Command('edit')
             refused('the browser came back without a code; run apex token edit again');
             return;
         case 'timeout':
-            refused('no approval arrived within 5 minutes; the approval page must be opened in a browser on this machine — run apex token edit again');
+            refused(loopbackTimeoutHint('apex token edit'));
+            return;
+        case 'expired':
+            refused('the code expired before anyone approved the widening; run apex token edit again for a new one');
             return;
         case 'refused':
             refused(outcome.detail);

package/dist/src/application/authenticate.js

@@ -32,8 +32,71 @@ export const approveInBrowser = async (deps, token, accountId) => {
         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, undefined, deps.accountId);
+    const approval = await approve(deps, undefined, deps.accountId);
     if (approval.kind !== 'minted')
         return approval;
     const { minted } = approval;
@@ -49,6 +112,24 @@ export const login = async (deps) => {
         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 };
+};
 /**
  * Revoke the saved token at the control plane that minted it, then forget it
  * (control-plane ADR-0064: a token may revoke itself and nothing else). The file

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 { editedPermissions, tokenEditProblem, tokenRequestProblem } from '../domain/credentials.js';
-import { approveInBrowser } from './authenticate.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
@@ -11,7 +11,7 @@ export const createToken = async (deps, input) => {
     const problem = tokenRequestProblem(name, input.days, input.repos, input.permissions);
     if (problem !== undefined)
         return { kind: 'invalid', detail: problem };
-    const approval = await approveInBrowser({ ...deps, name }, {
+    const approval = await approve({ ...deps, name }, {
         purpose: 'token',
         permissions: [...new Set(input.permissions)],
         ...(input.days === undefined ? {} : { days: input.days }),
@@ -81,7 +81,7 @@ export const editToken = async (api, approval, id, edit) => {
     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 approveInBrowser({ ...approval, name: target.name }, {
+    const approved = await approve({ ...approval, name: target.name }, {
         purpose: 'edit',
         tokenId: id,
         permissions,

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. */
@@ -209,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\`.`;

package/dist/src/domain/grants.js

@@ -0,0 +1,111 @@
+// domain layer — see ../../../../docs/conventions.md §1
+/**
+ * Complimentary access from the terminal (control-plane ADR-0056 as amended by
+ * ADR-0079, TASK-0199): the grant and installation shapes the admin API
+ * answers with, the checks `apex grant` makes before a round trip — the
+ * control plane makes them again — and how each reads as a line.
+ */
+/** The admin API's limits on a grant (control-plane `domain/grant.ts`). */
+export const MAX_GRANT_MINUTES = 120_000;
+export const MAX_GRANT_CONCURRENCY = 50;
+export const MAX_GRANT_REASON = 500;
+const whole = (raw, min, max) => {
+    if (raw === undefined || !/^[0-9]+$/.test(raw.trim()))
+        return undefined;
+    const n = Number(raw.trim());
+    return Number.isSafeInteger(n) && n >= min && n <= max ? n : undefined;
+};
+/**
+ * `--until YYYY-MM-DD`: the grant ends at the end of that UTC day, as the Console's form has it — so the
+ * instant sent is the next day's midnight. A day that is not a real date, or not after `now`, is refused.
+ */
+export const endOfDay = (day, now) => {
+    const value = day.trim();
+    const start = /^\d{4}-\d{2}-\d{2}$/.test(value) ? new Date(`${value}T00:00:00.000Z`) : new Date(Number.NaN);
+    if (Number.isNaN(start.getTime()) || start.toISOString().slice(0, 10) !== value)
+        return { ok: false, problem: `--until must be a date, YYYY-MM-DD, got ${JSON.stringify(day)}` };
+    const end = new Date(start.getTime() + 86_400_000);
+    if (end.getTime() <= now.getTime())
+        return { ok: false, problem: '--until must be today or later — the grant ends at the end of that UTC day' };
+    return { ok: true, value: end.toISOString() };
+};
+const minutesProblem = `--minutes must be a whole number from 1 to ${MAX_GRANT_MINUTES.toLocaleString('en-US')}`;
+const concurrencyProblem = `--concurrency must be a whole number from 1 to ${MAX_GRANT_CONCURRENCY}`;
+/** `apex grant create`'s arguments, checked. */
+export const createGrantBody = (installation, flags, now) => {
+    const installationId = whole(installation, 1, Number.MAX_SAFE_INTEGER);
+    if (installationId === undefined)
+        return { ok: false, problem: `expected a positive installation id, got ${JSON.stringify(installation)}` };
+    const minutesPerMonth = whole(flags.minutes, 1, MAX_GRANT_MINUTES);
+    if (minutesPerMonth === undefined)
+        return { ok: false, problem: minutesProblem };
+    const concurrency = whole(flags.concurrency, 1, MAX_GRANT_CONCURRENCY);
+    if (concurrency === undefined)
+        return { ok: false, problem: concurrencyProblem };
+    const reason = flags.reason?.trim() ?? '';
+    if (reason === '' || reason.length > MAX_GRANT_REASON)
+        return { ok: false, problem: `--reason is required, up to ${MAX_GRANT_REASON} characters — who this is for, and why they run free` };
+    if (flags.until === undefined)
+        return { ok: true, value: { installationId, minutesPerMonth, concurrency, reason } };
+    const until = endOfDay(flags.until, now);
+    return until.ok ? { ok: true, value: { installationId, minutesPerMonth, concurrency, reason, expiresAt: until.value } } : until;
+};
+/** `apex grant update`'s flags, checked: at least one change, each well-formed, and not both an end date and none. */
+export const updateGrantBody = (flags, now) => {
+    const body = {};
+    if (flags.minutes !== undefined) {
+        const n = whole(flags.minutes, 1, MAX_GRANT_MINUTES);
+        if (n === undefined)
+            return { ok: false, problem: minutesProblem };
+        body.minutesPerMonth = n;
+    }
+    if (flags.concurrency !== undefined) {
+        const n = whole(flags.concurrency, 1, MAX_GRANT_CONCURRENCY);
+        if (n === undefined)
+            return { ok: false, problem: concurrencyProblem };
+        body.concurrency = n;
+    }
+    if (flags.until !== undefined && flags.noEnd === true)
+        return { ok: false, problem: 'pass --until or --no-end, not both' };
+    if (flags.noEnd === true)
+        body.expiresAt = null;
+    if (flags.until !== undefined) {
+        const until = endOfDay(flags.until, now);
+        if (!until.ok)
+            return until;
+        body.expiresAt = until.value;
+    }
+    if (Object.keys(body).length === 0)
+        return { ok: false, problem: 'nothing to change: pass --minutes, --concurrency, --until or --no-end' };
+    return { ok: true, value: body };
+};
+const day = (iso) => iso?.slice(0, 10);
+/** One grant as a line: whose, how it stands, the month so far, and who granted it and why. */
+export const grantLine = (g) => {
+    const used = g.usedMinutes === undefined ? '' : `${Math.floor(g.usedMinutes).toLocaleString('en-US')} of `;
+    const state = g.state === 'ended' ? `ended ${day(g.endedAt ?? g.revokedAt) ?? ''}${g.revokedBy === undefined ? '' : ` by ${g.revokedBy}`}`.trim() : g.dormant ? `${g.state}, dormant — they pay for a plan` : g.state;
+    const until = g.expiresAt === undefined ? '' : `, until ${day(g.expiresAt) ?? ''}`;
+    return `${g.id}  ${g.owner} (installation ${g.installationId}) — ${state}; ${used}${g.minutesPerMonth.toLocaleString('en-US')} minutes a month, ${g.concurrency} at once${until}; granted by ${g.grantedBy}: ${g.reason}`;
+};
+/** What a create means, in the Console's words: open, a replacement, or dormant behind a subscription. */
+export const createdLine = (c) => c.dormant
+    ? `Granted to ${c.grant.owner}. They pay for a plan, so the grant is dormant until they stop.`
+    : `Granted to ${c.grant.owner}.${c.superseded === undefined ? '' : ' It replaces the grant they held.'}`;
+export const revokedLine = (r) => `Revoked the grant for ${r.grant.owner}.${r.cancelledJobs > 0 ? ` ${r.cancelledJobs} queued job${r.cancelledJobs === 1 ? ' was' : 's were'} cancelled.` : ''}`;
+/** One installation as a line: whose, and what Apex knows of it — or that it is new. */
+export const installationLine = (i) => {
+    const known = [
+        i.accountId === undefined ? 'no Account' : `Account ${i.accountId}`,
+        ...(i.subscription === undefined ? [] : [`subscription ${i.subscription}`]),
+        ...(i.grant === undefined ? [] : [`grant ${i.grant}`]),
+        ...(i.recentUsage ? ['ran in the last 30 days'] : []),
+    ];
+    return `${i.installationId}  ${i.account.login} (${i.account.type === 'User' ? 'personal account' : 'organization'})${i.listedAsTenant ? '' : ' — new'} · ${known.join(', ')}`;
+};
+/**
+ * The control plane refuses a grant write made with the machine token, and every operator route to an Account
+ * token. Either way the remedy is the operator token: say so.
+ */
+export const withOperatorHint = (message) => /machine token|no token reaches|operator’s|only the grant routes|not signed in/.test(message)
+    ? `${message} — sign in as an operator with: apex login --console`
+    : message;

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

@@ -3,7 +3,7 @@ import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { withPermissionHint } from '../domain/credentials.js';
-import { NotConfiguredError, apiUrlFrom, resolveCredential } from './credentials.js';
+import { NotConfiguredError, apiUrlFrom, resolveCredential, resolveOperatorCredential } 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 {
@@ -48,7 +48,7 @@ export class HttpControlPlane {
             this.credentialsAlsoPresent = [];
         }
         else {
-            const resolved = resolveCredential();
+            const resolved = config.operator === true ? resolveOperatorCredential() : resolveCredential();
             this.#token = resolved.token;
             this.#baseUrl = (config.baseUrl ?? resolved.apiUrl).replace(/\/$/, '');
             this.credentialSource = resolved.source;
@@ -247,6 +247,22 @@ export class HttpControlPlane {
     async accountsBackfill(input, apply) {
         return await this.#json('POST', `/api/v1/admin/accounts/backfill${apply ? '?apply=true' : ''}`, input);
     }
+    // ── complimentary access (control-plane ADR-0056, ADR-0079): the admin API's shapes, unchanged ──
+    async listGrants() {
+        return (await this.#json('GET', '/api/v1/admin/grants')).grants;
+    }
+    async createGrant(body) {
+        return await this.#json('POST', '/api/v1/admin/grants', body);
+    }
+    async updateGrant(id, body) {
+        return (await this.#json('PATCH', `/api/v1/admin/grants/${encodeURIComponent(id)}`, body)).grant;
+    }
+    async revokeGrant(id) {
+        return await this.#json('DELETE', `/api/v1/admin/grants/${encodeURIComponent(id)}`);
+    }
+    async listInstallations() {
+        return (await this.#json('GET', '/api/v1/admin/installations')).installations;
+    }
     async accountsUnconnected() {
         return (await this.#json('GET', '/api/v1/admin/accounts/unconnected')).installations;
     }

package/dist/src/infrastructure/credentials.js

@@ -9,6 +9,7 @@ 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';
+export const CONSOLE_URL_ENV = 'APEX_CONSOLE_URL';
 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);
@@ -35,6 +36,11 @@ export class InsecureCredentialsError extends NotConfiguredError {
 }
 /** `$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');
+/**
+ * `$XDG_CONFIG_HOME/apex/console-credentials`: where `apex login --console` keeps the operator token
+ * (control-plane ADR-0079) — beside the Account login, never in place of it.
+ */
+export const consoleCredentialsPath = (env = process.env) => join(dirname(credentialsPath(env)), 'console-credentials');
 /**
  * Adapter: the credentials file `apex login` writes.
  *
@@ -154,3 +160,20 @@ export const resolveCredential = (env = process.env, store = new FileCredentialS
     }
     throw new NotConfiguredError();
 };
+/**
+ * Which credential an operator command — `apex grant`, `apex tenant installations` — uses (control-plane
+ * ADR-0079): the operator token `apex login --console` saved, when it is private, unexpired and was minted by
+ * the control plane `APEX_API_URL` names; otherwise the ordinary order ({@link resolveCredential}), in which
+ * the machine token can read grants and is refused every write. An expired operator token is skipped, and
+ * the refusal that follows says to sign in again.
+ */
+export const resolveOperatorCredential = (env = process.env, consoleStore = new FileCredentialStore(consoleCredentialsPath(env)), fallback = () => resolveCredential(env), now = new Date()) => {
+    const explicitUrl = set(env[URL_ENV]) ? normaliseUrl(env[URL_ENV]) : undefined;
+    const saved = consoleStore.read();
+    if (saved !== undefined && !hasExpired(saved, now)) {
+        const mintedBy = normaliseUrl(saved.apiUrl);
+        if (explicitUrl === undefined || explicitUrl === mintedBy)
+            return { token: saved.token, apiUrl: mintedBy, source: 'console' };
+    }
+    return fallback();
+};

package/dist/src/infrastructure/device-login.js

@@ -0,0 +1,82 @@
+// infrastructure layer — see ../../../../docs/conventions.md §1
+import { existsSync } from 'node:fs';
+import { hostname, platform, release, type } from 'node:os';
+import { headlessReason, isDevicePollError, normaliseUrl } from '../domain/credentials.js';
+import { redeemedFrom } from './loopback-login.js';
+/**
+ * The device flow's adapters (control-plane ADR-0075): the two calls, what this machine says about
+ * itself, and whether a browser can open here at all.
+ */
+/** Why no browser can open here, read from this process's environment; `undefined` when one can. */
+export const detectHeadless = () => headlessReason({ env: process.env, platform: process.platform, dockerenv: existsSync('/.dockerenv') });
+/** What the approval page shows as "reported by the terminal": this machine's name and system. */
+export const machineReport = () => ({
+    hostname: hostname().slice(0, 100),
+    os: `${type()} ${release()} (${platform()})`.slice(0, 100),
+});
+export const sleep = async (ms) => await new Promise((resolve) => setTimeout(resolve, ms));
+/** Adapter: `POST /api/v1/cli/device` and the `{ deviceCode }` poll of `POST /api/v1/cli/token`. No credential either way. */
+export class HttpDeviceExchange {
+    #baseUrl;
+    #fetch;
+    constructor(baseUrl, fetchImpl = fetch) {
+        this.#baseUrl = normaliseUrl(baseUrl);
+        this.#fetch = fetchImpl;
+    }
+    async start(request) {
+        const body = await this.#post('/api/v1/cli/device', {
+            name: request.name,
+            purpose: request.purpose,
+            ...(request.days === undefined ? {} : { expiresInDays: request.days }),
+            ...(request.repos === undefined ? {} : { repos: request.repos }),
+            ...(request.permissions === undefined ? {} : { permissions: request.permissions }),
+            ...(request.accountId === undefined ? {} : { accountId: request.accountId }),
+            ...(request.tokenId === undefined ? {} : { tokenId: request.tokenId }),
+            ...(request.allRepositories === true ? { allRepositories: true } : {}),
+            ...(request.os === undefined ? {} : { os: request.os }),
+            ...(request.hostname === undefined ? {} : { hostname: request.hostname }),
+        });
+        if (!body.ok) {
+            if (body.status === 429)
+                throw new Error('too many device logins from this address this hour — wait, or approve in a browser on this machine with --browser');
+            throw new Error(typeof body.json['error'] === 'string' ? body.json['error'] : `starting the device login failed with ${body.status}`);
+        }
+        const j = body.json;
+        if (typeof j['deviceCode'] !== 'string' || typeof j['userCode'] !== 'string' || typeof j['verificationUri'] !== 'string') {
+            throw new Error('the control plane answered the device login without a code — is it older than this CLI?');
+        }
+        return {
+            deviceCode: j['deviceCode'],
+            userCode: j['userCode'],
+            verificationUri: j['verificationUri'],
+            expiresIn: typeof j['expiresIn'] === 'number' ? j['expiresIn'] : 600,
+            interval: typeof j['interval'] === 'number' ? j['interval'] : 5,
+        };
+    }
+    async poll(deviceCode) {
+        const body = await this.#post('/api/v1/cli/token', { deviceCode });
+        if (body.ok)
+            return { kind: 'minted', minted: redeemedFrom(body.json) };
+        const error = body.json['error'];
+        const interval = body.json['interval'];
+        if (body.status === 400 && isDevicePollError(error))
+            return { kind: error, ...(typeof interval === 'number' ? { interval } : {}) };
+        throw new Error(typeof error === 'string' ? error : `polling the device login failed with ${body.status}`);
+    }
+    async #post(path, payload) {
+        let response;
+        try {
+            response = await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: 'POST',
+                headers: { accept: 'application/json', 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (err) {
+            throw new Error(`${this.#baseUrl} is unreachable: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        const json = (await response.json().catch(() => ({})));
+        return { ok: response.ok, status: response.status, json };
+    }
+}