[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 · ◷

[mnriem]

Thanks — this is an unusually clear report. To pinpoint whether DLL-search-path isolation on our side would fix it, could you help narrow it: (1) does the same command succeed from a plain PowerShell (i.e. not launched by Codex Desktop), or with the Poppler/Git directories removed from PATH? (2) which OpenSSL DLL resolves first — e.g. where.exe libssl-3-x64.dll and where.exe libcrypto-3-x64.dll in the failing environment? That'll confirm the ABI-incompatible-DLL-on-PATH root cause and tell us whether pinning the DLL search dir to Spec Kit's Python env resolves it. In the meantime we'll look at making the HTTPS path fail with an actionable dependency diagnostic instead of the raw applink abort.

[Yi-111-a]

Adding Windows data points on @mnriem's two questions, from a Windows 11 (10.0.26200) host. I could not reproduce the failure by PATH manipulation alone, and the evidence I collected points away from the PATH-precedence explanation. Negative result and details below.

Setup

• Git for Windows 2.53.0.windows.2 — ships C:\Program Files\Git\mingw64\bin\libssl-3-x64.dll (1,026,716 bytes) and libcrypto-3-x64.dll (5,796,508 bytes). A second, separate pair lives at C:\Program Files\Git\usr\bin (msys-ssl-3.dll / msys-crypto-3.dll), so there are two distinct OpenSSL builds inside the same Git install.
• specify 1.0.6, installed via uv tool install → launcher at %USERPROFILE%\.local\bin\specify.exe. That directory contains no OpenSSL DLLs, matching the layout described in the report.
• Python 3.14.6, ssl.OPENSSL_VERSION == OpenSSL 3.5.7 9 Jun 2026.

Results

#	PATH condition	specify self check	direct HTTPS
A	clean	Up to date: 1.0.6	https://api.github.com → 200
B	Git\mingw64\bin prepended as first entry	Up to date: 1.0.6	→ 200
C	Git\usr\bin before mingw64\bin	—	git ls-remote https://github.com/github/spec-kit.git OK
D	Git\mingw64\bin before usr\bin	—	git ls-remote ... OK

No OPENSSL_Uplink / no OPENSSL_Applink output in any of the four.

Which DLL actually gets loaded

This is measured, not inferred — I resolved the loaded module paths from inside the process (GetModuleHandleW + GetModuleFileNameW, plus a full EnumProcessModules sweep). Identical in A and B, i.e. with Git's directory first on PATH:

libssl-3-x64.dll     -> ...\uv\python\cpython-3.14-windows-x86_64-none\DLLs\libssl-3-x64.dll
libcrypto-3-x64.dll  -> ...\uv\python\cpython-3.14-windows-x86_64-none\DLLs\libcrypto-3-x64.dll
_ssl.pyd             -> ...\uv\python\cpython-3.14-windows-x86_64-none\DLLs\_ssl.pyd

Git's copy is never loaded. The full module sweep listed only those three ssl/crypto modules in the process.

Why PATH ordering can't be the mechanism

Since Python 3.8 this is by design — bpo-36085 (GH-12302). From the 3.8 porting notes:

DLL dependencies for extension modules and DLLs loaded with ctypes on Windows are now resolved more securely. Only the system paths, the directory containing the DLL or PYD file, and directories added with os.add_dll_directory are searched for load-time dependencies. Specifically, PATH and the current working directory are no longer used, and modifications to these will no longer have any effect on normal DLL resolution.

CPython calls SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_DEFAULT_DIRS) at startup, so _ssl.pyd resolves its OpenSSL only from its own directory plus the system paths. A Poppler/Git directory prepended to PATH cannot reach it.

Two supporting checks:

• No other dependency in the tree is a native extension that links OpenSSL (typer, click, rich, platformdirs, readchar, pyyaml, packaging, pathspec, json5 are all pure Python), so there is no second candidate for an applink abort inside the interpreter.
• grep -rni "openssl\|add_dll_directory\|libssl\|applink" src/ scripts/ returns no matches — the project performs no DLL-search manipulation at all today.

Where that leaves it

I can't answer Q1 as literally asked, because I don't have Codex Desktop and can't reproduce its environment. So I can't rule out that it does something beyond prepending PATH. But PATH precedence alone is insufficient on this host, and if the working hypothesis is "the wrong libssl wins", then something other than PATH ordering has to be responsible.

Two things would pin it down:

1. Which process actually printed the message. If it came from a child process (git, or anything else specify shells out to) rather than from specify's own interpreter, then the fix is not in the HTTPS path at all. The full surrounding shell output — not just the one line — would settle this.
2. Whether it reproduces on 1.0.6. This was reported against 1.0.4; a re-run on current main would confirm it still stands.

One consequence worth noting up front: OPENSSL_Uplink(...): no OPENSSL_Applink is a C-level abort(), so Python try/except cannot intercept it. If we want an actionable diagnostic instead of the raw abort, it most likely has to be a startup pre-check or subprocess isolation, not error handling in the HTTPS path.

A smaller, independent ask

specify version prints CLI version / Python / Platform / Architecture / OS Version, but not the OpenSSL runtime in use. For a report like this, ssl.OPENSSL_VERSION is probably the single most useful diagnostic line, and it's cheap to add — so I have a focused PR with a test ready (specify version gains an OpenSSL row), rather than bundling it into this issue.

One thing I deliberately left out of that PR: the resolved path of the loaded libssl-3-x64.dll. It needs process-module enumeration, and it only becomes meaningful once we know a PATH-preceded DLL can actually be loaded — which is the part that's still open above. Adding it now would bake in an assumption that my own measurements don't support.

---

AI assistance was used to run these experiments and draft this comment, per the disclosure requirement in CONTRIBUTING.md. The commands above were run on my own Windows machine and the outputs are pasted unedited.

[mnriem]

Thanks @Yi-111-a —the measured module paths and negative reproduction help narrow this. My earlier suggestion that PATH ordering would establish the cause was premature; where.exe cannot show which DLL the failing process actually loaded.

@joey-orbyss, please retry the original command on the current release inside Codex Desktop and from plain PowerShell. Please include the Spec Kit/Python/uv versions, minimal catalog setup, and full surrounding output with credentials redacted. If it still fails, we need to identify whether the message comes from Specify’s interpreter or a child process, and which OpenSSL modules that process loaded.

The diagnostic improvement in #4556 is separate; this issue remains open pending reproduction in the affected environment.

Drafted for @mnriem with assistance from GitHub Copilot (model: GPT-6 Astra; interactive comment drafting).