Slice 9: Auth — Logout (Revoke Refresh Token)

[rghvgrv]

What

Adds POST /api/v1/auth/logout — revokes the caller's presented refresh token so it can no longer be used at /refresh. This completes the 3-slice auth foundation (register/login, refresh rotation, logout).

Implements Slice 9 of the backend foundation PRD (#1).

Changes

• src/SubVora.Application/Auth/IAuthService.cs: adds LogoutAsync(Guid userId, string presentedRefreshToken, ...)
• src/SubVora.Infrastructure/Auth/AuthService.cs: implementation — looks up the token by hash scoped to the caller's own user_id, sets revoked_at, quietly no-ops on a missing/foreign/already-revoked token
• src/SubVora.Api/Controllers/AuthController.cs: POST /api/v1/auth/logout, [Authorize]-protected, reads the caller's user id from the JWT's sub claim
• tests/SubVora.Api.Tests/LogoutControllerTests.cs: 4 new tests

Deviation from the issue (same as Slice 8)

Extended the existing IAuthService/AuthService rather than introducing the RefreshTokenService the issue's routing metadata referenced — that file doesn't exist in this codebase's actual Slice 7/8 design; refresh-token revocation logic already lives in AuthService alongside login and refresh-rotation.

A scoping decision worth flagging

The issue's acceptance criteria just says "revokes the caller's refresh token." I scoped the lookup to WHERE token_hash = @hash AND user_id = @callerUserId rather than just WHERE token_hash = @hash — an authenticated user should only be able to revoke their own sessions, not anyone else's token if they somehow knew its literal value (impractical to guess, since it's 32 random bytes, but scoping costs nothing and is the correct invariant for a logout endpoint). Verified with a dedicated test: attacker calls /logout with another user's real refresh token, gets 204 (logout is deliberately quiet, no info leakage) but the victim's token is confirmed still usable at /refresh afterward.

Verification

• dotnet build SubVora.slnx — 0 warnings, 0 errors
• dotnet test SubVora.slnx — 32/32 pass (2 smoke + 17 Infrastructure.Tests + 14 in Api.Tests, up from 10)
• Logout_WithValidRefreshToken_RevokesIt / Logout_ThenAttemptRefresh_Returns401 — the 2 required cases
• Logout_WithoutAccessToken_Returns401 — confirms [Authorize] actually gates the endpoint
• Logout_WithAnotherUsersRefreshToken_DoesNotRevokeIt — the ownership-scoping proof described above

Acceptance criteria (from #10)

• POST /api/v1/auth/logout requires a valid access token and revokes the presented refresh token.
• A revoked refresh token can no longer be used at /api/v1/auth/refresh (returns 401).

Also in this PR: Swagger UI + API docs

Requested separately, bundled in here since the auth surface (4 endpoints now) was the natural point to add it.

• Added Swashbuckle.AspNetCore.SwaggerUI (UI package only) pointed at the OpenAPI document .NET 10's built-in AddOpenApi()/MapOpenApi() already generates — one source of truth for the spec itself, Swashbuckle just renders it. Served at /swagger in Development only, same gating as the raw /openapi/v1.json endpoint.
• Enabled GenerateDocumentationFile on SubVora.Api and added XML doc comments (<summary>/<remarks>/<response>) plus matching [ProducesResponseType] attributes to all 4 AuthController actions, so the generated spec has real descriptions instead of bare method names. Suppressed CS1591 rather than requiring doc comments on every member — only public controller actions are documented, not DTOs/Program.cs.
• Verified locally, not just by inspection: ran the API with dotnet run, curled /openapi/v1.json and confirmed all 4 endpoints present with correct summaries and response descriptions, curled /swagger/index.html and confirmed the UI shell serves correctly.
• Found and fixed a .gitignore gap along the way: .vs/ and *.user were sitting untracked in the working tree but weren't actually covered by this repo's .gitignore (it's the streamlined dotnet-only template, which explicitly excludes IDE-specific entries) — added a small Visual Studio section.
• Refreshed README.md's stale "implementation not yet started" status line and filled in real Getting Started steps (docker compose, user-secrets, migrations, run, swagger link) now that there's an actual backend to run.

Not done: wiring a Bearer-auth "Authorize" button into Swagger UI (so /logout's [Authorize] requirement can be tested from the UI directly) — the .NET 9/10 native-OpenAPI security-scheme document-transformer API has shifted across recent versions and I didn't want to gamble on it working without a live check in a slice that wasn't asking for it. Flagging as a reasonable follow-up if it'd be useful.

Note: a local (uncommitted) change to src/SubVora.Api/appsettings.json setting a real-looking value for Jwt:Secret was sitting in the working tree when I picked this up — I did not commit it (matches the documented convention of empty placeholders + user-secrets/env vars only). Flagging in case it was your own local testing setup and you want to keep/manage it separately.

Closes #10