opencode-codex-security 0.1.1 → 0.1.2

package/docs/PUBLISHING.md

@@ -1,44 +1,58 @@
 # npm staging and human approval
 
-The source is public under Apache 2.0. Version `0.1.0` is live on npm under `latest`, verified November 10, 2026. The manifest retains `private: false`, public registry/access settings, a conservative `contentPolicy.class: dual-use` declaration and a root `DISCLOSURE`. Version `0.1.1` is prepared for staging; a version bump alone does not stage or publish it. GitHub previews remain available independently.
+`opencode-codex-security` is public on npm under Apache 2.0. Bootstrap is complete, and the GitHub OIDC staging workflow has been exercised successfully. Every release still needs a maintainer's separate review and npm 2FA approval before it is installable. Workflow success means **staged**, not approved or published.
 
-## Security boundaries
+Verified November 10, 2026: `latest` points to `0.1.0`; `0.1.1` is also public under `next`, with npm provenance. Check the registry again before choosing an installation or release version:
 
-This utility uses Codex Security for source scans, policy drafting and static finding validation, not exploit execution or patch application. Its dual-use metadata and disclosure must persist across versions. npm forbids direct OIDC publication for dual-use packages. This repository automates **staging only**; each live version requires a maintainer's review and npm 2FA approval. Never add a direct publish command or a token fallback.
+```sh
+npm view opencode-codex-security dist-tags versions --json
+```
 
-`Checks` builds and tests without publishing permissions. It installs locked dependencies with lifecycle scripts disabled, audits runtime dependencies, checks source/build freshness and package allowlists, and tests the exact tarball in an isolated OpenCode host. Consumer dependencies are resolved afresh and audited too. The package has no install, prepare, pack or publish lifecycle hooks. Build explicitly before packing. These checks are not a comprehensive secret scan or a guarantee that transitive dependencies are safe.
+For installation, use [the README](../README.md#install-a-released-version) or [agent setup](https://github.com/strantalis/opencode-codex-security/blob/main/docs/AGENT-SETUP.md). Consumers do not need npm login, trusted-publisher settings or these release tools. GitHub previews remain available independently through [the preview release guide](RELEASING.md).
+
+## Stage the next release
 
-`npm-stage.yml` is manual, main-only and bound in code to `strantalis/opencode-codex-security`. It requires a successful current-main push run from `ci.yml` in the same repository. It requires the tested source commit to match both current main and the staging workflow commit (`GITHUB_SHA`, recorded by npm provenance). It checks public visibility, fixed filenames, dual-use manifest, SHA-256 checksums and artifact count. It promotes those exact bytes without rebuilding. The GitHub-hosted staging job has only read access and `id-token: write`, runs pinned Node/npm tooling, and never checks out or executes project code or installs project dependencies. The action is pinned to a commit. There are no npm secrets. The workflow verifies bundled npm 11.20.0 in Node 26.13.0 and fails if tooling differs.
+1. Choose a version not already live or awaiting approval. Bump `version` in both package and lockfile in a reviewed PR. Use a new patch for fixes or a full prerelease such as `0.1.2-rc.1` for testing. Preserve `contentPolicy.class: dual-use`, the license and `DISCLOSURE`.
+2. Merge only after required checks and review pass. Wait for **Checks on the new main push** to succeed. Its tested artifact is retained for 14 days. A PR run is not a substitute.
+3. Run **Actions → Stage npm release** (`npm-stage.yml`) on main with that push run's numeric ID. Choose `next` for testing/prereleases or deliberately choose `latest` for a stable release. The default is `next`; prereleases with `latest` fail closed. Both tags refer to public packages once approved.
+4. Save the returned stage ID and review it as described below. **Do not approve in CI.** The workflow has no approval job and cannot complete human 2FA.
 
-## One-time bootstrap: separate maintainer action
+The workflow requires the tested commit to be both current main and the workflow commit. If main moves before staging, use the successful Checks push run for the new main. If a version is already live, choose a new version instead of rerunning it. No version can be overwritten after publication.
 
-Bootstrap is already complete for `opencode-codex-security`; use the later-version flow below for updates. The following steps document first-time setup only. Do not run them for another package until the maintainer approves the exact npm destination, public contents and account. Confirm name availability/ownership again. Review current npm policy, archive contents, license/dependency obligations and account eligibility. npm trust requires an **existing package**; do not try to grant trust to a nonexistent package.
+## Review and approve a staged version
 
-Use a workstation with Node 26.13.0/npm 11.20.0 (staging needs npm 11.15.0+). Enable npm 2FA. Download all three assets from a successful current-main CI run or matching GitHub preview, inspect `build-manifest.json` and verify `SHA256SUMS` before continuing. Use the actual archive filename:
+This is a separate maintainer action using an authorized npm account with 2FA. Use tooling supporting staged publishing (npm 11.15.0+); the workflow pins Node 26.13.0 and its bundled npm 11.20.0. Use the official interactive `npm login` only if sign-in is needed. Never paste or commit passwords, tokens or OTPs.
+
+Inspect the specific stage, then download its payload into a fresh review directory:
 
 ```sh
-# macOS; Linux: sha256sum -c SHA256SUMS
-shasum -a 256 -c SHA256SUMS
-npm login
-npm whoami
-npm stage publish ./opencode-codex-security-0.1.0.tgz --access public --tag latest --ignore-scripts
 npm stage list opencode-codex-security
 npm stage view STAGE_ID
+npm stage download STAGE_ID
 ```
 
-Login and bootstrap staging are separate maintainer actions, not effects of changing repository files. A 401 from `npm whoami` means the CLI is not authenticated, not that no account exists. Do not share or commit passwords, tokens or OTPs. **Staging a new name creates a public `0.0.0-stage` placeholder**, even before the first real version is approved. The staged payload itself is not a live published version. Review the stage, download and compare its tarball with the tested SHA-256, and approve only the intended version/tag. Human approval is a separate action:
+Check the package name, version, intended public tag, repository, source commit and provenance. Obtain the corresponding tested CI artifact's `build-manifest.json` and `SHA256SUMS` from the run used for staging. Verify its assets (`shasum -a 256 -c SHA256SUMS` on macOS, `sha256sum -c SHA256SUMS` on Linux), then compare the **downloaded stage tarball's** SHA-256 against `archiveSha256` in that manifest. Checksums alone do not establish trust in an untrusted manifest. Review the actual archive contents and release changes before approval.
+
+When the intended version, tag and bytes are confirmed, the maintainer performs the 2FA approval:
 
 ```sh
-npm stage download STAGE_ID
-# Compare the downloaded tarball's SHA-256 with build-manifest.json.
 npm stage approve STAGE_ID
 ```
 
-Approval requires 2FA and publishes that staged version. `npm stage reject STAGE_ID` also requires 2FA and discards it. Inspect any interrupted/uncertain operation with list/view before retrying; never blindly create another stage. Tags are immutable within a stage. Reject and restage if the tag was wrong. Check `npm view opencode-codex-security@0.1.0 version dist.integrity` and the intended dist-tag after approval. Do not treat a workflow success, stage ID or placeholder as a live release.
+Approval publishes that exact version and applies its selected tag. To discard a stage, use `npm stage reject STAGE_ID`, also requiring 2FA. Tags are immutable within a stage: reject and restage if the selected tag was wrong. Do not try to change trust or use a token to avoid approval.
+
+After approval, verify the specific version and intended tag in the public registry, replacing `VERSION` with the approved full version:
 
-## Configure stage-only trusted publishing: separate approval
+```sh
+npm view opencode-codex-security@VERSION version dist.integrity dist.attestations --json
+npm view opencode-codex-security dist-tags --json
+```
 
-After the package exists, the maintainer must explicitly authorize and configure persistent npm trust for exactly:
+Check provenance as well as the source/bytes in the build manifest. A stage ID, successful workflow or `0.0.0-stage` placeholder is not a release. An interrupted submission or approval can have an uncertain outcome: inspect stage list/view **and public registry state** before retrying. Do not blindly create another stage or assume a failed client response means nothing happened.
+
+## Existing trust and security boundaries
+
+The workflow uses the following publisher identity. The npm trust grant should permit staging only:
 
 - Provider: GitHub Actions.
 - Owner: `strantalis`.
@@ -47,25 +61,22 @@ After the package exists, the maintainer must explicitly authorize and configure
 - Permission: **stage only**, never direct publishing.
 - Environment: none (this workflow does not claim an environment).
 
-Use npm package settings or the current `npm trust` documentation, not invented CLI flags. Do not configure a broader repository/workflow or create a long-lived token as a workaround. Newly configured trust must be used within two days or it expires. Once the staged flow is verified, select npm package protection **Require two-factor authentication and disallow tokens**. These settings require separate approval and are not made by this repository change.
+The successful OIDC staging run confirms staging access for this workflow; it does not prove the full trust grant or account-wide token/2FA protection settings. Routine releases reuse the existing binding; do not repeat package bootstrap or recreate trust. If npm rejects the workflow because trust is absent, expired or mismatched, stop and have the maintainer review the exact settings using [npm's trusted-publisher documentation](https://docs.npmjs.com/trusted-publishers/). Persistent trust, package protection or account changes require separate authorization. Do not broaden the binding, disable 2FA or create a long-lived token as a workaround.
 
-## Stage a later version
+This utility uses Codex Security for source scans, policy drafting and static finding validation, not exploit execution or patch application. Its dual-use metadata and disclosure must persist. npm forbids direct OIDC publication for dual-use packages. This workflow uses OIDC for **staging only**; OIDC authentication does not grant human approval. Never add a direct publish command or a token fallback.
 
-1. Bump `version` in both package and lockfile in a reviewed PR. Use a patch bump for fixes (`0.1.1`); use a prerelease such as `0.1.1-rc.1` with `next` for testing. Never reuse a live version. Keep the dual-use metadata and disclosure.
-2. Merge only after checks pass. Wait for **Checks on the new main push** to finish successfully. Its verified artifact is retained for 14 days.
-3. Run **Actions → Stage npm release** on main with that run's numeric ID. Choose `next` for prereleases/testing or deliberately choose `latest` for a stable release. The default is `next`; prereleases with `latest` fail closed.
-4. Review the returned stage ID, version, tag, source and tarball hash using the human steps above. Approve with 2FA only when ready for public installation. There is no automated approval job.
+`Checks` builds and tests without publishing permissions. It installs locked dependencies with lifecycle scripts disabled, audits runtime dependencies, checks source/build freshness and package allowlists, and tests the exact tarball in an isolated OpenCode host. Consumer dependencies are resolved afresh and audited too. The package has no install, prepare, pack or publish lifecycle hooks. Build explicitly before packing. These checks are not a comprehensive secret scan or a guarantee that transitive dependencies are safe.
 
-If main moves, the artifact expires, trust is absent/expired, or registry permissions fail, fix the specific prerequisite and use a fresh current-main successful run. Do not weaken checks or fall back to tokens. A failure after submitting to npm can have an uncertain outcome: inspect stage list/view before retrying. A version cannot be overwritten after publication; use a new version for corrections.
+`npm-stage.yml` is manual, main-only and bound in code to this repository. It verifies a successful current-main push run from `ci.yml`, public visibility, fixed filenames, dual-use manifest, SHA-256 checksums and artifact count. It promotes those exact bytes without rebuilding. The tested source commit must match `GITHUB_SHA`, recorded by npm provenance. The GitHub-hosted staging job has read permissions plus `id-token: write`, uses a commit-pinned setup action and verifies its pinned Node/npm tooling. It never checks out or executes project code or installs project dependencies. There are no npm secrets.
 
 ## Limits and references
 
-Provenance is requested for public source/package with matching repository metadata. Review provenance after promotion: it identifies the staging workflow, while `build-manifest.json` links the bytes to the independently verified build commit/run. Native Desktop/platform testing and a complete real SDK assessment remain separate from mocked CI. Use only repositories and workplace devices authorized for scanning and data transfer.
+Provenance identifies the staging workflow; `build-manifest.json` links the bytes to the independently tested build commit/run. Native Desktop/platform testing and a complete real SDK assessment remain separate from mocked CI. Use only repositories and workplace devices authorized for scanning and data transfer.
 
 - [npm stage CLI](https://docs.npmjs.com/cli/v11/commands/npm-stage/)
-- [npm staged publishing and bootstrap](https://docs.npmjs.com/staged-publishing/)
+- [npm staged publishing](https://docs.npmjs.com/staged-publishing/)
 - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/)
 - [npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/)
 - [npm dual-use policy](https://docs.npmjs.com/policies/dual-use/)
 
-Verified November 10, 2026; recheck before setup. Installed metadata identifies Codex Security 0.9.1 as Apache-2.0, OpenCode plugin/Solid as MIT, and OpenTUI native binaries as MIT AND LGPL-2.1-or-later. Dependencies stay external; this is not comprehensive legal clearance.
+Verified November 10, 2026; recheck before release. Installed metadata identifies Codex Security 0.9.1 as Apache-2.0, OpenCode plugin/Solid as MIT, and OpenTUI native binaries as MIT AND LGPL-2.1-or-later. Dependencies stay external; this is not comprehensive legal clearance.

package/docs/RELEASING.md

@@ -1,8 +1,8 @@
-# Tested builds and open-source release readiness
+# Tested builds and GitHub previews
 
 ## Build and promote a tested preview
 
-Repository visibility is an explicit maintainer choice. The manifest is public-release-ready, but GitHub previews do not stage or publish to npm. No npm account, package registry token or new persistent credential is required for the preview pipeline. The separate [npm staging guide](PUBLISHING.md) describes explicit bootstrap/trust setup and human approval.
+Repository visibility is an explicit maintainer choice. This repository is public, but GitHub previews do not stage or publish to npm. No npm account, package registry token or new persistent credential is required for the preview pipeline. The separate [npm staging guide](PUBLISHING.md) describes the ongoing stage-only release flow and human approval. Package bootstrap is already complete.
 
 Every push and pull request runs locked installation with lifecycle scripts disabled, runtime dependency audit, lint, formatting, types, unit tests, build freshness, package allowlist and offline OpenCode integration. CI packs once, installs and tests that exact tarball, audits its newly resolved consumer dependencies, then saves `package-<full-commit>` for 14 days. The artifact contains the `.tgz`, `build-manifest.json` and `SHA256SUMS`. A PR artifact identifies its tested synthetic merge commit; prefer a push artifact when pinning a branch.
 
@@ -31,7 +31,7 @@ gh release download preview-COMMIT_PREFIX --repo strantalis/opencode-codex-secur
 shasum -a 256 -c SHA256SUMS
 # Linux: sha256sum -c SHA256SUMS
 cat build-manifest.json
-npm install --prefix ./consumer --ignore-scripts --no-audit --no-fund ./opencode-codex-security-0.1.1.tgz
+npm install --prefix ./consumer --ignore-scripts --no-audit --no-fund ./opencode-codex-security-0.1.2.tgz
 ```
 
 The tarball version follows the package manifest; the release tag, full source commit and hash uniquely identify each build. Use the archive filename actually listed in `build-manifest.json`, which may differ from the example above. A GitHub preview does not make that version live on npm. Set your OpenCode plugin's `package` to the absolute path of `consumer/node_modules/opencode-codex-security` while preserving unrelated configuration. Select `engine: fixture` for offline testing or your explicitly configured SDK mode. Keep each preview in a separate directory; switch/reload only after active scans, approval dialogs and policy forms finish. Keep the previous directory to roll back. Nothing auto-updates the watched installation.
@@ -44,7 +44,7 @@ Develop in a separate checkout/worktree, push fixes, inspect that commit's CI, m
 
 ## npm distribution
 
-Public GitHub distribution under Apache 2.0 is approved. Version `0.1.0` is live on npm. The separate manual `npm-stage.yml` workflow stages later tested artifacts using maintainer-configured stage-only trust. No account, npm package or persistent trust is created by adding that workflow. Every live npm version still requires human 2FA approval. See [publishing and operating the staging flow](PUBLISHING.md).
+Public GitHub distribution under Apache 2.0 is approved. Verified November 10, 2026: npm `latest` is `0.1.0`, and `0.1.1` is public under `next`. The separate manual `npm-stage.yml` workflow uses maintainer-configured trust to stage later tested artifacts; it never approves them. Bootstrap and the OIDC staging flow are established; routine releases reuse the existing trust binding. Every live npm version still requires human 2FA approval. See [publishing and operating the staging flow](PUBLISHING.md).
 
 Keep development fixes in separate worktrees and PRs; do not overwrite the watched local installation. For npm fixes, bump the patch version and lockfile together. For prerelease testing use a full prerelease version with `next`; use `latest` only deliberately for stable releases. Pin the full installed version, keep the prior consumer for rollback and reload only after active operations finish.
 

package/docs/SDK.md

@@ -1,16 +1,16 @@
 # Codex Security SDK integration
 
-Pinned SDK: `@openai/codex-security@0.9.1`; OpenCode/plugin: 2.2.6.
+Pinned SDK: `@openai/codex-security@0.9.1`; plugin API package: `@opencode/plugin@2.2.6`. OpenCode 2.2.6 is the original host-test baseline, not an exact-patch requirement.
 
 Current global configuration is documented in [GLOBAL-CONFIG.md](GLOBAL-CONFIG.md). No per-project SDK overrides are loaded. Session-supplied target/focus/context is distinct from global model, reasoning and Daybreak settings. Optional per-scan Standard/Deep mode overrides only the global mode fallback; no other SDK settings are overridden by session inputs.
 
 ## Pipeline
 
-1. `security_prepare_scan` or the native review action resolves the current OpenCode location (or explicit repository), canonical scope paths, focused instructions and bounded documentation files. It reads and hashes the global settings file. No SDK client, login or inference is created.
-2. Preview includes target, added context, model/reasoning, Daybreak/access program and estimated cost threshold. The whole conversation is not copied.
+1. `security_prepare_scan` or the native review action resolves the current OpenCode location (or explicit repository), canonical scope paths, focused instructions and bounded documentation files. It reads and hashes the global settings file and, when explicitly configured, imports an allowlisted custom-provider selection from a Codex TOML file. `codex.useCodexConfig: true` defaults to `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when that variable is unset/empty. An explicit `codex.configFile` wins without consulting `CODEX_HOME`; no import occurs by default. Only validated selection fields, not raw TOML or secret values, enter the source digest. No SDK client, login or inference is created.
+2. Preview includes target, added context, provider/base URL, auth mode, environment-key name, model/reasoning, source selection, Daybreak/access program and estimated cost threshold. The whole conversation is not copied.
 3. `security_run_scan` checks native OpenCode permissions. Applicable saved authorization can allow it without a redundant prompt. Native UI uses an explicit review action. Missing/mismatched/reused previews fail closed.
-4. Before starting, the plugin revalidates target/context and global config fingerprints. A change or expired preview requires a new review.
-5. The adapter creates an SDK client with the global model, reasoning and Daybreak constructor overrides and the fixed OpenAI provider. It invokes `run(repository, options)` with scope, prompt, documentation paths, configured scan settings, fixed ChatGPT auth and disabled owner suggestions.
+4. Before starting, the plugin revalidates target/context and global config, resolved source-file location and selected-provider fingerprints. A change or expired preview requires a new review.
+5. The adapter creates an SDK client from the resolved model, reasoning, Daybreak and provider snapshot. Default routing uses OpenAI plus dedicated ChatGPT auth. An explicit custom Responses provider uses `auth: "api-key"` and its selected environment key. It invokes `run(repository, options)` with scope, prompt, documentation paths, configured scan settings and disabled owner suggestions. Policy generation and validation use the same resolved route; validation separately requires uncapped approval.
 6. Progress and sanitized lifecycle events update the panel. Findings arrive at completion. Informational findings are counted but not relabeled in the four-severity display. Local SDK artifacts remain authoritative.
 
 ## Safety and authorization boundaries
@@ -23,13 +23,25 @@ Current global configuration is documented in [GLOBAL-CONFIG.md](GLOBAL-CONFIG.m
 - Models and account entitlement are not checked while loading settings. Daybreak is a separate toggle, not a model; the toggle does not grant access.
 - Cost limits use estimates, not a hard billing cap. In-flight work can exceed the threshold.
 
-## Dedicated authentication
+## Custom-provider authentication
 
-Real operations require an existing private, owned, nonsymlink dedicated auth file and directory. A metadata-only guard runs before constructing the real SDK client. It does not read tokens, perform login or import credentials. The injected mock clients bypass this real-auth precondition.
+Provider routing is an upcoming source-version `0.1.2` feature. Published `0.1.0`/`0.1.1` packages do not expose it.
 
-The SDK uses `$CODEX_SECURITY_STATE_DIR/codex-home`, otherwise `$CODEX_HOME/state/plugins/codex-security/codex-home`, with `~/.codex` as the default Codex home. Keep this outside the target repository.
+See [the no-sign-in setup](GLOBAL-CONFIG.md#use-an-existing-codexlitellm-provider-without-sign-in). Custom-provider readiness validates the non-secret routing and checks only the selected environment key's presence before SDK construction. It does not consult `account()`, log in, read `auth.json`, or import ambient credentials. The SDK's custom `env_key` path skips ambient-auth import; explicit API-key mode avoids stored-auth fallback. The plugin passes a snapshot, never the original SDK profile or unrelated settings.
 
-SDK 0.9.1 can import ambient credentials when its dedicated home is empty. The guard prevents ordinary missing-auth startup, but is not an atomic no-import policy: external deletion after the check can still race. Windows is deliberately rejected until a safe ACL verification path exists.
+Custom-provider Daybreak, auth commands, inline tokens, custom headers and catalogs are deliberately unsupported. Unknown model aliases can fail SDK cost estimation; the scan/policy limit is retained rather than bypassed. Known model estimates are not verified gateway billing rates. Gateways may route onward to upstream services, and Responses compatibility does not prove the required tool support. Mock tests do not establish real gateway compatibility.
+
+## Default dedicated ChatGPT authentication
+
+The default ChatGPT route requires an existing private, owned, nonsymlink dedicated auth file and directory. A metadata-only guard runs before constructing the real SDK client. It does not read tokens, perform login or import credentials. The injected mock clients bypass this real-auth precondition.
+
+The SDK uses `$CODEX_SECURITY_STATE_DIR/codex-home`, otherwise `$CODEX_HOME/state/plugins/codex-security/codex-home`, with `~/.codex` as the default Codex home. Keep this outside the target and enclosing repositories. The login command and OpenCode process must use the same environment.
+
+Only users choosing this default ChatGPT route should use its sign-in flow. If dedicated sign-in is absent, they can choose to complete the installed official CLI flow from the consumer directory: `./node_modules/.bin/codex-security login`. This creates a separate session through interactive sign-in, not a plugin startup action. Never ask for secrets in chat, read/copy private token files or import an ambient Codex sign-in to satisfy this guard. Do not run SDK `login status` or account helpers before dedicated credentials exist: they can import ambient credentials. These sign-in instructions are not needed for an explicitly selected custom-provider environment-key route.
+
+The guard requires a private dedicated `auth.json`; keyring-only authentication is insufficient. Do not automatically change credential storage, managed-device policy or permissions to make it pass. Report the incompatibility and use the official supported account setup. See [agent setup](https://github.com/strantalis/opencode-codex-security/blob/main/docs/AGENT-SETUP.md) for the complete installation prompt.
+
+SDK 0.9.1 can import ambient credentials when its dedicated home is empty. The guard prevents ordinary missing-auth startup, but is not an atomic no-import policy: external deletion after the check can still race. The ChatGPT guard deliberately rejects Windows until a safe ACL verification path exists. Custom-provider key checks are platform-neutral, but this project has not verified a complete Windows SDK operation.
 
 ## Verified behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-security",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -31,6 +31,7 @@
   "dependencies": {
     "@openai/codex-security": "0.9.1",
     "@opencode/plugin": "2.2.6",
+    "smol-toml": "1.9.1",
     "solid-js": "^1.9.0"
   },
   "devDependencies": {

package/src/core/codex-adapter.ts

@@ -9,7 +9,8 @@ import {
 } from './run-telemetry.ts';
 import { summarizeScanResult } from './result-summary.ts';
 import {
-  requireDedicatedSecurityCredentials,
+  requireSdkCredentials,
+  ProviderCredentialsRequiredError,
   DedicatedSecurityCredentialsRequiredError,
 } from './credential-guard.ts';
 import { safeFinding } from './report-safety.ts';
@@ -22,7 +23,8 @@ import type {
   ScanResult,
   Finding as SdkFinding,
 } from '@openai/codex-security';
-import type { ResolvedSdkSettings } from './sdk-settings.ts';
+import { sdkConfiguration, type ResolvedSdkSettings } from './sdk-settings.ts';
+import { ProviderConfigurationError } from './provider-config.ts';
 import type { Finding, ScanState } from '../types.js';
 
 /** Per-run consent, never persisted. The caller must obtain this from the user. */
@@ -42,9 +44,9 @@ export type SecurityFactory = (
   config?: CodexSecurityConfig,
 ) => SecurityClient | Promise<SecurityClient>;
 const realClient: SecurityFactory = async (config) => {
-  await requireDedicatedSecurityCredentials();
+  await requireSdkCredentials(config);
   const { CodexSecurity } = await import('@openai/codex-security');
-  return new CodexSecurity(config ?? { codexOverrides: { model_provider: 'openai' } });
+  return new CodexSecurity(config ?? sdkConfiguration());
 };
 function initial(repository: string, revision = 0, instanceId = ''): ScanState {
   return {
@@ -121,6 +123,14 @@ export function scanBudgetFailure(
   };
 }
 
+export function unsupportedPricingMessage(error: unknown): string | undefined {
+  if (
+    error instanceof Error &&
+    error.message.startsWith('A scan cost limit is not available for the configured model:')
+  )
+    return 'The SDK cannot estimate costs for this model or gateway alias, so the operation stopped without removing its cost limit. Use a gateway model with SDK-supported pricing, or ask the gateway administrator about a compatible route. Estimates are not gateway billing totals or hard caps.';
+}
+
 /** Local coordinator; SDK inference is network-backed, not an offline scanner. */
 export class CodexScanService {
   readonly root: string;
@@ -198,18 +208,15 @@ export class CodexScanService {
     let terminalPhase = 'Codex Security scan failed';
     try {
       signal.throwIfAborted();
-      client = await this.#factory({
-        codexOverrides: {
-          model_provider: 'openai',
-          ...(approval.settings
-            ? {
-                model: approval.settings.codex.model,
-                model_reasoning_effort: approval.settings.codex.reasoningEffort,
-                daybreak: approval.settings.codex.daybreak,
-              }
-            : {}),
-        },
-      });
+      if (
+        approval.settings?.codex.provider &&
+        approval.auth &&
+        approval.auth !== approval.settings.codex.auth
+      )
+        throw new ProviderConfigurationError(
+          'Approved authentication does not match the selected provider.',
+        );
+      client = await this.#factory(sdkConfiguration(approval.settings));
       signal.throwIfAborted();
       const telemetry = (this.#state.telemetry ??= emptyTelemetry());
       const options: ScanOptions = {
@@ -218,7 +225,7 @@ export class CodexScanService {
         knowledgeBasePaths: [...(approval.contextFiles ?? [])],
         ...approval.settings?.scan,
         mode: approval.settings?.scan.mode ?? 'standard',
-        auth: approval.auth ?? 'chatgpt',
+        auth: approval.settings?.codex.auth ?? approval.auth ?? 'chatgpt',
         maxCostUsd: approval.maxCostUsd,
         ownerSuggestions: false,
         signal,
@@ -380,9 +387,12 @@ export class CodexScanService {
       this.#state.error = signal.aborted
         ? null
         : (budget?.message ??
-          (error instanceof DedicatedSecurityCredentialsRequiredError
+          (error instanceof DedicatedSecurityCredentialsRequiredError ||
+          error instanceof ProviderCredentialsRequiredError ||
+          error instanceof ProviderConfigurationError
             ? error.message
-            : 'SDK scan failed. Check authentication, runtime prerequisites, and local SDK diagnostics.'));
+            : (unsupportedPricingMessage(error) ??
+              'SDK scan failed. Check authentication, runtime prerequisites, and local SDK diagnostics.')));
       terminalMessage = signal.aborted
         ? 'Cancellation requested; SDK run stopped. Partial results are not a completed scan.'
         : this.#state.error!;

package/src/core/credential-guard.ts

@@ -81,3 +81,50 @@ export async function requireDedicatedSecurityCredentials(
     throw new DedicatedSecurityCredentialsRequiredError();
   }
 }
+
+/** A fixed message, safe to expose without leaking credential values or SDK diagnostics. */
+export class ProviderCredentialsRequiredError extends Error {
+  constructor() {
+    super(
+      'The selected provider environment key is missing or blank. Make the configured envKey available to the OpenCode process before retrying. No sign-in or credential import was attempted.',
+    );
+    this.name = 'ProviderCredentialsRequiredError';
+  }
+}
+
+/** The only API-key readiness check: validate routing, then check the named key's presence. */
+export async function requireSdkCredentials(
+  config: import('@openai/codex-security').CodexSecurityConfig | undefined,
+  environment: Environment = process.env,
+): Promise<void> {
+  const routing = config?.codexOverrides;
+  const id = routing?.model_provider;
+  if (id === undefined || id === 'openai') return requireDedicatedSecurityCredentials(environment);
+  const { validateProvider, record, ProviderConfigurationError } =
+    await import('./provider-config.ts');
+  const providers = routing?.model_providers;
+  const native = typeof id === 'string' && record(providers) ? providers[id] : undefined;
+  if (
+    !record(native) ||
+    native.requires_openai_auth !== false ||
+    Object.keys(native).some(
+      (key) => !['name', 'base_url', 'env_key', 'wire_api', 'requires_openai_auth'].includes(key),
+    )
+  )
+    throw new ProviderConfigurationError(
+      'Invalid API-key provider routing. No authentication was initialized.',
+    );
+  const provider = validateProvider({
+    id,
+    baseUrl: native.base_url,
+    envKey: native.env_key,
+    wireApi: native.wire_api,
+  });
+  // Exact environment-variable selection on POSIX, case-insensitive on Windows.
+  // Never enumerate or copy environment values, return a key, or inspect auth.json.
+  const name =
+    process.platform === 'win32'
+      ? Object.keys(environment).find((key) => key.toUpperCase() === provider.envKey.toUpperCase())
+      : provider.envKey;
+  if (!name || !environment[name]?.trim()) throw new ProviderCredentialsRequiredError();
+}

package/src/core/planned-scan.ts

@@ -271,12 +271,43 @@ export class PlannedScanService {
         void this.#save(entry.state).catch(() => {});
       }
     });
+    try {
+      await validatePlan(plan);
+    } catch {
+      entry.state = {
+        ...entry.state,
+        status: this.#disposed || entry.cancelledBeforeStart ? 'cancelled' : 'error',
+        phase:
+          this.#disposed || entry.cancelledBeforeStart
+            ? 'Cancelled before execution'
+            : 'Preview invalid; prepare again',
+        error:
+          this.#disposed || entry.cancelledBeforeStart
+            ? null
+            : 'Target, context, or provider settings changed after approval. Prepare and review a new scan.',
+        finishedAt: new Date().toISOString(),
+      };
+      await this.#save(entry.state).catch(() => {});
+      this.#emit(entry.state);
+      return structuredClone(entry.state);
+    }
+    if (this.#disposed || entry.cancelledBeforeStart) {
+      entry.state = {
+        ...entry.state,
+        status: 'cancelled',
+        phase: 'Cancelled before execution',
+        finishedAt: new Date().toISOString(),
+      };
+      await this.#save(entry.state).catch(() => {});
+      this.#emit(entry.state);
+      return structuredClone(entry.state);
+    }
     service.start({
       approved: true,
       repository: plan.repository,
       allowNetworkModelInference: true,
       maxCostUsd: plan.settings.scan.maxCostUsd,
-      auth: 'chatgpt',
+      auth: plan.settings.codex.auth,
       settings: plan.settings,
       scopePaths: [...plan.scopePaths],
       scanPrompt: plan.scanPrompt,