[Bug] Windows Codex PATH can crash HTTPS updates with OPENSSL_Applink

[joey-orbyss]

Spec Kit version

specify 1.0.4, installed as a uv tool on Windows.

Environment

• Codex Desktop local task on Windows
• The task PATH prepends Codex-owned native dependency directories, including Poppler and Git directories that contain their own libssl-3-x64.dll and libcrypto-3-x64.dll.
• specify.exe is the uv-installed launcher under %USERPROFILE%\.local\bin.

Reproduction

From an initialized consumer with registered HTTPS catalogs, run either:

specify workflow update program-kit-bootstrap
specify bundle update program-kit --integration codex

Both commands reproducibly exit 1 before completing the remote update with:

OPENSSL_Uplink(...): no OPENSSL_Applink

The failure occurs specifically in the Codex Desktop process environment. A local/offline component installation can proceed because it does not enter the failing HTTPS path.

Expected behavior

Spec Kit HTTPS/catalog operations should use the OpenSSL runtime packaged with its Python environment and must not load an ABI-incompatible DLL merely because another application prepended native tools to PATH. If the launcher cannot isolate its DLL search path, it should fail with an actionable dependency diagnostic rather than the OpenSSL applink abort.

Impact

Documented workflow update and bundle update commands cannot run from Codex Desktop on affected Windows hosts. This blocks unattended governed upgrades and encourages consumers to use incomplete local recovery sequences.

[github-actions]

Bug assessment — windows-openssl-applink: Likely valid, needs reproduction · severity medium

---

Bug Assessment: Windows Codex PATH can crash HTTPS updates with OPENSSL_Applink

• Slug: windows-openssl-applink
• Created: 2026-09-04T13:34:20Z
• Source: issue [Bug] Windows Codex PATH can crash HTTPS updates with OPENSSL_Applink #4433
• Verdict: likely valid, needs reproduction
• Severity: medium

Report (summarized)

The reporter uses specify 1.0.4 installed as a uv tool on Windows, from a Codex Desktop local task. Codex prepends native dependency directories to PATH, including Poppler and Git directories containing their own libssl-3-x64.dll and libcrypto-3-x64.dll.

With registered HTTPS catalogs, both specify workflow update program-kit-bootstrap and specify bundle update program-kit --integration codex exit 1 before completing the remote update and emit OPENSSL_Uplink(...): no OPENSSL_Applink. Offline/local component installation can proceed because it does not enter the affected HTTPS path. No additional linked context or comments were provided.

Symptom

On affected Windows hosts launched from Codex Desktop, HTTPS catalog access for workflow and bundle updates fails with an OpenSSL applink error instead of using the SSL runtime associated with Spec Kit's Python environment. The expected behavior is for remote updates to work independently of unrelated native DLLs earlier on PATH, or to fail with an actionable dependency diagnostic rather than a native OpenSSL abort.

Reproduction

1. On Windows, install specify 1.0.4 as a uv tool and run it from a Codex Desktop local task.
2. Use a consumer project with registered HTTPS workflow/bundle catalogs. [NEEDS CLARIFICATION: the exact catalog registration commands/configuration and catalog URLs are not included in the report.]
3. Run either specify workflow update program-kit-bootstrap or specify bundle update program-kit --integration codex.
4. Observe exit code 1 and OPENSSL_Uplink(...): no OPENSSL_Applink before the remote update completes.

[NEEDS CLARIFICATION: the exact Windows version, Python/uv version, uv tool environment path, and the first conflicting DLL actually loaded were not reported.]

Suspected Code Paths

• src/specify_cli/workflows/_commands.py:2659-2712 — workflow_update resolves installed workflows through WorkflowCatalog.get_workflow_info; catalog errors are rendered and terminate the command.
• src/specify_cli/workflows/catalog.py:505-589 — workflow catalog fetching calls specify_cli.authentication.http.open_url for HTTPS sources. It relies on the process's Python/urllib SSL runtime and has no Windows DLL-directory initialization or conflict diagnostic.
• src/specify_cli/commands/bundle/__init__.py:442-480 — bundle_update builds the catalog stack and resolves each bundle before downloading its manifest.
• src/specify_cli/bundler/services/adapters.py:114-163,170-204 — bundle catalog fetching routes HTTPS requests through authentication.http.open_url, with no Windows-specific DLL isolation.
• src/specify_cli/authentication/http.py:164-223 — open_url creates isolated urllib.request openers, but the opener isolation is for redirect/auth behavior; it does not isolate native DLL resolution or select an explicit SSL context.
• pyproject.toml:7-16 — the package declares Python-level dependencies but no native OpenSSL runtime or Windows DLL-loading policy. The uv-installed Python distribution therefore supplies the effective SSL implementation.

Root Cause Hypothesis

The report is consistent with a Windows native-library resolution conflict: a DLL with the same OpenSSL library name as the one expected by Python's _ssl extension may be selected from a Codex-prepended PATH directory, producing an ABI/runtime mismatch and the OPENSSL_Applink failure. The two commands share the authenticated urllib transport, which explains the common failure, while offline/local paths avoid SSL entirely. Confidence: medium. The repository clearly lacks explicit Windows DLL search-path handling, but the precise loaded module and whether the native failure aborts before Python can wrap it require reproduction on the affected host.

Proposed Remediation

Preferred: Add a single Windows runtime bootstrap at CLI startup, before any HTTPS/SSL use, that establishes the intended Python environment's native DLL directory using the supported Windows DLL-directory mechanism (and keeps the handle alive for the process lifetime). Centralize this behavior rather than adding separate workarounds to workflow and bundle catalog code. The bootstrap should be narrowly scoped to the interpreter/package runtime, avoid trusting arbitrary PATH entries, and emit a clear diagnostic containing the Python/uv environment and expected runtime locations if setup cannot be completed. Confirm that the launcher/package layout used by uv tools exposes the required DLL directory across supported Python versions.

The transport should continue to use the existing authenticated open_url path. Explicitly initializing the SSL runtime before the first request is preferable to replacing urllib with another HTTP library, because both affected commands already converge on this transport and changing libraries would not by itself guarantee correct native DLL selection.

Alternatives (optional):

• Adjust the Windows launcher to sanitize or reorder the child process PATH before starting Python. This may be effective, but it is more invasive, can break legitimate user tools, and does not help callers embedding/importing the CLI.
• Add a documented clean-environment fallback or actionable preflight check that detects conflicting loaded OpenSSL modules and instructs users to launch outside Codex Desktop. This is lower risk but leaves the affected integration broken and should be a temporary mitigation, not the primary fix.

Files likely to change:

• src/specify_cli/__init__.py or a new stdlib-only Windows runtime helper imported during CLI startup
• src/specify_cli/authentication/http.py only if the bootstrap needs to be tied to transport initialization
• tests/test_github_http.py and/or a dedicated Windows runtime test module
• Packaging/launcher documentation or configuration if the runtime DLL location must be made explicit

Tests to add or update:

• A Windows test that starts a subprocess with controlled conflicting native-library directories ahead of PATH and verifies an HTTPS request uses the Spec Kit/Python runtime without the applink failure.
• A test that invokes both workflow and bundle catalog fetch seams against a mocked HTTPS response and verifies they share the initialized transport.
• A failure-path test proving an unavailable or ambiguous runtime produces an actionable diagnostic and nonzero exit rather than an unhandled native error.
• Preserve existing redirect, authentication, offline, and catalog-cache tests; the change must not weaken their URL or credential policies.

Risks & Considerations

• Windows DLL search behavior varies by Python version, embeddable/uv installation layout, and whether a conflicting module has already been loaded; initialization must occur before SSL is imported or loaded.
• Holding os.add_dll_directory handles for the process lifetime is necessary on supported Windows Python versions; premature cleanup can reintroduce the problem.
• PATH sanitization can regress unrelated subprocesses and should not be used as the only fix.
• A native-library diagnostic must report paths and versions without exposing tokens or other credentials.
• The current workflow fetcher falls back to stale cache on fetch exceptions, while the bundle fetcher wraps the error; behavior should remain explicit and must not silently treat a failed remote update as successful.

Open Questions

• [NEEDS CLARIFICATION: Which Windows version, Python version, and uv version are present in the failing Codex Desktop process?]
• [NEEDS CLARIFICATION: Which exact libssl-3-x64.dll/libcrypto-3-x64.dll paths are loaded at failure time, and which paths belong to the uv Python environment?]
• [NEEDS CLARIFICATION: Does the process terminate inside the native OpenSSL call, or does Python catch and wrap the underlying exception before exit?]
• [NEEDS CLARIFICATION: Are the workflow and bundle catalogs configured with the same HTTPS host, or do both failures occur against different catalog hosts?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4433 · 126 AIC · ⌖ 11.1 AIC · ⊞ 28.3K · ◷