phase: 173_docs_push_creds_split

All gates green. Final report:

**Phase 173 — final verification pass (all tasks already complete in `complete/`)**

- Verified the full implementation is in the working tree: `docs_user`/`docs_token` settings + catalogue rows (task 01), `docs_repo` PUT 422 guard + `docs_token` write-only pin (task 02), `run_git(env)` + `push_document(user, token)` credential env (task 03), `settings_migrate.py` wired into `create_app()` (task 04), E2E suite (task 05).
- **Completion criteria:**
  1. GET `/api/admin/settings` lists `docs_user` (plain) + `docs_token` (secret, `value=null`), token never in any body — ✅ `test_docs_token_is_write_only_masked_end_to_end` + E2E sentinel-absent-from-DOM
  2. PUT `docs_repo` with `://user:pass@` → 422 naming the fields; clean URL passes — ✅ integration + E2E UI-side
  3. Token set → `GIT_CURL_USERNAME`/`GIT_CURL_PASSWORD`/`GIT_TERMINAL_PROMPT=0` on every git step; empty → `env=None` — ✅ mocked-git unit tests
  4. Legacy env split once at startup, idempotent, one INFO line, `.env` untouched — ✅ `test_settings_migrate.py` (4 shapes) + `test_docs_push_migrate.py`
  5. Full suite green, coverage >90%, lint clean — ✅
  6. E2E isolated: `test_docs_push_creds.py` 4/4; regression set (panel + layout + response_to_docs) 21/21 — ✅
  7. Commit + phase move — harness's job (per instructions, not mine).
  8. README/AGENTS consistent — ✅ (below)
- Tests/lint: `uv run pytest` exit 0 (4112 passed) · `uv run pytest --cov=app --cov-report=term-missing` TOTAL 99% · `uv run ruff check .` clean · `uv run pyright` 0 errors
- Docs: README.md (incl. Docs-push config section, guard/migration paragraph, `.env.example` block) and AGENTS.md verified consistent in full; fixed two stale docstrings in `app/config.py` + `app/core/settings_catalog.py` (`is_set` → the API's actual `has_value` field).
- No live-infrastructure changes (no live step in this phase). No next pending phase — `todo/` held only 173.

tests/integration/test_admin_settings_api.py

@@ -9,7 +9,7 @@ The pins (00_phase, Testing & Quality):
 * the auth matrix — anonymous AND a signed-in token USER get 403 on ALL
   four routes (the router-wide ``require_admin`` closes the surface on
   every method), the admin 200s on all four;
-* the shape — ``items`` length == ``len(Settings.model_fields)`` (75),
+* the shape — ``items`` length == ``len(Settings.model_fields)`` (78),
   groups in ``GROUPS`` order (the stable order the E2E pins against),
   ``totals.count`` / ``overridden`` correct, ``overlay_enabled`` true;
   on an empty table a field whose ``BOR_*`` var the test env sets
@@ -152,7 +152,7 @@ def test_auth_matrix_all_four_routes(client: TestClient, db: Session) -> None:
 
 
 def test_catalogue_shape_and_sources_on_empty_table(admin_client) -> None:
-    """The whole catalogue, grouped and stable: 75 items (exactly
+    """The whole catalogue, grouped and stable: 78 items (exactly
     ``Settings.model_fields``), groups in ``GROUPS`` order (each group a
     contiguous block, the block order = ``GROUPS``), ``totals`` correct,
     ``overlay_enabled`` true. On an empty table: the env-var-set field
@@ -418,7 +418,7 @@ def test_kill_switch_disables_the_mechanism_not_the_panel(
 def test_catalogue_stays_under_the_byte_budget(admin_client) -> None:
     """The whole catalogue stays under the phase-167 INFO bar (64 KB —
     ``BOR_LOG_LARGE_RESPONSE_BYTES``), so ``GET /api/admin/settings``
-    never floods the log (75 items ≈ 20 KB; the audit script re-verifies
+    never floods the log (78 items ≈ 20 KB; the audit script re-verifies
     the 256 KB budget in task 06)."""
     r = admin_client.get(API)
     assert r.status_code == 200
@@ -602,3 +602,166 @@ def test_llm_thinking_level_row_contract(
     anon = TestClient(fastapi_app)
     r = anon.put(f"{API}/llm_thinking_level", json={"value": "high"})
     assert r.status_code == 403 and r.json() == {"detail": "admin only"}
+
+
+def test_docs_token_is_write_only_masked_end_to_end(
+    admin_client: TestClient, db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (task 02, C1): ``docs_token`` is a write-only
+    ``secret=True`` row — the EXISTING generic secret contract pinned
+    for the new key (no new code): (a) before a save the GET reports
+    the row in the ``Docs push`` group, ``secret=true``,
+    ``value=null`` (masked) and ``has_value=false`` — with
+    ``docs_user`` a plain ``str`` row at ``""``; (b) a PUT stores it
+    (200) and the GET reports ``has_value=true`` with the plaintext
+    NOWHERE in the raw body — the core pin: the token text is absent
+    from the response JSON, the leak class this phase kills; (c) a
+    blank PUT 422s (the self-lockout guard — ``DELETE`` is the
+    explicit clear) and the stored value is unchanged; (d) a DELETE
+    unsets it (reset to the env value — ``""`` by default).
+    """
+    # A deterministic base (machine-independent, the phase-172 test's
+    # idiom): an explicit empty process value for both docs
+    # credentials — the process env RANKS ABOVE the operator's local
+    # ``.env`` (the conftest pin's reasoning), so this pins the code
+    # defaults no matter what the machine's ``.env`` carries.
+    monkeypatch.setenv("BOR_DOCS_USER", "")
+    monkeypatch.setenv("BOR_DOCS_TOKEN", "")
+    invalidate_settings()
+
+    # (a) the rows: docs_token masked + unset, docs_user plain + empty.
+    r = admin_client.get(API)
+    assert r.status_code == 200, r.text
+    item = _item(r.json(), "docs_token")
+    assert item["group"] == "Docs push"
+    assert item["label"] == "Docs token"
+    assert item["type"] == "str"
+    assert item["env_var"] == "BOR_DOCS_TOKEN"
+    assert item["secret"] is True
+    assert item["restart_required"] is False
+    assert item["overridable"] is True
+    assert item["masked"] is True
+    assert item["value"] is None
+    assert item["db_value"] is None
+    assert item["has_value"] is False
+    assert item["has_override"] is False
+    assert item["default"] == ""  # masked: the code default is never shown
+    user = _item(r.json(), "docs_user")
+    assert user["group"] == "Docs push"
+    assert user["label"] == "Docs user"
+    assert user["secret"] is False
+    assert user["masked"] is False
+    assert user["value"] == ""
+    assert user["has_value"] is False
+
+    # (b) a PUT stores it (200, the RAW string in app_settings) and the
+    # GET reports has_value=true with the plaintext NOWHERE in the raw
+    # body (asserted on response.text, not the parsed model).
+    r = admin_client.put(f"{API}/docs_token", json={"value": "bor-docs-tok-123"})
+    assert r.status_code == 200, r.text
+    assert r.json()["masked"] is True
+    assert r.json()["value"] is None
+    assert r.json()["has_value"] is True
+    assert r.json()["source"] == "db"
+    assert db.execute(
+        text("SELECT value FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == "bor-docs-tok-123"  # stored, exactly as sent
+    assert get_settings().docs_token == "bor-docs-tok-123"  # live, no restart
+
+    r = admin_client.get(API)
+    assert r.status_code == 200
+    item = _item(r.json(), "docs_token")
+    assert item["has_value"] is True
+    assert item["value"] is None
+    assert item["db_value"] is None
+    assert "bor-docs-tok-123" not in r.text  # NOWHERE in the raw body
+
+    # (c) a blank PUT is a 422 (a blank token would self-lockout —
+    # DELETE is the explicit clear) and the stored value is unchanged.
+    r = admin_client.put(f"{API}/docs_token", json={"value": "   "})
+    assert r.status_code == 422
+    assert "BOR_DOCS_TOKEN must not be blank" in r.json()["detail"]
+    assert db.execute(
+        text("SELECT value FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == "bor-docs-tok-123"  # unchanged
+
+    # (d) a DELETE unsets it: the row is gone and the effective value is
+    # back to the env value (the pinned "" — the anonymous state, C5).
+    r = admin_client.delete(f"{API}/docs_token")
+    assert r.status_code == 200, r.text
+    assert r.json()["source"] == "env"  # the pinned empty BOR_DOCS_TOKEN
+    assert r.json()["has_override"] is False
+    assert r.json()["has_value"] is False
+    assert get_settings().docs_token == ""  # the override is gone
+    assert db.execute(
+        text("SELECT count(*) FROM app_settings WHERE key = 'docs_token'")
+    ).scalar() == 0  # the row is gone
+
+
+def test_docs_repo_refuses_embedded_credentials(
+    admin_client: TestClient, db: Session, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Phase 173 (task 02, C4): a ``docs_repo`` PUT with a
+    ``://<user>:<pass>@`` segment is a 422 that NAMES the Docs user /
+    Docs token fields (asserted in the detail, not just present) and
+    stores NOTHING — the leak cannot be re-created from the UI. Clean
+    ``https://`` URLs, local paths and ``ssh://`` remotes pass
+    untouched; a ``user:``-looking subdomain (no trailing ``@``) does
+    NOT false-positive. A legacy ``.env`` value with embedded
+    credentials is NOT a PUT — the task-04 startup migration handles
+    that path."""
+    # A deterministic base: explicit empty/valid process values for the
+    # docs settings — the process env ranks above the operator's local
+    # ``.env`` (the conftest pin's reasoning), so the base is the code
+    # defaults no matter what the machine's ``.env`` carries (a local
+    # ``BOR_DOCS_REPO`` with embedded credentials is EXACTLY the leak
+    # class under test — it must not leak into this pin).
+    monkeypatch.setenv("BOR_DOCS_REPO", "")
+    monkeypatch.setenv("BOR_DOCS_BRANCH", "bor-docs")
+    invalidate_settings()
+
+    # The 422: names the replacement fields, stores nothing.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "https://u:pass@gitea.example.com/o/r.git"}
+    )
+    assert r.status_code == 422
+    detail = r.json()["detail"]
+    assert "Docs user" in detail
+    assert "Docs token" in detail
+    assert db.execute(text("SELECT count(*) FROM app_settings")).scalar() == 0
+    # The failed write did not disturb the live view.
+    assert get_settings().docs_repo == ""
+
+    # Clean https:// URL: passes (the branch validator is satisfied by
+    # the non-empty docs_branch default — the repo is set, the token
+    # shape is valid).
+    r = admin_client.put(f"{API}/docs_repo", json={"value": "https://gitea.example.com/o/r.git"})
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "https://gitea.example.com/o/r.git"
+    assert get_settings().docs_repo == "https://gitea.example.com/o/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # A local path: untouched.
+    r = admin_client.put(f"{API}/docs_repo", json={"value": "/srv/docs-repo"})
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "/srv/docs-repo"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # A ``user:``-looking subdomain: the trailing ``@`` requirement keeps
+    # the regex from false-positiving — passes untouched.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "https://sub.domain.example.com/r.git"}
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "https://sub.domain.example.com/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+
+    # An ssh:// remote (credentials via SSH keys, never in the URL):
+    # untouched.
+    r = admin_client.put(
+        f"{API}/docs_repo", json={"value": "ssh://git@gitea.example.com/o/r.git"}
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["db_value"] == "ssh://git@gitea.example.com/o/r.git"
+    assert admin_client.delete(f"{API}/docs_repo").status_code == 200
+    assert db.execute(text("SELECT count(*) FROM app_settings")).scalar() == 0