Repository navigation
Description
Audit of main @ 3ccb5f1e1139abb708c113f6663e64eb953cb702 (43 commits, full history read), all 9 consumers full-cloned and compared byte-for-byte. Baseline: 252 tests pass, 98.9 % branch coverage, ruff/mypy clean. This follows the earlier P0–P3 remediation (#12, #13) and does not re-list what those fixed.
Consumer state at audit time: all 9 mcp-server-* repos consume shared; all copies are byte-identical to main. Six pin 73e65ec9; three (batocera, pixelcade, misterfpga) pin 769702a0 — see F1.
Severity: high = exploitable or data-leaking in the deployed setup; med = correctness/robustness bug reachable in practice; low = hardening, hygiene, docs.
Correctness & operations
F1 · med · Three consumers pin a commit that no longer exists on any branch — non-breaking
Evidence: batocera, pixelcade, misterfpga shared.lock → commit = "769702a01a28a175286a7e94ee5d264f635e8c3d". That SHA was the head of PR #14's mask-ip-url-helpers branch, squash-merged as 73e65ec9 and deleted. git cat-file -t 769702a in a fresh clone of this repo: not found. It resolves only because GitHub still serves the dangling object through raw.githubusercontent.com; a server-side GC breaks sync_shared.py --check in those three repos' CI with an opaque HTTP 404.
Why it happened: scripts/sync_shared.py only ever writes main's SHA (resolve_main), but never validates that the SHA it reads from a lock is reachable from main. A lock hand-edited (or synced from a branch checkout) is accepted silently.
Fix: in --check/--update, one GET /repos/{repo}/compare/main...{commit} call; warn (not fail) when status is ahead/diverged, with the squash-merge explanation and the fix (--update). Siblings: re-run --update (moves the lock to 3ccb5f1; no file changes).
F2 · low (corrected from med) · serve_http has no graceful-shutdown bound — non-breaking
Evidence: src/mcp_shared/remote.py:460-462 calls uvicorn.run(...) without timeout_graceful_shutdown, so uvicorn's default is to wait for every open connection before running lifespan shutdown. Every sibling's deploy/alpine/*.initd uses supervisor="supervise-daemon" with the default stop schedule SIGTERM/5 (man page); a SIGKILL after 5 s skips the siblings' lifespan teardown (device/MQTT disconnects).
Correction after measuring (2026-11-08): in the current stack (mcp 2.3, sse-starlette 3.7, uvicorn 0.54) this does not reproduce: the SDK's responses, including a tool call stuck on an unresponsive device, are SSE streams that sse-starlette closes ~1 s after it sees Server.should_exit, so lifespan shutdown ran in 1.1 s with or without the bound. The remaining risk is that sse-starlette finds uvicorn's exit flag by monkey-patch/introspection, which has broken before across versions (its own #132 and #211). So: defense in depth, not a live hang — severity lowered to low.
Fix: a fixed SHUTDOWN_TIMEOUT = 2 passed as timeout_graceful_shutdown (no new flag/env: the number only has to fit inside the supervisor's 5 s), uvicorn_settings(cfg) so a test runs the exact server configuration, and an end-to-end test that shuts down with a stuck tool call in flight and asserts lifespan shutdown runs inside the budget — a regression guard if the sse-starlette hook breaks. (Sibling-side, separately: siblings' stop_task(..., 5.0, …) timeouts equal the supervisor's whole budget; consider retry="SIGTERM/15" in the initd files.)
F3 · med · stop_tasks re-cancels every 250 ms, which interrupts a task's own finally: cleanup — non-breaking (behavior change)
Evidence: src/mcp_shared/tasks.py:92-94: every loop round calls task.cancel() on each pending task, then asyncio.wait(..., timeout=0.25). A task whose cleanup awaits anything >250 ms (MQTT DISCONNECT + close, a websocket close frame, await client.aclose()) gets a second CancelledError inside its finally. Reproduced: a worker with a 0.6 s awaited cleanup ends with cleanup_interrupted=True under stop_task(timeout=5).
History: the re-cancel exists for the Python 3.11 wait_for dropped-cancel bug (commit 4f4d397, CPython #28149, fixed in 3.12); sofabaton's mqtt.py:105 depends on it. The intent is sound; the period is the problem.
Fix: add grace: float = 1.0 to stop_task/stop_tasks/stop_background_tasks: cancel once, re-cancel only if still pending after grace, repeat. Keeps the 3.11 safety net, gives cleanups a full second. Tests that exercise the dropped-cancel path pass grace=0.25 explicitly; new test asserts a 0.6 s cleanup completes.
F4 · med · logsafe.redact_secrets misses several secret shapes that occur in this stack — non-breaking
Evidence (all verified against main; SECRET survives redact_secrets):
?access_token=SECRET,?refresh_token=,?id_token=,?client_secret=,?sig=/?signature=,?auth=,?code=—_QUERY_SECRET(logsafe.py:61) only matches a baretoken=/key=right after?/&, so the OAuth names are not covered.Authorization: Basic dXNlcjpwYXNz…,Authorization: Token …— onlyBeareris handled (logsafe.py:67).CF-Access-Client-Secret: <64 hex>(Cloudflare service tokens) and header/dict keysx-api-key,token,pairing_key,client_key,pin,pskinrepr()of a headers dict —_JSON_SECRETkey list (logsafe.py:62-64) lacks them.Cookie: CF_Authorization=SECRET/Set-Cookie: CF_Authorization=…— Access's cookie name isn't covered when the value isn't JWT-shaped.MQTT_PASSWORD=SECRET/*_SECRET=/*_TOKEN=env-style lines (e.g. a sibling logging its env at debug).repr(HttpConfig)/repr(AccessPolicy)prints the fullMCP_ALLOWED_EMAILSset.
Property-based fuzzing (3 000 cases each) ofredact()found no idempotence failures and no surviving non-loopback IPv4/IPv6 — the address rules are solid; the gaps are all in the secret-key vocabulary.
Fix: extend the key vocabularies, add a genericAuthorization: <scheme> <creds>rule, a header-line rule (Name: valuefor the sensitive names), a cookie rule forCF_Authorization, and an env-styleNAME_(PASSWORD|SECRET|TOKEN)=rule; add property tests underpytest.importorskip("hypothesis")so siblings without hypothesis still pass;AccessPolicy.emailsgetsfield(repr=False).
F5 · low · mask_ip leaks an IPv4-mapped address; mask_url raises on a bad port — non-breaking
Evidence: mask_ip("::ffff:192.168.1.5") → "x:x::192.168.1.5" (logsafe.py:130-131 takes the text after the last :; for mapped/embedded-v4 forms that is the whole IPv4). mask_url("http://192.168.1.5:abc/") raises ValueError from parsed.port (logsafe.py:172) — a helper meant for log paths must not raise. Found by property tests.
Fix: use ipaddress to detect ipv4_mapped/embedded v4 and mask that tail; wrap parsed.port and fall back to the raw netloc port text.
F6 · low · remote.py denial log and /healthz details
Evidence: remote.py:281 logs the rejected identity's e-mail verbatim ("{email} is not in MCP_ALLOWED_EMAILS"); logsafe has no e-mail rule, so a pasted log carries third-party PII. AccessVerifier holds anyio.Lock across the blocking JWKS fetch (:241-258), serialising all verifications for up to timeout=10 s during a refetch — acceptable but worth a comment. last_fetch is updated on every resolve, not only on network fetches (:257-258), so the variable name over-promises (behaviour is fine: it rate-limits unknown-kid probes).
Fix: mask the local part (u***@example.com) in the denial message (part of F4 PR); comment the two subtleties. Non-breaking.
scripts/sync_shared.py
F7 · med · Writes are not atomic — non-breaking
Evidence: write_files (:355) does path.write_bytes(...) in place; --update writes the lock with write_text (:530). A crash/SIGINT mid-write leaves a truncated module in src/<pkg>/, and nothing flags it until --check. The docstring's "a network failure halfway leaves the repo as it was" is true only for fetch failures.
Fix: write to <target>.tmp-<pid> in the same directory, os.replace(); same for the lock.
F8 · med · --update silently overwrites uncommitted hand-edits to synced copies — breaking (CLI behaviour)
Evidence: run() (:523-535) fetches and writes with no look at the working tree. A developer who edited src/<pkg>/remote.py locally (against the rule, but to debug) and then runs --update loses the edit with no message; git diff afterwards shows only upstream's change. sync_all_siblings.py update makes this fleet-wide.
Fix: when the sibling is a git repo, refuse to overwrite a target that git status --porcelain -- <target> reports modified, naming the files and suggesting git stash/git diff; --force overrides. Draft PR, labelled breaking: scripts that relied on silent overwrite need --force.
F9 · low · Lock parsing ignores unknown keys; repo regex allows ./.. segments — non-breaking
Evidence: read_lock (:124-144) reads exclude and ignores anything else, so excludes = ["remote"] (typo) silently excludes nothing and the next --update pulls remote.py into a stdio-only server. _REPO = r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+" (:82) accepts ../x, which becomes part of a raw.githubusercontent.com URL.
Fix: warn on unknown lock keys (list the known ones); reject repo segments that are ./...
CI & tooling
F10 · med · Workflow runs with default token permissions and tag-pinned actions — non-breaking
Evidence: .github/workflows/ci.yml has no permissions: block (the token gets the repo default, which may be write), actions/checkout@v7 / actions/setup-python@v7 are mutable tags, no timeout-minutes, no concurrency group, no Dependabot config (pip or github-actions). Python matrix 3.11–3.14 does cover what Alpine ships (3.12 on 3.20–3.22, 3.13 on edge) — fine.
Fix: permissions: contents: read, pin both actions to their v7 commit SHAs (3d3c42e5…, 6d4fd22b…) with a version comment, timeout-minutes: 15, concurrency: ${{ github.workflow }}-${{ github.ref }} with cancel-in-progress, .github/dependabot.yml for github-actions + pip (weekly). Siblings have the same gaps (6 of 9 lack permissions:); their copies of the pattern are out of scope here but worth a round.
F11 · low · No pre-commit; test templates excluded from lint — non-breaking
Evidence: pyproject.toml excludes templates/ from ruff/mypy (unavoidable: __PKG__), and there is no .pre-commit-config.yaml, so a template that fails lint is only caught after render in CI.
Fix: .pre-commit-config.yaml with ruff + a local hook that renders (sync_shared.py --source . --package mcp_shared) and lints tests/. Not addressed in this round.
Repo hygiene (public repo; code, docs, tests, history)
F12 · low · Room names and RFC 1918 addresses used as examples — non-breaking
Evidence: ratelimit.py:211 docstring example "Rate limit on Den: …"; templates/tests/test_ratelimit.py:84-85, 293-373 use "den", "office", "living room" as bucket keys. 192.168.1.{5,9,10,20,60,147} appear in logsafe.py:11, test_logsafe.py:42,104,151, test_remote.py:99,321-322,371. The portfolio convention is placeholders only; TEST-NET-1 (192.0.2.0/24) exists for exactly this.
Fix: "tv-1"/"tv-2"-style keys; 192.0.2.x everywhere (behaviour identical: only the last octet matters to the tests).
Secret scan of every blob in history (detect-secrets, plus a targeted PII pattern scan): no credentials, tokens, keys or hostnames found. Already-fixed history items are noted in the session report only, per the audit brief.
F13 · low · Docs: sibling list out of date — non-breaking
Evidence: CLAUDE.md:5-7 and README.md:16-24 list 8 siblings; mcp-server-misterfpga consumes shared (all 7 modules) and is missing. README should also say what a lock SHA must be (a main commit, not a PR-branch head) — the root cause of F1.
Architecture (RFC, not a PR)
F14 · RFC · copy-and-sync vs. a versioned package
Covered in the session report. Short version: keep copy-and-sync for now (zero-dependency Alpine LXC installs, byte-identical test templates, one SHA per sibling are real advantages at 9 consumers), but (a) make the lock point only at main commits (F1), (b) start tagging main (v0.x) so shared.lock can carry a human-readable version next to the SHA, and (c) revisit publishing mcp-server-shared to PyPI once the siblings themselves are on PyPI, because then pip install mcp-server-webos would need the shared package as a dependency anyway and the sync step becomes the odd one out.
PRs (all open 2026-11-08; CI green on Python 3.11–3.14)
| PR | Branch | Findings | Breaking | Consumers affected |
|---|---|---|---|---|
| #17 | audit/logsafe-secret-coverage |
F4, F6 | no | all 9 (logsafe, remote) |
| #18 | audit/logsafe-mask-helpers |
F5 | no | all 9 (logsafe) |
| #19 | audit/remote-graceful-shutdown |
F2 | no | all 9 (remote) |
| #20 | audit/tasks-recancel-grace |
F3 | no (default behaviour change) | all 9 (tasks) |
| #21 | audit/sync-atomic-and-lock-checks |
F1, F7, F9 | no | all 9 (sync script) |
| #22 | audit/sync-dirty-tree |
F8 | yes → draft, breaking; builds on #21 |
all 9 (sync script) |
| #23 | audit/ci-hardening |
F10 | no | none (this repo's workflow) |
| #24 | audit/hygiene-and-docs |
F12, F13 | no | all 9 (test templates, one docstring) |
Not yet addressed: nothing; all closed in the second round (2026-11-10, details in the closing comment): F11 pre-commit (#29); F14 (b) tags and lock version (#31, v0.1.0/v0.1.1), (c) PyPI won't fix; initd retry and sibling CI permissions: (sibling PRs, item C); e-mail masking in redact() (#28); a shared shared-drift workflow, reusable rather than synced (#30). Shutdown paths that can still exceed 15 s are tracked in their own repos (sofabaton#27, webos#18, misterfpga#15, workbench#14).
Generated by Claude Code
Activity
shared-drift: per-event concurrency group; only PR runs cancel
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift calls mcp-server-shared's reusable workflow (v0.1.0)
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
CI: shared-drift workflow pinned to v0.1.1
SDNick484 commentedon Nov 11, 2026
Second round (2026-11-10): what closed the remaining items
Everything below is merged, and CI is green on
mainin every repo it touched.mainis taggedv0.1.0(9449e9f, after A) andv0.1.1(5f9b824, after #33).A · mcp-server-shared
last_fetchonly on a network fetch (it was a real bug: cache hits kept a rotated key refused for up to the 1 h cache)redact()masks e-mail (u***@example.com), plus a fix for a quadratic_URL_PASSWORDregex and a flaky hypothesis testpre-commitecosystem (F11)shared-driftworkflow (workflow_call), read-only token, SHA-pinned, timeout, per-event concurrencyversionlock key, written by--update, shown by--check/status(F14 b)update --pr --auto-merge, off by default; reports and skips where auto-merge is off or no checks are required (all siblings today)B · sibling sync to
185fc55(same shared files asv0.1.1)batocera#28 · harmony#23 · misterfpga#14 · onkyo#11 · pixelcade#18 · shieldtv#11 · sofabaton#26 · steam-backlog#11 · webos#17 · workbench#12: all merged. Two earlier rounds (at
9449e9fand5f9b824) were closed unmerged: the first because #33 was needed, the second because its commits carried the local git identity (#34).C · sibling-side
retry="SIGTERM/15/SIGKILL/5", with each service's shutdown budget in a comment · C2 · CIpermissions: contents: read, per-event concurrency (only PR runs cancel),timeout-minuteson every job, SHA-pinned actions, Dependabot (actions + pip, weekly),shared-driftcalling #30's workflow atv0.1.1retryRelated fixes made along the way: steam-backlog#10 adds a commit allowlist to its privacy scan, for one earlier sync commit that carried the local git identity. steam-backlog#12 and steam-backlog-triage#19 allow Dependabot's
support@github.comsign-off, which was failing every PR's scan.F14 · architecture
(a) lock only
maincommits: done in #21. (b) tagmain, version in the lock: done (#31,v0.1.0/v0.1.1). (c) publish mcp-server-shared to PyPI: won't fix; copy-and-sync stays.Convention changes
maingetsvX.Y.Ztags.shared.lockmay carryversion = "vX.Y.Z", written by--updatewhen the locked commit is tagged. The first sync after this one writes it, because each sibling's--updateruns its own (older) script. Rolling back means deleting the key.uses: SDNick484/mcp-server-shared/.github/workflows/shared-drift.yml@<SHA> # vX.Y.Z. Workflows are not synced files; Dependabot bumps that pin like an action.redact()masks e-mail addresses by default: a log-output change for every consumer.pre-commitis in the dev extra (pre-commit install).retry="SIGTERM/15/SIGKILL/5"; supervise-daemon reads it at start.Deploying the merged services, along with their new initd files, is a separate step.
🤖 Generated with Claude Code