requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/session-files.mjs

@@ -0,0 +1,192 @@
+// @ts-check
+
+import * as nativeFs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError } from "./errors.mjs";
+import { protectPrivatePath } from "./private-path.mjs";
+
+const MAX_SESSION_BYTES = 65_536;
+
+/** Filesystem errors never expose exception text that might contain credentials. */
+export class SessionFiles {
+  /** @param {string} file @param {{platform?: NodeJS.Platform, fs?: Partial<typeof nativeFs>, protectPath?: (file: string, directory: boolean) => Promise<void>, syncDirectory?: () => Promise<void>, lockWaitMs?: number}} [options] */
+  constructor(file, options = {}) {
+    this.file = file;
+    this.directory = path.dirname(file);
+    this.lock = `${file}.lock`;
+    this.fs = { ...nativeFs, ...options.fs };
+    this.platform = options.platform ?? process.platform;
+    this.protectPath = options.protectPath ?? ((file, directory) => this.#protect(file, directory));
+    this.syncDirectory = options.syncDirectory ?? (() => this.#syncDirectory());
+    this.lockWaitMs = options.lockWaitMs ?? 10_000;
+  }
+
+  /** @template T @param {() => Promise<T>} action @returns {Promise<T>} */
+  async withLock(action) {
+    await this.#prepareDirectory();
+    const deadline = performance.now() + this.lockWaitMs;
+    let handle;
+    while (!handle) {
+      try { handle = await this.fs.open(this.lock, "wx", 0o600); }
+      catch (error) {
+        if (errorCode(error) !== "EEXIST") throw storageFailure();
+        if (performance.now() >= deadline) {
+          throw new CliError("Another RequestShield command holds the session lock. Retry after it exits. If a command crashed, remove the session.json.lock file only after confirming no RequestShield command is running.", {
+            code: "SESSION_LOCKED", exitCode: 7,
+          });
+        }
+        await delay(40);
+      }
+    }
+    try {
+      // Never steal an old-looking lock: a suspended process may own it while
+      // its provider request rotates a token. No credentials enter this file.
+      await handle.writeFile(JSON.stringify({ pid: process.pid, id: randomUUID() }));
+      return await action();
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    } finally {
+      await handle.close().catch(() => undefined);
+      await this.fs.rm(this.lock, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async read() {
+    let handle;
+    try {
+      const directory = await this.fs.lstat(this.directory);
+      if (!directory.isDirectory() || directory.isSymbolicLink()) throw storageFailure();
+      const stat = await this.fs.lstat(this.file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw storageFailure();
+      if (this.platform !== "win32" && process.platform !== "win32"
+        && ((stat.mode & 0o077) !== 0 || (directory.mode & 0o077) !== 0
+          || stat.uid !== process.getuid?.() || directory.uid !== process.getuid?.())) throw permissionFailure();
+      handle = await this.fs.open(this.file, "r");
+      const buffer = Buffer.alloc(MAX_SESSION_BYTES + 1);
+      let total = 0;
+      while (total < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+        if (bytesRead === 0) break;
+        total += bytesRead;
+      }
+      if (total > MAX_SESSION_BYTES) throw invalidFile();
+      try { return JSON.parse(buffer.subarray(0, total).toString("utf8")); }
+      catch { throw invalidFile(); }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (errorCode(error) === "ENOENT") {
+        throw new CliError("Not signed in. Run `requestshield login` first.", { code: "NOT_SIGNED_IN", exitCode: 3 });
+      }
+      throw storageFailure();
+    } finally { await handle?.close().catch(() => undefined); }
+  }
+
+  /** Remove only the selected regular credential file under the refresh lock.
+   * No JSON parsing is needed, so malformed or mismatched sessions can be cleared.
+   */
+  async remove() {
+    try {
+      const directory = await this.fs.lstat(this.directory);
+      if (!directory.isDirectory() || directory.isSymbolicLink()) throw storageFailure();
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") return false;
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    }
+    return this.withLock(async () => {
+      let removed = false;
+      try {
+        const existing = await this.fs.lstat(this.file);
+        if (!existing.isFile() || existing.isSymbolicLink()) throw storageFailure();
+        await this.fs.unlink(this.file);
+        removed = true;
+        await this.syncDirectory();
+        return true;
+      } catch (error) {
+        if (removed) {
+          throw new CliError("The local session was removed, but its durability could not be confirmed. Run `requestshield logout` again to confirm removal.", {
+            code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
+          });
+        }
+        if (errorCode(error) === "ENOENT") return false;
+        if (error instanceof CliError) throw error;
+        throw storageFailure();
+      }
+    });
+  }
+
+  /** Caller holds the session lock. @param {unknown} value */
+  async write(value) {
+    const temp = `${this.file}.${randomUUID()}.tmp`;
+    let handle;
+    let replaced = false;
+    try {
+      try {
+        const existing = await this.fs.lstat(this.file);
+        if (!existing.isFile() || existing.isSymbolicLink()) throw storageFailure();
+      } catch (error) { if (errorCode(error) !== "ENOENT") throw error; }
+      handle = await this.fs.open(temp, "wx", 0o600);
+      await this.protectPath(temp, false);
+      const serialized = `${JSON.stringify(value)}\n`;
+      if (Buffer.byteLength(serialized) > MAX_SESSION_BYTES) throw invalidFile();
+      await handle.writeFile(serialized, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await this.fs.rename(temp, this.file);
+      replaced = true;
+      await this.syncDirectory();
+    } catch (error) {
+      if (replaced) {
+        throw new CliError("The session was replaced, but its durability could not be confirmed. Run `requestshield login` again if the next command cannot load it.", {
+          code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
+        });
+      }
+      if (error instanceof CliError) throw error;
+      throw storageFailure();
+    } finally {
+      await handle?.close().catch(() => undefined);
+      await this.fs.rm(temp, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async #prepareDirectory() {
+    try {
+      await this.fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+      const stat = await this.fs.lstat(this.directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw permissionFailure();
+      await this.protectPath(this.directory, true);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw permissionFailure();
+    }
+  }
+
+  async #syncDirectory() {
+    if (this.platform === "win32" || process.platform === "win32") return;
+    const directory = await this.fs.open(this.directory, "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  }
+
+  /** @param {string} file @param {boolean} directory */
+  async #protect(file, directory) {
+    try {
+      await protectPrivatePath(file, directory, {platform: this.platform, fs: this.fs});
+    } catch { throw permissionFailure(); }
+  }
+}
+
+/** @param {unknown} error */
+function errorCode(error) { return error && typeof error === "object" ? Reflect.get(error, "code") : undefined; }
+function storageFailure() {
+  return new CliError("Could not read or safely save the RequestShield session. Check local storage permissions and sign in again if a refresh was interrupted.", { code: "SESSION_STORAGE_ERROR", exitCode: 7 });
+}
+function permissionFailure() {
+  return new CliError("Could not protect the RequestShield session for the current operating-system user. No new credentials were written.", { code: "SESSION_PERMISSION_ERROR", exitCode: 7 });
+}
+function invalidFile() {
+  return new CliError("The saved RequestShield session is invalid. Run `requestshield login` again.", { code: "INVALID_SESSION", exitCode: 3 });
+}

package/src/session-store.mjs

@@ -0,0 +1,204 @@
+// @ts-check
+
+import os from "node:os";
+import path from "node:path";
+import { CliError } from "./errors.mjs";
+import { getApiUrl, getOAuthConfig, validateBearerToken } from "./config.mjs";
+import { OAuthClient } from "./oauth-client.mjs";
+import { SessionFiles } from "./session-files.mjs";
+
+/** @typedef {{accessToken: string, refreshToken: string, expiresAt: number, scopes: string[]}} Credentials */
+/** @typedef {{issuer: string, clientId: string, apiUrl: string}} OAuthConfig */
+/** @typedef {Credentials & {version: 1, issuer: string, clientId: string, apiUrl: string, refreshState: "ready" | "in_progress"}} SavedSession */
+/** @typedef {'signed_out' | 'valid' | 'expired' | 'refresh_uncertain' | 'config_mismatch' | 'invalid' | 'configuration_error'} SessionState */
+/** @typedef {{profile: import('./config.mjs').Profile, apiUrl: string | null, issuer: string | null, clientId: string | null, state: SessionState, localOnly: true, expiresAt?: number, scopes?: string[]}} SessionStatus */
+
+const REFRESH_WINDOW_MS = 60_000;
+
+export class SessionStore {
+  /**
+   * @param {{env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, homeDir?: string, profile?: import("./config.mjs").Profile,
+   * config?: OAuthConfig, oauth?: {refresh(token: string): Promise<Credentials>},
+   * now?: () => number, fs?: Partial<typeof import("node:fs/promises")>,
+   * protectPath?: (file: string, directory: boolean) => Promise<void>, lockWaitMs?: number}} [options]
+   */
+  constructor(options = {}) {
+    this.platform = options.platform ?? process.platform;
+    this.homeDir = options.homeDir ?? os.homedir();
+    this.profile = options.profile ?? "prod";
+    // Environment variables select OS storage locations only, never credentials
+    // or the API/provider configuration bound to those credentials.
+    this.file = sessionPath(options.env ?? process.env, this.platform, this.homeDir, this.profile);
+    this.config = options.config;
+    this.oauth = options.oauth;
+    this.now = options.now ?? Date.now;
+    this.files = new SessionFiles(this.file, {
+      platform: this.platform, fs: options.fs,
+      protectPath: options.protectPath, lockWaitMs: options.lockWaitMs,
+    });
+  }
+
+  /** A successful interactive sign-in replaces even an uncertain refresh record. @param {Credentials} credentials */
+  async save(credentials) {
+    const session = this.#record(credentials);
+    await this.files.withLock(async () => { await this.files.write(session); });
+  }
+
+  /** Inspect the local snapshot only: no refresh, network request, lock or write.
+   * @returns {Promise<SessionStatus>}
+   */
+  async status() {
+    let config;
+    /** @type {SessionStatus} */
+    const result = { profile: this.profile, apiUrl: null, issuer: null, clientId: null, state: "signed_out", localOnly: true };
+    try {
+      config = this.#config();
+      result.apiUrl = config.apiUrl;
+      result.issuer = config.issuer;
+      result.clientId = config.clientId;
+    } catch (error) {
+      if (!(error instanceof CliError) || error.code !== "OAUTH_CONFIG_INVALID") throw error;
+      try { result.apiUrl = getApiUrl(this.profile); } catch { /* Partial configuration may lack an API URL too. */ }
+    }
+    let session;
+    try { session = checkedSession(await this.files.read()); }
+    catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      if (error.code === "NOT_SIGNED_IN") return result;
+      if (error.code === "INVALID_SESSION") return { ...result, state: "invalid" };
+      throw error;
+    }
+    if (!config) return { ...result, state: "configuration_error" };
+    if (!matchesConfig(session, config)) return { ...result, state: "config_mismatch" };
+    return {
+      ...result,
+      state: session.refreshState === "in_progress" ? "refresh_uncertain" : session.expiresAt <= this.now() ? "expired" : "valid",
+      expiresAt: session.expiresAt,
+      scopes: [...session.scopes],
+    };
+  }
+
+  /** Remove only this profile's local credential; never revoke provider tokens. */
+  async signout() {
+    return { profile: this.profile, removed: await this.files.remove() };
+  }
+
+  async loadToken() {
+    const initial = await this.#read();
+    if (initial.refreshState === "ready" && initial.expiresAt > this.now() + REFRESH_WINDOW_MS) return initial.accessToken;
+
+    return this.files.withLock(async () => {
+      // Another CLI process may have refreshed while this one waited.
+      const session = await this.#read();
+      this.#assertReady(session);
+      if (session.expiresAt > this.now() + REFRESH_WINDOW_MS) return session.accessToken;
+
+      // Persist before dispatch: a crash/lost response must not resend a
+      // potentially rotated refresh token. Preserve the original credential.
+      await this.files.write({ ...session, refreshState: "in_progress" });
+      let refreshed;
+      try {
+        const oauth = this.oauth ?? new OAuthClient({ config: this.#config() });
+        refreshed = await oauth.refresh(session.refreshToken);
+      } catch (error) {
+        const code = error instanceof CliError ? error.code : undefined;
+        if (code === "OAUTH_REJECTED" || code === "NETWORK_ERROR"
+          || code === "OAUTH_INVALID_RESPONSE" || code === "OAUTH_CONFIG_INVALID") {
+          // OAuthClient guarantees these are definitive rejections or failures
+          // during discovery, before refresh dispatch.
+          await this.files.write(session);
+          throw new CliError("Could not refresh the RequestShield session. Retry the command.", {
+            code: "SESSION_REFRESH_FAILED", exitCode: 7,
+          });
+        }
+        throw signinRequired();
+      }
+
+      // A validation/write failure retains the marker and original credentials.
+      const replacement = this.#record(refreshed);
+      await this.files.write(replacement);
+      return replacement.accessToken;
+    });
+  }
+
+  #config() { return this.config ?? getOAuthConfig(this.profile); }
+
+  /** @param {Credentials} value @returns {SavedSession} */
+  #record(value) {
+    const credentials = checkedCredentials(value);
+    if (credentials.expiresAt <= this.now()) throw invalidSession();
+    return { version: 1, ...this.#config(), ...credentials, refreshState: "ready" };
+  }
+
+  /** @returns {Promise<SavedSession>} */
+  async #read() {
+    const record = checkedSession(await this.files.read());
+    const config = this.#config();
+    if (!matchesConfig(record, config)) throw invalidSession();
+    return record;
+  }
+
+  /** @param {SavedSession} session */
+  #assertReady(session) {
+    if (session.refreshState !== "ready") throw signinRequired();
+  }
+}
+
+/** @param {SavedSession} session @param {OAuthConfig} config */
+function matchesConfig(session, config) {
+  return session.issuer === config.issuer && session.clientId === config.clientId && session.apiUrl === config.apiUrl;
+}
+
+/** @param {unknown} value @returns {SavedSession} */
+function checkedSession(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidSession();
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.version !== 1 || typeof record.issuer !== "string" || typeof record.clientId !== "string" || typeof record.apiUrl !== "string"
+    || (record.refreshState !== "ready" && record.refreshState !== "in_progress")) throw invalidSession();
+  const allowed = new Set(["version", "issuer", "clientId", "apiUrl", "refreshState",
+    "accessToken", "refreshToken", "expiresAt", "scopes"]);
+  if (Object.keys(record).some(key => !allowed.has(key))) throw invalidSession();
+  return { version: 1, issuer: record.issuer, clientId: record.clientId, apiUrl: record.apiUrl,
+    ...checkedCredentials(record), refreshState: record.refreshState };
+}
+
+/** @param {unknown} value @returns {Credentials} */
+function checkedCredentials(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidSession();
+  const record = /** @type {Record<string, unknown>} */ (value);
+  try { validateBearerToken(record.accessToken); } catch { throw invalidSession(); }
+  if (typeof record.refreshToken !== "string" || record.refreshToken.length > 16_384
+    || !/^[\x21-\x7e]+$/.test(record.refreshToken)
+    || typeof record.expiresAt !== "number" || !Number.isSafeInteger(record.expiresAt) || record.expiresAt <= 0
+    || !Array.isArray(record.scopes) || record.scopes.length === 0 || record.scopes.length > 64
+    || record.scopes.some(scope => typeof scope !== "string" || !/^[\x21\x23-\x5b\x5d-\x7e]{1,256}$/.test(scope))
+    || new Set(record.scopes).size !== record.scopes.length) throw invalidSession();
+  return {
+    accessToken: /** @type {string} */ (record.accessToken), refreshToken: record.refreshToken,
+    expiresAt: record.expiresAt, scopes: [...record.scopes],
+  };
+}
+
+function invalidSession() {
+  return new CliError("The saved RequestShield session is no longer usable. Run `requestshield login` again.", {
+    code: "INVALID_SESSION", exitCode: 3,
+  });
+}
+function signinRequired() {
+  return new CliError("The RequestShield session could not be safely refreshed. Run `requestshield login` again.", {
+    code: "SESSION_SIGNIN_REQUIRED", exitCode: 3,
+  });
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {NodeJS.Platform} platform @param {string} homeDir @param {import("./config.mjs").Profile} [profile] */
+export function sessionPath(env, platform, homeDir, profile = "prod") {
+  if (!["prod", "qat", "stg"].includes(profile)) {
+    throw new CliError("This RequestShield installation is invalid. Reinstall the CLI or contact support.", { code: "INVALID_PROFILE", exitCode: 2 });
+  }
+  const suffix = profile === "prod" ? ["session.json"] : [profile, "session.json"];
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA || path.join(homeDir, "AppData", "Local"), "IntelliFend", "RequestShield", ...suffix);
+  }
+  const base = env.XDG_STATE_HOME || path.join(homeDir, ".local", "state");
+  return path.join(base, "intellifend", "requestshield", ...suffix);
+}

package/src/terminal.mjs

@@ -0,0 +1,143 @@
+// @ts-check
+import { stripVTControlCharacters } from "node:util";
+
+/** @typedef {{isTTY?: boolean, columns?: number, term?: string, noColor?: boolean}} TerminalCapabilities */
+/** @typedef {{stdout?: TerminalCapabilities, stderr?: TerminalCapabilities}} TerminalContext */
+/** @typedef {{terminal?: TerminalContext}} TerminalOutput */
+
+const segmenter = new Intl.Segmenter(undefined, {granularity: "grapheme"});
+const colors = {bold: 1, cyan: 36, muted: 90, success: 32, warning: 33, error: 31, info: 36};
+
+/** Measure terminal cells, not UTF-16 units; styles and combining marks occupy no cells.
+ * @param {string} value */
+export function displayWidth(value) {
+  let width = 0;
+  for (const {segment} of segmenter.segment(stripVTControlCharacters(value))) {
+    if (/^[\p{Mark}\p{Cf}]+$/u.test(segment)) continue;
+    const point = segment.codePointAt(0) ?? 0;
+    const emoji = /\p{Emoji_Presentation}|\uFE0F|\u20E3/u.test(segment);
+    const wide = point >= 0x1100 && (point <= 0x115f || point === 0x2329 || point === 0x232a
+      || point >= 0x2e80 && point <= 0xa4cf && point !== 0x303f
+      || point >= 0xac00 && point <= 0xd7a3 || point >= 0xf900 && point <= 0xfaff
+      || point >= 0xfe10 && point <= 0xfe19 || point >= 0xfe30 && point <= 0xfe6f
+      || point >= 0xff00 && point <= 0xff60 || point >= 0xffe0 && point <= 0xffe6
+      || point >= 0x20000 && point <= 0x3fffd);
+    width += emoji || wide ? 2 : 1;
+  }
+  return width;
+}
+
+/** Wrap prose at word boundaries. Never split copyable keys, URLs or secret values.
+ * @param {string} value @param {number} columns @returns {string[]} */
+function wrap(value, columns) {
+  return value.split("\n").flatMap(line => {
+    const words = line.trim().match(/`[^`\n]+`|\S+/gu) ?? [];
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+      if (current && displayWidth(`${current} ${word}`) > columns) {
+        lines.push(current);
+        current = word;
+      } else current += `${current ? " " : ""}${word}`;
+    }
+    lines.push(current);
+    return lines;
+  });
+}
+
+/** Pure presentation: callers explicitly provide capabilities; no product config is read.
+ * @param {TerminalCapabilities} [capabilities] */
+export function createRenderer(capabilities = {}) {
+  const columns = Number.isFinite(capabilities.columns) && Number(capabilities.columns) > 0
+    ? Math.max(20, Math.floor(Number(capabilities.columns))) : 80;
+  const decorated = capabilities.isTTY === true && capabilities.term !== "dumb" && !capabilities.noColor;
+  /** @param {keyof typeof colors} color @param {string} value */
+  const paint = (color, value) => decorated ? `\x1b[${colors[color]}m${value}\x1b[0m` : value;
+  /** @param {string} value @param {number} width */
+  const pad = (value, width) => value + " ".repeat(Math.max(0, width - displayWidth(value)));
+  /** @param {string} value */
+  const status = value => {
+    if (["enabled", "installed", "valid", "locally valid", "up_to_date"].includes(value)) return paint("success", value);
+    if (["pending", "accepted", "expired", "missing", "attention_required", "refresh_uncertain"].includes(value)) return paint("warning", value);
+    if (["revoked", "invalid", "config_mismatch", "configuration_error"].includes(value)) return paint("error", value);
+    return value;
+  };
+  /** @param {Array<[string, string]>} entries */
+  const fields = entries => {
+    const labelWidth = Math.max(0, ...entries.map(([label]) => displayWidth(label) + 1));
+    return entries.map(([label, value]) => {
+      const rendered = /^(status|session \(local\))$/i.test(label) ? status(value) : value;
+      // Values remain byte-for-byte intact, including spaces in names and paths.
+      if (labelWidth + displayWidth(value) + 4 > columns) return `  ${paint("muted", `${label}:`)}\n    ${rendered}`;
+      return `  ${paint("muted", pad(`${label}:`, labelWidth))}  ${rendered}`;
+    }).join("\n");
+  };
+  return {
+    columns,
+    /** @param {string} text @param {string} [icon] */
+    heading: (text, icon) => paint("bold", `${decorated && icon ? `${icon} ` : ""}${text}`),
+    /** @param {string} text */
+    section: text => paint("bold", text.toUpperCase()),
+    /** @param {string} text */
+    command: text => paint("cyan", text),
+    /** @param {string} text */
+    muted: text => paint("muted", text),
+    /** @param {string} text */
+    paragraph: text => wrap(text, columns).join("\n"),
+    /** @param {Array<{label: string, description: string, icon?: string}>} entries
+     * @param {{labelWidth?: number}} [layout] */
+    rows: (entries, layout = {}) => {
+      const labelWidth = Math.max(layout.labelWidth ?? 0, ...entries.map(entry => displayWidth(entry.label)));
+      const descriptionColumn = labelWidth + 4;
+      const stacked = columns - descriptionColumn < 24;
+      return entries.map(({label, description, icon}) => {
+        const prefix = decorated && icon ? `${icon} ` : "";
+        const indent = stacked ? 4 : descriptionColumn;
+        const lines = wrap(`${prefix}${description}`, columns - indent);
+        if (stacked) return `  ${paint("cyan", label)}\n${lines.map(line => `    ${line}`).join("\n")}`;
+        return `  ${paint("cyan", pad(label, labelWidth))}  ${lines[0]}`
+          + lines.slice(1).map(line => `\n${" ".repeat(indent)}${line}`).join("");
+      }).join("\n");
+    },
+    fields,
+    status,
+    /** @param {'success'|'warning'|'error'|'info'} kind @param {string} text */
+    message: (kind, text) => {
+      const labels = {success: "Success:", warning: "Warning:", error: "Error:", info: "Info:"};
+      const symbols = {success: "✓", warning: "⚠", error: "✖", info: "ℹ"};
+      return paint(kind, wrap(`${decorated ? symbols[kind] : labels[kind]} ${text}`, columns).join("\n"));
+    },
+    /** @param {string[]} headers @param {string[][]} rows */
+    table: (headers, rows) => {
+      const widths = headers.map((header, index) => Math.max(displayWidth(header), ...rows.map(row => displayWidth(row[index] ?? ""))));
+      if (widths.reduce((sum, width) => sum + width, 2 + 2 * (headers.length - 1)) > columns) {
+        return rows.map(row => fields(headers.map((header, index) => [header, row[index] ?? ""]))).join("\n\n");
+      }
+      const header = `  ${headers.map((value, index) => paint("bold", index === headers.length - 1 ? value : pad(value, widths[index]))).join("  ")}`;
+      const body = rows.map(row => `  ${headers.map((name, index) => {
+        const value = row[index] ?? "";
+        const formatted = name.toLowerCase() === "status" ? status(value) : value;
+        return index === headers.length - 1 ? formatted : pad(formatted, widths[index]);
+      }).join("  ")}`);
+      return [header, ...body].join("\n");
+    },
+  };
+}
+
+/** @param {TerminalOutput} deps @param {'stdout'|'stderr'} [stream] */
+export function rendererFor(deps, stream = "stdout") {
+  return createRenderer(deps.terminal?.[stream]);
+}
+
+/** Only terminal presentation uses TERM/NO_COLOR; these never select product settings.
+ * Injected output callbacks default to plain text unless capabilities are supplied.
+ * @param {TerminalOutput & {log?: (message: string) => void, warn?: (message: string) => void, env?: NodeJS.ProcessEnv}} deps
+ * @returns {TerminalContext} */
+export function resolveTerminal(deps) {
+  if (deps.terminal) return deps.terminal;
+  const env = deps.env ?? process.env;
+  /** @param {{isTTY?: boolean, columns?: number}} stream @param {boolean} injected */
+  const detect = (stream, injected) => ({isTTY: !injected && stream.isTTY === true, columns: stream.columns,
+    term: env.TERM, noColor: env.NO_COLOR !== undefined});
+  return {stdout: detect(process.stdout, !!deps.log), stderr: detect(process.stderr, !!deps.warn)};
+}

package/src/usage-time.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+
+/** Strict UTC timestamps, with seconds and optional millisecond precision.
+ * Date.parse alone accepts calendar rollovers such as February 30.
+ * @param {unknown} value @returns {number | undefined}
+ */
+export function utcTimestamp(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value)) return undefined;
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) return undefined;
+  const normalized = value.replace(/(?:\.(\d{1,3}))?Z$/, (_match, fraction = "") => `.${fraction.padEnd(3, "0")}Z`);
+  return new Date(time).toISOString() === normalized ? time : undefined;
+}
+
+/** Validate syntax and ordering only; the server owns the current retention window.
+ * @param {{from?: string, to?: string}} options
+ */
+export function validateUsageRange({from, to}) {
+  if (from === undefined && to === undefined) return {};
+  const start = utcTimestamp(from), end = utcTimestamp(to);
+  if (start === undefined || end === undefined || start >= end) {
+    throw new CliError("Provide both --from and --to as valid UTC timestamps ending in Z, with --from before --to (at most three fractional digits).", {code: "INVALID_ARGUMENT", exitCode: 2});
+  }
+  return {from: /** @type {string} */ (from), to: /** @type {string} */ (to)};
+}