@brass-build/cli 0.3.0 → 0.4.1

package/src/config.ts

@@ -79,7 +79,13 @@ export interface CredentialInputs {
 // refreshes into short-lived access tokens.
 export type ResolvedCredential =
   | { kind: 'service'; token: string; source: 'flag' | 'env' | 'file' }
-  | { kind: 'session'; sid: string; source: 'file' };
+  // `authBaseUrl` is the origin the session was minted on, carried so every
+  // command refreshes it THERE. The profile is keyed on the api host, so an
+  // invocation naming `--api-url` alone lands on a stored session and would
+  // otherwise refresh it against whatever auth origin the flags defaulted to,
+  // which answers 401 and reads as the sign-in having gone stale. Absent on a
+  // file an older CLI wrote, which falls back to the invocation's origin.
+  | { kind: 'session'; sid: string; source: 'file'; authBaseUrl?: string };
 
 // Resolve which credential to use, most-explicit first: an inline `--token`,
 // then `BRASS_SERVICE_TOKEN`, then the stored login session, then a stored
@@ -94,7 +100,14 @@ export function resolveCredential(inputs: CredentialInputs): ResolvedCredential
   }
   const stored = inputs.file?.credentials[inputs.profile];
   if (stored?.session && isNonEmpty(stored.session.sid)) {
-    return { kind: 'session', sid: stored.session.sid.trim(), source: 'file' };
+    return {
+      kind: 'session',
+      sid: stored.session.sid.trim(),
+      source: 'file',
+      ...(isNonEmpty(stored.session.authBaseUrl)
+        ? { authBaseUrl: stored.session.authBaseUrl.trim() }
+        : {}),
+    };
   }
   if (isNonEmpty(stored?.token)) {
     return { kind: 'service', token: stored.token.trim(), source: 'file' };

package/src/login.ts

@@ -21,6 +21,7 @@ import {
   writeStoredCredential,
   type PendingLogin,
 } from './store.js';
+import { renderApprovalPrompt } from './approval-prompt.js';
 import type { Logger } from './log.js';
 import type { Profile } from './config.js';
 
@@ -37,6 +38,9 @@ export interface LoginStartOptions {
   // Mint a fresh grant even when a usable one is pending (`--new`), for a
   // human who lost the relayed code.
   force?: boolean;
+  // The app to approve alongside the CLI (`--app`), so one human action
+  // covers the sign-in and the app the machine will hand a browser.
+  targetAppId?: string;
   // Set when a wait follows in the same command (`--start --wait`), whose own
   // terminal result is the one the caller reads. `--json` is one document per
   // run, so the started state prints to the human stream only.
@@ -71,7 +75,9 @@ export async function loginStart(options: LoginStartOptions): Promise<number> {
   if (resumed === null && existing !== null && existing.expiresAt > now()) {
     await postDeviceCancel(existing.authBaseUrl, existing.deviceCode);
   }
-  const pending = resumed ?? (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env));
+  const pending =
+    resumed ??
+    (await mintPendingLogin(options.authBaseUrl, now(), options.profile, env, options.targetAppId));
   promptFor(options.log, pending, {
     lead: resumed === null ? null : 'A sign-in is already waiting for approval.',
   });
@@ -131,7 +137,13 @@ export async function loginCheck(options: LoginCheckOptions): Promise<number> {
 
   for (;;) {
     if (now() >= pending.expiresAt) {
-      pending = await mintPendingLogin(pending.authBaseUrl, now(), options.profile, env);
+      pending = await mintPendingLogin(
+        pending.authBaseUrl,
+        now(),
+        options.profile,
+        env,
+        pending.targetAppId,
+      );
       intervalSeconds = pending.intervalSeconds;
       renewed = true;
       promptFor(options.log, pending, {
@@ -162,6 +174,16 @@ export async function loginCheck(options: LoginCheckOptions): Promise<number> {
       options.log.result({ state: 'denied' });
       return 1;
     }
+    // The server has stopped accepting this grant, so the stored code is one
+    // the approval page refuses. Clearing it is what stops `brass status`
+    // relaying it, and what a caller reads as "start a new one" rather than
+    // "keep waiting".
+    if (outcome.state === 'expired') {
+      await writePendingLogin(options.profile, null, env);
+      options.log.info('That sign-in expired. Run `brass login --start` to begin a new one.');
+      options.log.result({ state: 'expired' });
+      return 1;
+    }
     // RFC 8628 §3.5: polling too fast. Back off for the rest of this wait.
     if (outcome.state === 'slow_down') intervalSeconds += 5;
 
@@ -190,11 +212,13 @@ async function mintPendingLogin(
   now: number,
   profile: Profile,
   env: NodeJS.ProcessEnv,
+  targetAppId?: string,
 ): Promise<PendingLogin> {
-  const auth = await deviceAuthorize(authBaseUrl, now);
+  const auth = await deviceAuthorize(authBaseUrl, now, targetAppId);
   const pending: PendingLogin = {
     authBaseUrl,
     deviceCode: auth.deviceCode,
+    ...(targetAppId !== undefined ? { targetAppId } : {}),
     userCode: auth.userCode,
     verificationUri: auth.verificationUri,
     ...(auth.verificationUriComplete !== undefined
@@ -215,15 +239,14 @@ function remainingSeconds(pending: PendingLogin, now: number): number {
   return Math.max(0, Math.round((pending.expiresAt - now) / 1000));
 }
 
-// The one rendering of "here is what to relay, and here is what to run next",
-// so a resumed, renewed, and freshly minted grant all read the same to whoever
-// is relaying it.
 function promptFor(log: Logger, pending: PendingLogin, opts: { lead: string | null }): void {
   log.info(
-    (opts.lead !== null ? `${opts.lead}\n` : '') +
-      'To approve this sign-in, go to:\n' +
-      `  ${targetUrl(pending)}\n` +
-      `and confirm the code:  ${pending.userCode}\n` +
-      '\nThen run `brass login --check --wait` to finish signing in.',
+    renderApprovalPrompt({
+      url: targetUrl(pending),
+      code: pending.userCode,
+      lead: opts.lead,
+      nextCommand: 'brass login --check --wait',
+      relaying: true,
+    }),
   );
 }

package/src/project.ts

@@ -1,5 +1,5 @@
 import { readFile, writeFile, readdir, stat, mkdir, realpath } from 'node:fs/promises';
-import { join, relative, sep, dirname } from 'node:path';
+import { join, relative, resolve, sep, dirname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { zipSync } from 'fflate';
 import type { BrassSchemaManifest } from './api.js';
@@ -84,15 +84,90 @@ export interface AppManifest {
   [key: string]: unknown;
 }
 
+// The manifest filename, and the bundle-relative directory the capability
+// docs put it in.
+export const MANIFEST_FILENAME = 'brass-app.json';
+const WELL_KNOWN_DIR = '.well-known';
+
+// Where `publish` and `status` look for the served manifest, most
+// authoritative first. The copy inside the bundle is the one the platform
+// reads back after a deploy, so it outranks the repo root, which is the flat
+// layout an app that keeps its manifest beside `package.json` uses.
+export function publishManifestCandidates(dir: string): string[] {
+  return [join(dir, WELL_KNOWN_DIR, MANIFEST_FILENAME), MANIFEST_FILENAME];
+}
+
+// Where `schema pull` looks for a manifest to merge a pulled schema into.
+// Source locations only: a bundler rewrites its output directory on the next
+// build, so a schema written there is gone before the app is published. Each
+// candidate is used only when it already holds a file, so a layout this list
+// does not name falls back to the root default rather than being guessed at.
+export function sourceManifestCandidates(): string[] {
+  return [
+    MANIFEST_FILENAME,
+    join(WELL_KNOWN_DIR, MANIFEST_FILENAME),
+    join('public', WELL_KNOWN_DIR, MANIFEST_FILENAME),
+    join('static', WELL_KNOWN_DIR, MANIFEST_FILENAME),
+  ];
+}
+
+// Absent means no file at this path, which is what lets a caller walk a
+// candidate list. Every other failure throws: a manifest that exists and
+// cannot be parsed is a mistake to report, and answering it with `null` drops
+// the `name` and `client_token` it was written to carry, which reads as a
+// missing manifest and creates a duplicate app on the next stateless run.
 export async function readManifest(path: string): Promise<AppManifest | null> {
+  let raw: string;
   try {
-    const raw = await readFile(path, 'utf8');
-    const parsed = JSON.parse(raw) as unknown;
-    if (typeof parsed !== 'object' || parsed === null) return null;
-    return parsed as AppManifest;
-  } catch {
-    return null;
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+    throw new Error(`Could not read the manifest at ${path}: ${(err as Error).message}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch (err) {
+    throw new Error(`The manifest at ${path} is not valid JSON: ${(err as Error).message}`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`The manifest at ${path} must hold a JSON object.`);
+  }
+  return parsed as AppManifest;
+}
+
+// The first candidate that holds a manifest, paired with the path it came
+// from so a caller can name it. A candidate with no file is skipped; one that
+// is present and unreadable throws out of `readManifest`, so a malformed
+// manifest is reported rather than passed over for the next candidate down.
+export async function loadFirstManifest(
+  cwd: string,
+  candidates: readonly string[],
+): Promise<{ path: string; manifest: AppManifest } | null> {
+  for (const candidate of candidates) {
+    const manifest = await readManifest(resolve(cwd, candidate));
+    if (manifest !== null) return { path: candidate, manifest };
+  }
+  return null;
+}
+
+// The first candidate that holds a file, without parsing it. `schema pull`
+// picks its destination this way so it merges into a malformed manifest's
+// path and fails there, instead of stepping over it and writing a second
+// manifest the bundle never serves.
+export async function firstExistingManifestPath(
+  cwd: string,
+  candidates: readonly string[],
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    try {
+      if ((await stat(resolve(cwd, candidate))).isFile()) return candidate;
+    } catch {
+      // Not there, or not reachable through this path. Try the next.
+    }
   }
+  return null;
 }
 
 export async function writeManifest(path: string, manifest: AppManifest): Promise<void> {

package/src/sdk-pairing.ts

@@ -0,0 +1,53 @@
+// Which `@brass-build/client` this CLI is allowed to use.
+//
+// The dependency is pinned to one exact version, and what the CLI imports is
+// the `internal` subpath, the entry that promises nothing from one release to
+// the next. So the only copy it can run against is the one it names, and a
+// correct install always provides it.
+//
+// What does not is a CLI running somewhere its own dependency is not
+// reachable, and every way in is quiet. `npx brass` from a directory with no
+// `node_modules` fetches the CLI alone from the registry. `npm i -g` nests a
+// registry copy under the CLI. Installing the CLI tarball by itself resolves
+// the SDK from npm, which succeeds precisely because an unreleased build in a
+// working tree still carries the last released version number.
+//
+// The check is on the VERSION, not on any one export, and that is the point:
+// a check per export is re-earned every time the CLI reaches for a new one,
+// and it reports whatever that call happened to need rather than the pairing
+// that is actually wrong. One version comparison covers every surface the CLI
+// imports today and every one it adds later.
+
+export interface LoadedSdk {
+  version: string;
+  // Which file answered. The version cannot identify a copy on its own: a
+  // machine can hold several that all report the same one, which is exactly
+  // the case here, so the path is what ends the search.
+  path: string;
+}
+
+// The mismatch, as a sentence, or `null` when the pairing is sound.
+//
+// `loaded` is null when the SDK could not be resolved from the CLI's own
+// location. That is not a mismatch: it is the shape an in-repo run takes,
+// where the module specifier is mapped to the SDK's source and there is no
+// installed package to read a version from. Being unable to check is not
+// evidence of a fault, so it passes.
+export function sdkMismatchMessage(args: {
+  pinned: string | undefined;
+  loaded: LoadedSdk | null;
+}): string | null {
+  const { pinned, loaded } = args;
+  if (pinned === undefined || loaded === null) return null;
+  if (loaded.version === pinned) return null;
+  return (
+    `This CLI is built against @brass-build/client ${pinned}, and the copy it ` +
+    `loads is ${loaded.version} (${loaded.path}). It reads the SDK's internal ` +
+    `entry, which changes between releases, so the two have to match. Install ` +
+    `the CLI into the directory you run it from ("npm i @brass-build/cli") and ` +
+    `run it as ./node_modules/.bin/brass with absolute paths: a global install ` +
+    `keeps its own copy of the SDK, and npx resolves node_modules from the ` +
+    `current directory, so it fetches one from the registry when run anywhere ` +
+    `else.`
+  );
+}

package/src/session.ts

@@ -11,6 +11,7 @@
 
 import { spawn } from 'node:child_process';
 import { BrassApiError, networkError } from './api.js';
+import { renderApprovalPrompt } from './approval-prompt.js';
 import type { AuthProvider } from './auth.js';
 
 // Every auth call carries a few hundred bytes, so a host still silent after
@@ -42,11 +43,18 @@ export interface RefreshedTokens {
   // the CLI's app id, so a copy of it authenticates as the CLI and nothing
   // else.
   sessionToken?: string;
+  // The acting-app assertion minted alongside the access token, naming the
+  // CLI as the app asking. The access token names the person and never the
+  // app, so this is what the platform reads to tell a CLI call from any
+  // other caller signed in as the same person. Absent against a platform
+  // build that mints none.
+  appAssertion?: string;
 }
 
 interface RefreshWire {
   access_token: string;
   id_token: string;
+  app_assertion?: string;
   expires_in: number;
   session_token?: string;
 }
@@ -119,6 +127,7 @@ export async function postRefresh(
     idToken: json.id_token,
     expiresAt: now + tokenTtlSeconds(json.expires_in) * 1000,
     ...(json.session_token ? { sessionToken: json.session_token } : {}),
+    ...(json.app_assertion ? { appAssertion: json.app_assertion } : {}),
   };
 }
 
@@ -151,6 +160,77 @@ export async function postSignOut(
   }
 }
 
+export type BrowserSessionOutcome =
+  | { state: 'ready'; url: string; expiresIn: number }
+  // The app is not approved for the platform session behind this machine's
+  // sign-in. The URL is a page the human opens to grant it; the mint is a
+  // re-run of the same command afterwards.
+  | { state: 'needs_approval'; approvalUrl: string; expiresIn: number };
+
+interface BrowserSessionWire {
+  url?: string;
+  expires_in?: number;
+  error?: string;
+  error_description?: string;
+  approval_url?: string;
+}
+
+// Ask the auth API for a URL that signs a browser in as the human this
+// machine is signed in as. The stored device pointer is the credential, and
+// the answer is `return_to` with a one-time code on it, so what reaches the
+// browser expires in minutes and is spent once.
+//
+// The URL is a credential for as long as it lives. It belongs in the browser
+// the caller is about to drive, not in a log, a PR body, or a commit.
+export async function postDeviceAppSession(
+  authBaseUrl: string,
+  sid: string,
+  args: { appId: string; returnTo: string },
+  origin: string = REFRESH_ORIGIN,
+): Promise<BrowserSessionOutcome> {
+  const url = `${authBaseUrl}/device/app-session`;
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', origin },
+      body: new URLSearchParams({ sid, app_id: args.appId, return_to: args.returnTo }),
+      signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
+    });
+  } catch (cause) {
+    throw networkError(`reaching ${authBaseUrl}`, cause);
+  }
+  const json = (await response.json().catch(() => ({}))) as BrowserSessionWire;
+  if (response.ok) {
+    if (!json.url) {
+      throw new BrassApiError(response.status, 'Brass returned no browser-session URL.');
+    }
+    return {
+      state: 'ready',
+      url: json.url,
+      expiresIn: tokenTtlSeconds(json.expires_in),
+    };
+  }
+  if (json.error === 'app_not_approved' && json.approval_url) {
+    return {
+      state: 'needs_approval',
+      approvalUrl: json.approval_url,
+      expiresIn: tokenTtlSeconds(json.expires_in),
+    };
+  }
+  // The server's own wording where it has one: every refusal here names a
+  // specific thing the caller can fix (an unknown app, a return_to off the
+  // allowlist, a sign-in that has ended), and rewording them locally would
+  // lose which.
+  throw new BrassApiError(
+    response.status,
+    json.error_description ??
+      (response.status === 401
+        ? "Your Brass sign-in is no longer valid (401). Run 'brass login' to sign in again."
+        : `Could not mint a browser session (${response.status}).`),
+  );
+}
+
 // Abandon a sign-in this machine started and never redeemed, so the code it
 // relayed to a human stops being redeemable. Reports whether the server took
 // it, like `postSignOut`: the record naming the grant is the caller's only
@@ -216,11 +296,17 @@ interface DeviceAuthorizeWire {
   expires_in: number;
 }
 
+// `targetAppId` is the app the machine will hand a browser once it is signed
+// in (`brass login --app`). The grant still mints for the CLI alone; naming a
+// target only widens what the human's one approval covers, so a later
+// `brass browser-session` needs no second trip to a browser.
 export async function deviceAuthorize(
   authBaseUrl: string,
   now: number = Date.now(),
+  targetAppId?: string,
 ): Promise<DeviceAuthorization> {
   const body = new URLSearchParams({ app_id: CLI_APP_ID });
+  if (targetAppId !== undefined) body.set('target_app_id', targetAppId);
   let response: Response;
   try {
     response = await fetch(`${authBaseUrl}/device/authorize`, {
@@ -232,8 +318,18 @@ export async function deviceAuthorize(
   } catch (cause) {
     throw new Error(`Network error reaching ${authBaseUrl}: ${String(cause)}`);
   }
-  if (!response.ok) throw new Error(`Device sign-in could not start (${response.status})`);
-  const json = (await response.json()) as DeviceAuthorizeWire;
+  // The server's own reason where it sent one. Every 400 here names a
+  // specific thing the caller got wrong (an app id that is not an app, an app
+  // that does not support device sign-in), and a status on its own sends them
+  // looking at the network instead.
+  const json = (await response.json().catch(() => ({}))) as DeviceAuthorizeWire & {
+    error_description?: string;
+  };
+  if (!response.ok) {
+    throw new Error(
+      json.error_description ?? `Device sign-in could not start (${response.status})`,
+    );
+  }
   return {
     deviceCode: json.device_code,
     userCode: json.user_code,
@@ -260,7 +356,12 @@ export type DevicePollOutcome =
   | { state: 'approved'; tokens: RefreshedTokens }
   | { state: 'pending' }
   | { state: 'slow_down' }
-  | { state: 'denied' };
+  | { state: 'denied' }
+  // The grant is spent, cancelled, unknown, or its session has ended. The
+  // server returns this to stop the polling, so a caller that reads it as
+  // "keep waiting" relays a code the approval page refuses for the rest of
+  // its own deadline.
+  | { state: 'expired' };
 
 export async function pollDeviceTokenOnce(
   authBaseUrl: string,
@@ -294,11 +395,17 @@ export async function pollDeviceTokenOnce(
         idToken: json.id_token,
         expiresAt: now + tokenTtlSeconds(json.expires_in) * 1000,
         ...(json.session_token ? { sessionToken: json.session_token } : {}),
+        ...(json.app_assertion ? { appAssertion: json.app_assertion } : {}),
       },
     };
   }
-  // The user declined: the one terminal refusal.
+  // The user declined: the one terminal refusal the person chose.
   if (json.error === 'access_denied') return { state: 'denied' };
+  // The other terminal one, which the server chose: the grant was consumed,
+  // cancelled, is unknown, or its session has ended. No later poll of this
+  // grant can be approved, so waiting out the deadline only relays a code the
+  // approval page will not take.
+  if (json.error === 'expired_token') return { state: 'expired' };
   // RFC 8628 §3.5: polling too fast. The caller backs off.
   if (json.error === 'slow_down') return { state: 'slow_down' };
   // Everything else is "keep waiting": `authorization_pending`, a transient
@@ -328,12 +435,17 @@ export async function pollDeviceToken(
     const outcome = await pollDeviceTokenOnce(authBaseUrl, auth.deviceCode, now());
     if (outcome.state === 'approved') return outcome.tokens;
     if (outcome.state === 'denied') throw new Error('Sign-in was denied.');
+    if (outcome.state === 'expired') {
+      throw new Error('Device sign-in expired. Run `brass login` again.');
+    }
     if (outcome.state === 'slow_down') intervalSeconds += 5;
   }
 }
 
 export interface DeviceLoginOptions {
   authBaseUrl: string;
+  // An app to approve alongside the CLI (`brass login --app`).
+  targetAppId?: string;
   // Shows the verification URL + user code to the human; defaults to stderr.
   onPrompt?: (auth: DeviceAuthorization) => void;
   // Opens the approval page (user code prefilled) in a browser; defaults to
@@ -344,7 +456,7 @@ export interface DeviceLoginOptions {
 }
 
 export async function loginDevice(options: DeviceLoginOptions): Promise<LoginResult> {
-  const auth = await deviceAuthorize(options.authBaseUrl);
+  const auth = await deviceAuthorize(options.authBaseUrl, Date.now(), options.targetAppId);
   (options.onPrompt ?? defaultDevicePrompt)(auth);
   (options.openBrowser ?? openBrowser)(auth.verificationUriComplete ?? auth.verificationUri);
   const tokens = await pollDeviceToken(
@@ -357,12 +469,14 @@ export async function loginDevice(options: DeviceLoginOptions): Promise<LoginRes
 }
 
 function defaultDevicePrompt(auth: DeviceAuthorization): void {
-  const target = auth.verificationUriComplete ?? auth.verificationUri;
   process.stderr.write(
-    '\nOpening your browser to approve this sign-in.\n' +
-      `If it doesn't open, go to:\n  ${target}\n` +
-      `and confirm the code:  ${auth.userCode}\n` +
-      '\nWaiting for approval...\n',
+    `\n${renderApprovalPrompt({
+      url: auth.verificationUriComplete ?? auth.verificationUri,
+      code: auth.userCode,
+      // This command polls to approval on its own, so there is nothing further
+      // to run; what the reader needs is that the wait has started.
+      closing: 'Waiting for approval...',
+    })}\n`,
   );
 }
 
@@ -398,7 +512,17 @@ export function sessionAuth(authBaseUrl: string, sid: string): AuthProvider {
       if (cached === null || Date.now() >= cached.expiresAt - SKEW_MS) {
         cached = await postRefresh(authBaseUrl, sid);
       }
-      return { authorization: `Bearer ${cached.accessToken}`, 'x-id-token': cached.idToken };
+      return {
+        authorization: `Bearer ${cached.accessToken}`,
+        'x-id-token': cached.idToken,
+        // Refreshed on the same call as the token, so the two always name
+        // the same grant. Omitted rather than sent empty when the platform
+        // minted none, since a header the verifier cannot read is the same
+        // as no header and an empty one only obscures which it was.
+        ...(cached.appAssertion
+          ? { 'x-brass-app-assertion': cached.appAssertion }
+          : {}),
+      };
     },
   };
 }

package/src/store.ts

@@ -47,6 +47,9 @@ export async function writeStoredCredential(
 export interface PendingLogin {
   authBaseUrl: string;
   deviceCode: string;
+  // The app named by `brass login --app`, carried so a grant this CLI renews
+  // in place asks for the same approval the relayed one did.
+  targetAppId?: string;
   userCode: string;
   verificationUri: string;
   verificationUriComplete?: string;
@@ -112,6 +115,80 @@ export async function writePendingLogin(
   } satisfies PendingLoginsFile);
 }
 
+// An app approval `brass browser-session` asked for and no one has granted
+// yet. Recorded for the same reason a pending sign-in is: the caller relayed a
+// URL to a human and now has to wait, and `brass status` is where it asks what
+// is outstanding. Without it, status reports the app as ready and names a next
+// step that is not the blocked one.
+//
+// One per profile, carrying the app it is for, so status reports it only
+// against the app it resolved. A second app asked about while a first is
+// pending overwrites it; the link it replaces stays valid on the server, and
+// re-running the command for that app reports it again.
+export interface PendingApproval {
+  appId: string;
+  approvalUrl: string;
+  authBaseUrl: string;
+  expiresAt: number;
+}
+
+interface PendingApprovalsFile {
+  version: 1;
+  pending: Record<Profile, PendingApproval>;
+}
+
+export function pendingApprovalFilePath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(dirname(credentialsFilePath(env)), 'pending-approval.json');
+}
+
+async function readPendingApprovalsFile(
+  env: NodeJS.ProcessEnv,
+): Promise<PendingApprovalsFile | null> {
+  try {
+    const raw = await readFile(pendingApprovalFilePath(env), 'utf8');
+    const parsed = JSON.parse(raw) as PendingApprovalsFile;
+    if (parsed.version !== 1 || typeof parsed.pending !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function readPendingApproval(
+  profile: Profile,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<PendingApproval | null> {
+  const entry = (await readPendingApprovalsFile(env))?.pending[profile];
+  if (
+    entry === undefined ||
+    typeof entry.appId !== 'string' ||
+    typeof entry.approvalUrl !== 'string' ||
+    typeof entry.expiresAt !== 'number'
+  ) {
+    return null;
+  }
+  return entry;
+}
+
+// The approval URL names a question rather than carrying a credential (the
+// page still gates on the reader's own cookie), but the file is written
+// owner-only like its siblings: what it discloses is which machine is asking
+// about which app.
+export async function writePendingApproval(
+  profile: Profile,
+  pending: PendingApproval | null,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const existing = (await readPendingApprovalsFile(env)) ?? { version: 1 as const, pending: {} };
+  const entries = { ...existing.pending };
+  if (pending === null) delete entries[profile];
+  else entries[profile] = pending;
+  await writeOwnerOnlyJson(pendingApprovalFilePath(env), {
+    version: 1,
+    pending: entries,
+  } satisfies PendingApprovalsFile);
+}
+
 async function writeOwnerOnlyJson(path: string, payload: unknown): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });

package/src/version.ts

@@ -3,6 +3,6 @@
 // free here, unlike the SDK's query-param channel). Lets the platform
 // measure the CLI version distribution, in particular pinned CI copies.
 // A unit test pins this to package.json's version.
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.1';
 
 export const CLI_CLIENT_ID = `cli/${VERSION}`;