From 991369bd54fc6b7c2b7de5e43c370421c9ccee3f Mon Sep 17 00:00:00 2001 From: Juan Pablo Date: Wed, 27 May 2026 15:35:46 -0300 Subject: [PATCH 1/2] docs: document auth session flow --- docs/agent-guide.md | 4 ++++ scripts/docs_smoke.py | 2 ++ tests/test_docs_public_urls.py | 10 ++++++++++ 3 files changed, 16 insertions(+) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 68776ccd..6c79a221 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -110,6 +110,10 @@ curl -s -X POST "$API_HOST/api/v1/wallets/register" \ GitHub link and claim endpoints require GitHub OAuth plus a wallet signature. The browser flow starts at `https://mrwk.ltclab.site/auth/github/login?next=/me`. +Check the current session with `GET /api/v1/auth/me`; unauthenticated callers +receive `{"authenticated": false, "github_login": null}`. End a browser session +with `POST /auth/logout`, which redirects to `/` and clears the MergeWork auth +cookies. Do not use `GET /auth/logout` for logout side effects. ## Wallet Payloads diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py index 0871c020..53f9b581 100644 --- a/scripts/docs_smoke.py +++ b/scripts/docs_smoke.py @@ -44,6 +44,8 @@ "docs/agent-guide.md": [ ("Public reads such as `GET /api/v1/bounties/{id}/attempts` do not require login"), ("creating or releasing an attempt requires the GitHub-authenticated browser session"), + "Check the current session with `GET /api/v1/auth/me`", + "Do not use `GET /auth/logout` for logout side effects.", ], "docs/bounty-rules.md": [ "## Submission Evidence Templates", diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py index c7f13666..8b355903 100644 --- a/tests/test_docs_public_urls.py +++ b/tests/test_docs_public_urls.py @@ -113,6 +113,16 @@ def test_api_examples_document_auth_me_response_shape() -> None: assert "Unauthenticated requests return" in examples +def test_agent_guide_documents_auth_session_flow() -> None: + guide = Path("docs/agent-guide.md").read_text(encoding="utf-8") + + assert "https://mrwk.ltclab.site/auth/github/login?next=/me" in guide + assert "GET /api/v1/auth/me" in guide + assert '{"authenticated": false, "github_login": null}' in guide + assert "POST /auth/logout" in guide + assert "Do not use `GET /auth/logout` for logout side effects." in guide + + def test_api_examples_document_bounty_list_response_shape() -> None: examples = Path("docs/api-examples.md").read_text(encoding="utf-8") From 7535949598be8fcb8647c532c580ea90c376f102 Mon Sep 17 00:00:00 2001 From: Juan Pablo Date: Wed, 27 May 2026 15:52:16 -0300 Subject: [PATCH 2/2] docs: lock auth logout contract --- docs/agent-guide.md | 4 ++-- scripts/docs_smoke.py | 1 + tests/test_docs_public_urls.py | 2 ++ 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 6c79a221..5ee9a8ab 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -112,8 +112,8 @@ GitHub link and claim endpoints require GitHub OAuth plus a wallet signature. The browser flow starts at `https://mrwk.ltclab.site/auth/github/login?next=/me`. Check the current session with `GET /api/v1/auth/me`; unauthenticated callers receive `{"authenticated": false, "github_login": null}`. End a browser session -with `POST /auth/logout`, which redirects to `/` and clears the MergeWork auth -cookies. Do not use `GET /auth/logout` for logout side effects. +with `POST /auth/logout`, which redirects to `/` and clears the MergeWork auth cookies. +Do not use `GET /auth/logout` for logout side effects. ## Wallet Payloads diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py index 53f9b581..d392a178 100644 --- a/scripts/docs_smoke.py +++ b/scripts/docs_smoke.py @@ -45,6 +45,7 @@ ("Public reads such as `GET /api/v1/bounties/{id}/attempts` do not require login"), ("creating or releasing an attempt requires the GitHub-authenticated browser session"), "Check the current session with `GET /api/v1/auth/me`", + "clears the MergeWork auth cookies", "Do not use `GET /auth/logout` for logout side effects.", ], "docs/bounty-rules.md": [ diff --git a/tests/test_docs_public_urls.py b/tests/test_docs_public_urls.py index 8b355903..05c3defa 100644 --- a/tests/test_docs_public_urls.py +++ b/tests/test_docs_public_urls.py @@ -120,6 +120,8 @@ def test_agent_guide_documents_auth_session_flow() -> None: assert "GET /api/v1/auth/me" in guide assert '{"authenticated": false, "github_login": null}' in guide assert "POST /auth/logout" in guide + assert "redirects to `/`" in guide + assert "clears the MergeWork auth cookies" in guide assert "Do not use `GET /auth/logout` for logout side effects." in guide