[FEATURE] Cross-protocol fallback with custom port: port mismatch across SSH/HTTPS

[edenfunf]

Problem

When --allow-protocol-fallback is enabled and a dependency has a custom port, _build_repo_url passes the same dep_ref.port to both build_ssh_url and build_https_clone_url. For servers where SSH and HTTPS run on different ports, the cross-protocol fallback produces an incorrect URL.

Concrete scenario: Bitbucket Datacenter

Bitbucket DC defaults: SSH on port 7999, HTTPS on port 7990.

- ssh://git@bitbucket.corp.com:7999/project/repo.git

Attempt	URL produced	Result
SSH	ssh://git@bitbucket.corp.com:7999/project/repo.git	Correct
HTTPS fallback	https://bitbucket.corp.com:7999/project/repo.git	Wrong — HTTPS is on 7990, not 7999

Other affected scenarios

Setup	SSH attempt	HTTPS fallback	Result
GitLab (SSH:2222, HTTPS:443)	ssh://host:2222/... ✅	https://host:2222/... ❌	Hits SSH daemon
Same-port server (e.g. Gitea:3000)	✅	✅	Works by accident

Current mitigations

Strict mode (default since #778) prevents this from manifesting for explicit ssh:// and https:// URLs — only the declared protocol is attempted. The bug only surfaces when users explicitly opt in via --allow-protocol-fallback or APM_ALLOW_PROTOCOL_FALLBACK=1.

The test test_https_attempt_preserves_same_port_across_protocols (test_auth_scoping.py:423) codifies "same port across protocols" as intended behavior — which is correct for same-port servers but wrong for the Bitbucket DC scenario.

Root cause

DependencyReference has a single port: Optional[int] field shared across all protocols. There is no ssh_port / https_port distinction. TransportAttempt and TransportSelector have no port awareness — port handling lives entirely in _build_repo_url which blindly passes dep_ref.port to whichever builder it calls.

Design space

The fundamental issue: when crossing protocols, we cannot guess the correct port for the other protocol.

Option A: Warn + multi-port fallback cascade

When dep_ref.port is set and cross-protocol fallback triggers:

1. Try with same port (covers same-port servers)
2. If that fails, try with default port (covers servers where the other protocol uses default port)
3. Emit a warning: "Custom port {port} was specified for {scheme}://; the fallback protocol may use a different port."

Pro: no schema change. Con: doesn't cover BB DC (HTTPS:7990 is neither 7999 nor 443).

Option B: fallback field in object form

- git: ssh://git@bitbucket.corp.com:7999/project/repo.git
  fallback: https://bitbucket.corp.com:7990/project/repo.git
  ref: v1.0

Pro: fully explicit, covers any URL difference (not just port — also path differences for ADO, proxies, etc.). Con: schema expansion.

Option C: Per-protocol port fields in object form

- git: bitbucket.corp.com/project/repo
  ssh_port: 7999
  https_port: 7990

Pro: explicit. Con: only addresses port, not other URL differences; requires host field to be meaningful; less general than Option B.

Option D: Status quo + documentation

Strict mode already prevents the problem for explicit URLs. Document that --allow-protocol-fallback with custom ports may produce incorrect fallback URLs, and recommend pinning the protocol that matches the port.

Pro: zero code change. Con: doesn't help users who genuinely need fallback across different ports.

Files involved

• src/apm_cli/deps/github_downloader.py — _build_repo_url (line 664), _clone_with_fallback
• src/apm_cli/deps/transport_selection.py — TransportSelector.select, TransportAttempt (no port awareness)
• src/apm_cli/utils/github_host.py — build_ssh_url, build_https_clone_url
• src/apm_cli/models/dependency/reference.py — single port field

Context

Follow-up from PR #665 review. The "same port across protocols" behavior was a deliberate choice in #665 to fail loudly rather than silently hitting a different service. Strict-by-default transport (#778) subsequently removed most of the exposure. This issue tracks the residual gap for the --allow-protocol-fallback path.

Refs: #661, #665, #731, #778

[edenfunf]

@danielmeppiel Follow-up from the #665 review discussion and the strict-by-default transport work in #778. Looking for your direction on the design tradeoffs before doing anything here.

The strict default already eliminates the problem for explicit URLs — if you write ssh://host:7999/..., only SSH is attempted. The bug only surfaces with --allow-protocol-fallback, where the HTTPS fallback blindly reuses the SSH port (e.g. Bitbucket DC: SSH on 7999, HTTPS on 7990 → https://host:7999/... hits the wrong service).

I laid out four options in the issue. My honest assessment:

• Option A (warn + multi-port cascade) is cheap but doesn't actually solve the BB DC case — 7990 is neither 7999 nor the default 443.
• Option B (fallback: URL field on object form) is the most general — it handles any URL difference across protocols, not just port. But it's a schema expansion.
• Option C (ssh_port / https_port fields) solves ports specifically but is less general than B.
• Option D (status quo + docs) is honest: strict mode already covers the default path, and --allow-protocol-fallback inherently carries a "you know what you're doing" semantic.

Given that strict mode already prevents this for 99%+ of users, I'm leaning toward D for now (document the limitation clearly) and revisit B if users report hitting this in practice. But if you'd prefer to address it proactively — especially given BB DC users are already showing up (#661, #731) — I'm happy to prototype Option B.

What's your preference?

[danielmeppiel]

Panel verdict: Option D + targeted warning + doc note (your lean is right)

Ran this past the full review panel. Strong consensus -- you've already done the hard analysis; here's the synthesized direction.

---

Why D, briefly

Strategic (CEO + Growth Hacker)

Strict-by-default (#778) was a deliberate bet: "be explicit; APM won't guess transports." Adding a fallback: field to the dependency schema (Option B) is a large surface (lockfile keying, policy schema, plugin export, marketplace ingestion, identity dedup) for a scenario that:

1. Strict mode already prevents for the 99%+ default path, and
2. Every BB-DC / non-standard-port user can already work around by pinning the protocol they want (ssh://...:7999 or https://...:7990).

Adding schema would weaken the "explicit beats magic" story we just shipped. We should hold the line.

Architecture (Python Architect)

If we ever do this, B is the right primitive (it generalizes to path/host/proxy differences -- ADO especially). C (per-protocol port fields) is a half-measure that doesn't generalize. So: don't ship C; keep B in the back pocket; only revisit if real demand materializes.

Security (Supply-Chain Security Expert)

Option A's "try same port, then default port" cascade is the worst of the four: it sends auth credentials at URLs the user never wrote. Marginal but real. The current "same port across protocols" behavior is actually conservative -- fails loudly. Don't replace it with a guesser.

DevX UX (DevX UX Expert)

--allow-protocol-fallback is an opt-in escape hatch. We owe those users a clear failure, not a clever guess. The right fix is to tell them upfront, not at clone time.

Logging (CLI Logging Expert)

Any warning routes through CommandLogger, default visibility ([!]), once per dep, not per attempt.

---

Recommended scope of the small PR

A 30-50 line change, no schema impact:

1. In _clone_with_fallback (or TransportSelector.select): when --allow-protocol-fallback is active AND dep_ref.port is not None AND the planned attempts include both schemes, emit a default-visibility warning before the first clone attempt. Suggested wording:

   [!] Custom port {port} is set on this dependency. Cross-protocol fallback will reuse the same port for the other scheme. If your server uses different ports per protocol (e.g., Bitbucket Datacenter: SSH 7999, HTTPS 7990), pin the protocol with an explicit ssh:// or https:// URL.

2. docs/src/content/docs/guides/dependencies.md + authentication.md: a short callout under the strict-transport / fallback section documenting the limitation and the pin-the-protocol workaround.

3. apm install --allow-protocol-fallback help text: one-line caveat that fallback reuses the same port.

4. CHANGELOG: one Changed entry under [Unreleased] noting the warning.

5. Tests: cover the warning fires when expected, doesn't fire in strict mode, doesn't fire when no port is set.

What we explicitly do NOT do

• No fallback: field, no ssh_port/https_port fields, no schema migration.
• No multi-port cascade (security regression).
• No change to the existing test_https_attempt_preserves_same_port_across_protocols invariant -- it stays as the documented behavior, the warning makes that behavior loud.

When to revisit Option B

If we see 2+ external issues over the next ~60 days from users who genuinely cannot pin a single protocol (e.g., they need both SSH for push and HTTPS for clone in the same apm.yml, with different ports), escalate to Option B. Until then, the warning + docs is the right level of investment.

---

Action

Happy for you to take the small PR if you want it -- the four files above are the only touch points. Tag me for the review when ready. Thanks for the careful write-up; this is exactly the level of analysis that lets us make a confident "no, and here's why" call.