Merge branch 'main' into mdangelo/codex/codex-security-stable-npm-release-20260724

Author: mldangelo-oai

sdk/typescript/README.md

@@ -269,6 +269,12 @@ Python interpreter. The preflight result includes the selected authentication
 method and, for an environment API key, its variable name. Authentication and
 model access remain unverified until a real scan starts.
 
+Scan progress identifies the selected credential source before Codex starts.
+Interactive terminals also show how to retry with ChatGPT when an environment
+API key overrides the stored sign-in. Progress remains on stderr so JSON output
+stays machine readable. Recoverable failures include safe retry causes and,
+when available, the server-provided retry delay.
+
 ## Documentation and security
 
 - [CLI quickstart](https://developers.openai.com/codex/security/cli)

sdk/typescript/src/api.ts

@@ -120,8 +120,13 @@ export interface ScanOptions {
   failureSeverity?: SeverityLevel;
   onOutputArchived?: (archiveDir: string) => void;
   onOutputDirReady?: (scanDir: string) => void;
+  onAuthentication?: (authentication: ScanAuthentication) => void;
   onScanStarted?: () => void;
-  onReconnect?: (attempt: number, maxAttempts: number) => void;
+  onReconnect?: (
+    attempt: number,
+    maxAttempts: number,
+    details?: ScanReconnectDetails,
+  ) => void;
   onWorkerStatus?: (status: ScanWorkerStatus) => void;
   onObserverError?: (observer: ScanObserverName, error: unknown) => void;
   signal?: AbortSignal;
@@ -138,7 +143,13 @@ export type ScanAuthentication =
       verified: false;
     };
 
+export interface ScanReconnectDetails {
+  reason: "rate_limit" | "network" | "authentication" | "authorization";
+  retryAfterSeconds?: number;
+}
+
 type ScanObserverName =
+  | "onAuthentication"
   | "onOutputArchived"
   | "onOutputDirReady"
   | "onScanStarted"
@@ -353,6 +364,12 @@ export class CodexSecurity {
             "OPENAI_API_KEY or CODEX_API_KEY for CI.",
         );
       }
+      notifyObserver(
+        "onAuthentication",
+        options.onAuthentication,
+        options.onObserverError,
+        scanAuthentication(this.#dependencies.environment),
+      );
       const python = await (
         this.#dependencies.resolvePluginPython ?? resolvePluginPython
       )({
@@ -940,7 +957,11 @@ interface ScanEventRunOptions {
   expectation: ScanExpectation;
   onFinalize?: () => Promise<void>;
   onScanStarted?: () => void;
-  onReconnect?: (attempt: number, maxAttempts: number) => void;
+  onReconnect?: (
+    attempt: number,
+    maxAttempts: number,
+    details?: ScanReconnectDetails,
+  ) => void;
   onWorkerStatus?: (status: ScanWorkerStatus) => void;
   onObserverError?: (observer: ScanObserverName, error: unknown) => void;
 }
@@ -1005,6 +1026,7 @@ export async function runScanEvents(
           options.onReconnect,
           options.onObserverError,
           ...reconnect,
+          reconnectDetails(message),
         );
       }
     }
@@ -1264,6 +1286,71 @@ function reconnectAttempt(message: string): [number, number] | null {
   return attempt <= maxAttempts ? [attempt, maxAttempts] : null;
 }
 
+function reconnectDetails(message: string): ScanReconnectDetails | undefined {
+  const classification = classifyConnectionFailure(message);
+  if (classification !== "rate_limited") {
+    if (classification === "network_error") return { reason: "network" };
+    if (classification === "unauthorized") return { reason: "authentication" };
+    if (classification === "forbidden") return { reason: "authorization" };
+    return undefined;
+  }
+  const delay =
+    /\b(?:try again|retry)\s+in\s+(\d{1,6}(?:\.\d{1,3})?)\s*(?:s\b|seconds?\b)/iu.exec(
+      message,
+    );
+  const retryAfterSeconds = delay === null ? NaN : Number(delay[1]);
+  return {
+    reason: "rate_limit",
+    ...(Number.isFinite(retryAfterSeconds) &&
+    retryAfterSeconds > 0 &&
+    retryAfterSeconds <= 3_600
+      ? { retryAfterSeconds }
+      : {}),
+  };
+}
+
+export function classifyConnectionFailure(
+  error: unknown,
+):
+  | "rate_limited"
+  | "unauthorized"
+  | "forbidden"
+  | "network_error"
+  | "timeout"
+  | "unknown" {
+  const message = error instanceof Error ? error.message : String(error);
+  if (
+    /\brate[_ -]?limit(?:ed|[_ -]exceeded)?\b|\b429\b|\btoo many requests\b/iu.test(
+      message,
+    )
+  ) {
+    return "rate_limited";
+  }
+  if (
+    /\b401\b|\bunauthori[sz]ed\b|\binvalid[_ -](?:api[_ -]?key|authentication|token|credentials?)\b|\b(?:expired|revoked)[_ -](?:api[_ -]?key|token|credentials?)\b|\b(?:api[_ -]?key|token|credentials?)(?: has)? (?:expired|been revoked)\b/iu.test(
+      message,
+    )
+  ) {
+    return "unauthorized";
+  }
+  if (
+    /\b403\b|\bforbidden\b|\bpermission denied\b|\b(?:model|organization|project) access\b|\b(?:access denied|do not have access|not authorized|insufficient permissions)\b|\bmodel[_ -]?not[_ -]?found\b/iu.test(
+      message,
+    )
+  ) {
+    return "forbidden";
+  }
+  if (
+    /\b(?:ENOTFOUND|ECONNRESET|ECONNREFUSED|EHOSTUNREACH|ETIMEDOUT)\b|\b(?:network|connection|TLS|DNS)\b|\berror sending request\b/iu.test(
+      message,
+    )
+  ) {
+    return "network_error";
+  }
+  if (/\b(?:timed? out|timeout)\b/iu.test(message)) return "timeout";
+  return "unknown";
+}
+
 export function scanRuntimeCodexConfig(config: JsonObject): JsonObject {
   const hardened = structuredClone(config);
   delete hardened["sandbox_mode"];

sdk/typescript/src/cli.ts

@@ -28,6 +28,7 @@ import { pathToFileURL } from "node:url";
 import { Cli, z } from "incur";
 import { parse as parseToml } from "smol-toml";
 import {
+  classifyConnectionFailure,
   CodexSecurity,
   scanAuthentication,
   type ScanOptions,
@@ -1976,15 +1977,45 @@ async function runScan(
       onOutputDirReady: (path) => {
         scanDir = path;
       },
+      onAuthentication: (authentication) => {
+        progress?.stopTimer();
+        if (authentication.method === "api_key") {
+          progress?.stage(
+            `Authentication: API key from ${authentication.source}.`,
+          );
+          if (errorOutput.isTTY === true) {
+            progress?.stage(
+              process.platform === "win32"
+                ? "To use a ChatGPT sign-in, unset OPENAI_API_KEY and CODEX_API_KEY, then retry the scan."
+                : "Retry with ChatGPT: env -u OPENAI_API_KEY -u CODEX_API_KEY codex-security scan ...",
+            );
+          }
+        } else {
+          progress?.stage("Authentication: stored Codex credentials.");
+        }
+        progress?.startTimer("Preparing scan");
+      },
       onScanStarted: () => {
         progress?.stopTimer();
         progress?.startTimer(runningMessage());
       },
-      onReconnect: (attempt, maxAttempts) => {
+      onReconnect: (attempt, maxAttempts, details) => {
         progress?.stopTimer();
-        progress?.stage(
-          `Codex connection interrupted; retrying (${attempt}/${maxAttempts})`,
-        );
+        const message =
+          details?.reason === "rate_limit"
+            ? `Rate limit reached; retrying${
+                details.retryAfterSeconds === undefined
+                  ? ""
+                  : ` in ${details.retryAfterSeconds}s`
+              } (${attempt}/${maxAttempts}).`
+            : details?.reason === "network"
+              ? `Network connection interrupted; retrying (${attempt}/${maxAttempts}).`
+              : details?.reason === "authentication"
+                ? `Authentication interrupted; retrying (${attempt}/${maxAttempts}).`
+                : details?.reason === "authorization"
+                  ? `Model access interrupted; retrying (${attempt}/${maxAttempts}).`
+                  : `Codex connection interrupted; retrying (${attempt}/${maxAttempts})`;
+        progress?.stage(message);
         progress?.startTimer(runningMessage());
       },
       onWorkerStatus: (status) => {
@@ -2044,7 +2075,7 @@ async function runScan(
     const message =
       failure instanceof OutputInsideProtectedRootError
         ? cliErrorMessage(protectedRootErrorMessage(failure))
-        : cliErrorMessage(failure);
+        : scanFailureMessage(failure);
     if (failure instanceof OutputInsideProtectedRootError) {
       errorOutput.write(`${message}\n`);
     } else {
@@ -2094,6 +2125,23 @@ async function runScan(
   return { exitCode: blockingCount > 0 ? 1 : 0, data: result.toJSON() };
 }
 
+function scanFailureMessage(error: unknown): string {
+  switch (classifyConnectionFailure(error)) {
+    case "unauthorized":
+      return "Authentication failed. Sign in again or provide a valid API key.";
+    case "forbidden":
+      return "The selected credentials cannot access the configured model. Use an account or API key with model access.";
+    case "rate_limited":
+      return "The configured account reached its rate limit. Wait and retry.";
+    case "network_error":
+      return "The model service could not be reached. Check your network connection and try again.";
+    case "timeout":
+      return "The connection timed out. Check your network connection and try again.";
+    case "unknown":
+      return cliErrorMessage(error);
+  }
+}
+
 function scanScope(arguments_: ScanArguments): string | null {
   if (arguments_.paths.length > 0) {
     const displayed = arguments_.paths.slice(0, 3).map((path) => {

sdk/typescript/src/index.ts

@@ -4,6 +4,7 @@ export type {
   ScanAuthentication,
   ScanOptions,
   ScanPreflight,
+  ScanReconnectDetails,
 } from "./api.js";
 export type { ScanWorkerPhase, ScanWorkerStatus } from "./worker-progress.js";
 export { CodexLoginHandle } from "./auth.js";