Skip to content

Validate slugs on both surfaces; keep a venv per mcp major (#69, #71) - #72

Open
daniel-pittman wants to merge 3 commits into
developfrom
fix/69-71
Open

daniel-pittman wants to merge 3 commits into
developfrom
fix/69-71

Conversation

@daniel-pittman

Copy link
Copy Markdown
Owner

Closes #69. Closes #71.

Two issues on one branch, three commits. Each commit message has the full detail.

#69: workspace and repo slugs reach URLs unencoded

Neither surface limited slugs to the characters Bitbucket allows. A ? or # in a slug moved the rest of the request path into a query string or fragment, so a request could reach a different endpoint than the tool named. For example, bb -w 'acme#f' vars set --workspace ... sent a variables write to /workspaces/acme. Python also accepted inner whitespace that bash rejected, which is a parity gap on a boundary check.

Both surfaces now accept only [A-Za-z0-9._-] for workspace and repo slugs. The existing empty, / and ./.. checks run first, with their messages unchanged.

  • Python: a new bb_api.validate_slug is used by repo_path, by the four workspace-level paths in bb_ops, and by mcp_server._resolve_repo before it builds the client.

  • bash: a new _slug_chars_ok helper is used by:

    • repo_path and _require_workspace;
    • bb repos, which had no workspace check at all;
    • the workspace scope of bb vars;
    • the whoami probe;
    • the open and approve browser URLs.

    It runs tr under LC_ALL=C, so the allowed set is byte-exact with Python's ASCII regex in every locale. A sentinel byte stops $(...) from stripping newline-only bad bytes.

  • whoami: on both surfaces it no longer probes an invalid workspace. Python's quote() leaves .. intact, which can reach the global repositories listing and report a false "auth OK".

  • InvalidURL: the MCP tools now also catch http.client.InvalidURL, which subclasses neither OSError nor ValueError and escaped the error envelope.

#71: residuals from the mcp 2.x migration (#70)

  • Rollback: the bootstrap venv is now named for the mcp major version (bitbucket-cli/venv-mcp2). Releases built for mcp 1.x keep using bitbucket-cli/venv, untouched.
  • Concurrent first launch: install-and-stamp runs under an exclusive fcntl.flock, and the sentinel is checked again once the lock is held.
  • Real-SDK test: TestRealMCPServer reads mcp_server.py's own import line and imports it from the real SDK. It skips only when mcp is absent.
  • Corrupt sentinel: an undecodable sentinel now triggers a reinstall instead of crashing startup.

On first launch after this merges, an existing install builds venv-mcp2 once, which takes about 30 seconds.

How it was verified

  • Python: 712 passed on Python 3.10, 3.11 and 3.12 with mcp 2.3.0. On 3.11 without mcp, 710 passed and 2 skipped.
  • bash: every harness passes. tests/bash/test_security_guards.sh passes 34/34 on host bash and in the pinned bash 3.2 image.
  • Real server over stdio, in scratch data directories:
    • A fresh bootstrap builds venv-mcp2, and bad slugs return the ValueError envelope from a real tool call.
    • Next to an mcp 1.30.0 venv, the new code left that venv untouched, and the pre-Migrate the MCP server to mcp 2.x (FastMCP is now MCPServer) #70 release still served all 43 tools from it.
    • Three simultaneous first launches: exactly one installed, and all three served.
  • The bash CLI, against an unrouted API base: each rejected input stops before the network. bb -w <valid> whoami still probes.
  • Mutation checks: each guard and fix was reverted once to confirm its tests fail.

Reviewed locally first

Two local rounds, each run by Claude (Opus), Codex and Antigravity.

  • Round 1: all three found that bb repos and bb vars --workspace still skipped the check, that whoami probed invalid workspaces, and that _slug_chars_ok passed newlines. Each was reproduced, then fixed in the third commit.
  • Round 2: Codex and Antigravity found nothing. All three confirmed every round-1 gap closed, with no regressions from the fix.

Accepted residuals, which go into a debt ticket after the merge:

  • whoami verdict for an invalid workspace (LOW). The MCP whoami returns auth.ok: False with a ValueError message naming the slug rule. The tool's convention for "not probed" is ok: None with a skipped reason, and bash prints "probe skipped". The fix is to return the skipped shape and update the two tests.
  • The install lock waits on pip. A hung pip blocks other first launches for as long as it runs.
  • flock support. A data directory on a filesystem without flock support fails the first bootstrap. A current venv skips the lock.
  • Venvs already upgraded by Migrate the MCP server to mcp 2.x (FastMCP is now MCPServer) #70. Installs that already moved bitbucket-cli/venv to mcp 2.x stay that way. The per-major directory protects future switches, and that old directory can be deleted once venv-mcp2 is up.
  • UUID-form identifiers are rejected by design.

🤖 Generated with Claude Code

daniel-pittman and others added 3 commits November 18, 2026 22:34
Slugs are interpolated into URL paths unencoded, and neither surface
limited them to the characters Bitbucket allows. A `?` or `#` in a slug
moved the rest of the request path into a query string or fragment, so
a request could reach a different endpoint than the tool named. Python
also accepted inner whitespace that bash already rejected, a parity gap
on a boundary check.

Both surfaces now accept only `[A-Za-z0-9._-]` for workspace and repo
slugs, after the existing empty, `/`, and `.`/`..` checks (whose
messages are unchanged):

- Python: new bb_api.validate_slug, used by repo_path, by the four
  workspace-level paths in bb_ops (projects_list, members_list,
  repos_list, and the workspace scope of the variables tools), and by
  mcp_server._resolve_repo before it builds the client.
- bash: new _slug_chars_ok, used by repo_path and _require_workspace.
  It runs `tr` under LC_ALL=C so the allowed set is byte-exact with
  Python's ASCII regex in every locale.

The MCP tools also catch http.client.InvalidURL, which subclasses
neither OSError nor ValueError and escaped the error envelope.

Tests cover each layer: bb_api, each bb_ops workspace path (no request
made), _resolve_repo before _get_client, the InvalidURL envelope, and
the bash security harness under host bash and bash 3.2. Disabling the
character check fails 30 Python tests and 7 bash cases.

Closes #69.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Four residuals from the mcp 2.x migration (#70):

- Rollback. The bootstrap venv was shared across releases, so once a
  newer release upgraded it to mcp 2.x, an older release (or a checkout
  switched back to one) saw a sentinel, skipped the install and failed
  importing mcp.server.fastmcp. The venv directory is now named for the
  mcp major version (`bitbucket-cli/venv-mcp2`), so releases built for
  mcp 1.x keep using `bitbucket-cli/venv` untouched. A test ties the
  directory name to the major in _VENV_DEPS.
- Concurrent first launch. Install-and-stamp now runs under an exclusive
  fcntl.flock on `venv-mcp2.lock` beside the venv, and the sentinel is
  checked again once the lock is held, so a launch that waited for
  another one's install re-execs without installing again.
- Real-SDK test reach. TestRealMCPServer now reads mcp_server.py's own
  `from mcp... import MCPServer` line and imports that module and class
  from the real SDK, so a wrong module path on that line fails the test.
  It skips only when the `mcp` package itself is absent; an installed SDK
  lacking the module now fails instead of skipping.
- Corrupt sentinel. _venv_is_current also treats a UnicodeDecodeError as
  stale, so an undecodable sentinel triggers a reinstall instead of
  crashing startup. The sentinel is read and written as UTF-8.

Verified by running the server over stdio in scratch data directories:
a fresh bootstrap builds venv-mcp2; beside an mcp 1.30.0 `venv` it
leaves that venv and its sentinel untouched, and the pre-#70 release
still serves all 43 tools from it afterward; of three simultaneous first
launches, exactly one installs and all three serve. Each of the four
fixes was reverted once to confirm its test fails. Full suite: 709
passed on Python 3.10, 3.11 and 3.12 with mcp 2.3.0; every bash harness
passes.

Closes #71.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first #69 commit put the slug check in bash repo_path and
_require_workspace, but some builders use neither:

- `bb repos` interpolated the workspace into /repositories/{ws} with no
  check at all. It now calls _require_workspace, like projects and
  members.
- `bb vars --workspace` (list, set and delete) built
  /workspaces/{ws}/pipelines-config/variables/ with only the empty, `/`
  and `.`/`..` checks, so a `#` sent a variables write to /workspaces/{ws}.
  It now also rejects inner whitespace and non-slug characters.
- `bb whoami` and the MCP whoami probed /repositories/{ws} for any
  workspace. Python's quote() leaves `..` intact, which can reach the
  global repositories listing and report a false "auth OK". Both now skip
  the probe for an invalid slug and say why. A test that pinned the old
  behavior (probing a `/`-bearing workspace, encoded) now asserts the
  skip.
- `bb open` and `bb approve` build bitbucket.org browser URLs; they now
  run the same slug checks through repo_path, and `approve` checks its
  build number.

_slug_chars_ok also accepted values whose only bad bytes were newlines,
because `$(...)` strips trailing newlines. A sentinel byte closes that.

The bash security harness gains cases for each path, plus direct
newline cases for _slug_chars_ok; it passes 34/34 on host bash and in the
pinned bash 3.2 image. Removing any one of the guards fails its cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Semgrep (OSS): no findings

Clean scan. Posted before the Claude review.

@github-actions

Copy link
Copy Markdown

CI Tests

✅ Tests passed: the pytest suite across Python 3.10/3.11/3.12 (and bash syntax checks) is green on b249a905a.

Posted before the Claude review so the test outcome is folded into the review.

@claude

claude Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Claude finished @daniel-pittman's task in 1m 28s —— View job


PR #72 review: no blocking findings

I found no correctness bugs, security problems or CLAUDE.md violations in this diff. The one finding is LOW, posted inline. CI passed (pytest on 3.10, 3.11 and 3.12, plus the bash syntax checks, green on b249a905a). Semgrep found nothing.

Findings

Severity Location Finding
LOW mcp_server.py:47 import fcntl at module top level runs on every import, including BB_MCP_SKIP_BOOTSTRAP=1 test imports, so the module can't be imported on non-POSIX systems. This changes nothing today: the bootstrap already assumes POSIX (bin/python3) and CI is Linux-only. If that ever matters, move the import into _bootstrap_venv.

The PR already lists two residuals, and I agree they are LOW and not blocking:

  • The MCP whoami returns auth.ok: False for an invalid slug, where the "not probed" convention is ok: None with a skipped reason, as bash does.
  • The install lock blocks other first launches for as long as pip runs.

What I checked

#69, slug validation on both surfaces

  • Python's validate_slug: the checks run in a safe order: non-string or blank, then /, then ./.., then _SLUG_RE.fullmatch. Using fullmatch means a trailing newline can't slip past the way it would with $. The new check is called in:

    • repo_path;
    • all four workspace-level paths in bb_ops (projects_list, members_list, repos_list, workspace-scope _variables_base);
    • both branches of _resolve_repo, before _get_client;
    • the whoami probe.

    The ValueError is raised inside the existing try and comes back in the error envelope.

  • bash's _slug_chars_ok:

    • Under LC_ALL=C, tr -d 'A-Za-z0-9._-' keeps the trailing - literal on both GNU and BSD tr.
    • The printf x sentinel correctly stops $(...) from stripping newlines.
    • It uses no bash 4+ features, so the 3.2 floor holds.
  • bash coverage: I grepped bb for every place a workspace or repo slug reaches a URL. All of them now go through the guard:

    • projects, members and repos use _require_workspace;
    • repo create and every repo command use repo_path;
    • workspace-scope vars has its own check;
    • the whoami probe has its own check;
    • the browser URLs in open and approve now go through repo_path.

    The vars check now also rejects inner whitespace (_ws_stripped != BB_WORKSPACE), which matches Python.

  • repo_path from open and approve: it runs in the parent shell, so kill -TERM $$ stops the script cleanly as intended.

  • http.client.InvalidURL: it is now in _TOOL_EXPECTED_EXCEPTIONS, which is correct because it subclasses neither OSError nor ValueError.

#71, follow-ups from the mcp 2.x migration

  • Lock and re-check: the sentinel is checked, then the lock is taken, then the sentinel is checked again before installing. A launch that waited on the lock therefore doesn't install a second time.
  • Lock release: finally releases the lock even when pip fails, and closing the file would release it anyway.
  • No lock once current: a re-exec'd child sees a current sentinel and never takes the lock.
  • Lock file location: it sits beside the venv, and the parent directory is created first, so open(..., "a") cannot fail on a missing directory.
  • Sentinel encoding: it is now read and written as UTF-8, and UnicodeDecodeError triggers a reinstall instead of crashing startup.
  • Venv name: venv-mcp2 is tied to the <3 ceiling in _VENV_DEPS by test_venv_dir_names_the_pinned_major, so the two can't drift apart silently.
  • Real-SDK test: TestRealMCPServer now parses mcp_server.py's own from mcp… import line, so a wrong module path fails the test instead of skipping it.

Test coverage

The tests added here meaningfully cover the behavior that changed:

  • Python slug checks:

    • test_bb_api.py covers bad characters (space, ?, #, %, control characters, tab, UUID form, non-ASCII), accepted slugs, non-string input, and the order of the error messages.
    • test_bb_ops_repos.py checks that all four workspace-level paths reject a bad slug before any request is sent.
    • test_mcp_server.py covers _resolve_repo rejecting before _get_client, the tool-level envelope, InvalidURL envelope handling, and the whoami skip.
  • Bootstrap: TestVenvInstallLock checks the order of lock, pip and exec events for:

    • a fresh install;
    • a launch that waited while another finished;
    • an already-current venv (no lock taken);
    • a failed install (lock released);
    • a corrupt sentinel.

    TestVenvPerMajor ties the venv name to the pinned major version.

  • bash: test_security_guards.sh adds rejection cases for every newly guarded command, a whoami probe-skip check, direct unit checks of _slug_chars_ok with newline inputs, and positive guard-pass cases.

  • Small gap: cmd_pipeline_approve gained a _require_build_number call, but no test feeds it a non-numeric build number. It uses the same helper logs already tests, so this is not blocking.

All tests passed in CI.

Comment thread mcp_server.py

from __future__ import annotations

import fcntl

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LOW: fcntl is now imported at module load, so the module can't be imported on non-POSIX systems. Only _bootstrap_venv uses fcntl, but this import runs on every import, including BB_MCP_SKIP_BOOTSTRAP=1 test imports. Today that changes nothing: the bootstrap already assumes POSIX (bin/python3), and CI is Linux-only. If Windows or a test-only import ever matters, move the import into _bootstrap_venv (or guard it). Not blocking.

@github-actions

Copy link
Copy Markdown

Review Gate

✅ Gate: PASS — Review reported no HIGH/CRITICAL findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Debt remaining from #70: mcp 2.x migration Validate repo and workspace slugs by character set on both surfaces

1 participant