Actionable comments posted: 3

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/src/api/routes/auth/admin.routes.ts`:
- Around line 144-149: The catch block currently calls
clearAdminRefreshTokenCookie(res) for all non-403 errors which forces logout on
transient failures (e.g., failures in getUserById() or token issuance); change
it to only clear the cookie for explicit auth-invalidating failures by checking
the error type/status: call clearAdminRefreshTokenCookie(res) only when the
error indicates authentication is invalid (for example error instanceof AppError
&& error.statusCode === 401) or other known token-invalid errors, and otherwise
leave the cookie intact so transient backend errors do not log the admin out.
- Around line 53-59: The current catch converts every non-AppError into a 400
and includes the raw exception text; instead, preserve AppError propagation (if
error instanceof AppError then next(error)), otherwise log the original
exception (using the module logger or console.error) and call next(new
AppError('Failed to exchange admin session', 500,
ERROR_CODES.INTERNAL_SERVER_ERROR_OR_AUTH_ERROR)) with a generic 5xx status and
without appending error.message to the response; update the block around the
existing next(new AppError(...)) call in admin session exchange to implement
this behavior.

In `@packages/dashboard/src/lib/api/client.ts`:
- Line 3: The change to CSRF_COOKIE_NAME breaks existing sessions because
getCsrfToken() only reads the new key; update getCsrfToken() to try the new
constant CSRF_COOKIE_NAME first and, if not found, fall back to the previous
cookie name (the legacy key) so pre-existing sessions continue to work during
rollout; ensure any write/update logic (where CSRF_COOKIE_NAME is used)
continues to set the new key while reads accept both names, and reference
CSRF_COOKIE_NAME and getCsrfToken() when implementing the fallback.

---

Outside diff comments:
In `@backend/src/infra/security/token.manager.ts`:
- Around line 103-117: The strict guards in verifyRefreshToken are currently
rejecting pre-rollout refresh tokens; add a compatibility path that accepts
legacy refresh tokens for a 7-day window: detect a legacy shape (e.g., missing
csrfNonce or missing/absent sessionType or older claim layout) and allow
verification if jwt.verify succeeds and the token's iat/exp indicates it was
issued within the last 7 days; for legacy tokens, populate default values for
csrfNonce/sessionType in the returned RefreshTokenPayload (or include a
legacyRefresh flag) so callers can force rotation and skip CSRF recomputation
for that flow. Apply the same compatibility changes to the corresponding logic
referenced around lines 208-225 so both verification paths accept tokens from
the 7-day horizon and mark them for exchange.

In `@packages/dashboard/src/features/login/services/login.service.ts`:
- Around line 89-97: The fetch call in login.service.ts uses a hardcoded
'/api/auth/admin/refresh' which bypasses getDashboardApiBaseUrl(); update the
code that builds the refresh URL to use getDashboardApiBaseUrl() (e.g., compute
const base = getDashboardApiBaseUrl(); then build the refresh endpoint as base +
'/api/auth/admin/refresh' or otherwise join paths to avoid double slashes) and
use that URL in the fetch call (the function performing the fetch is the admin
refresh request in login.service.ts). Ensure headers, credentials, and
AbortSignal.timeout(REQUEST_TIMEOUT_MS) remain unchanged.

2 issues found across 13 files

Confidence score: 3/5

• There is some merge risk because backend/src/api/routes/auth/admin.routes.ts currently clears the admin refresh cookie on non-403 errors, which can force unexpected logouts during transient backend failures (severity 6/10, high confidence).
• Error handling in backend/src/api/routes/auth/admin.routes.ts also appears to expose raw internal failure messages and maps unexpected exchange failures to 400 INVALID_INPUT, which can misclassify server-side faults and leak internals.
• Pay close attention to backend/src/api/routes/auth/admin.routes.ts - tighten cookie-clearing conditions and return a generic server error for unexpected exchange failures.

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/src/api/routes/auth/admin.routes.ts">

<violation number="1" location="backend/src/api/routes/auth/admin.routes.ts:56">
P2: Avoid returning raw internal error messages and `400 INVALID_INPUT` for unexpected exchange failures; use a generic server error instead.</violation>

<violation number="2" location="backend/src/api/routes/auth/admin.routes.ts:147">
P2: Only clear the admin refresh cookie for authentication-invalidating failures (for example 401). Clearing it for every non-403 error turns transient backend failures into forced logout.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

Code Review — Fix admin refresh & persist CSRF along session

Summary: The approach is sound and the core security design is well-executed. The two root bugs (CSRF instability across rotation and admin/user cookie collision) are fixed correctly. No blocking issues; a few suggestions below.

Requirements context

No matching spec or plan was found under /docs/superpowers/specs/ or /docs/superpowers/plans/ for this change. Assessment is against the PR description and linked behaviour: (1) CSRF token must survive refresh-token rotation, (2) admin and user cookies must be independent.

Findings

Critical

(none)

Suggestion

[Software Engineering] Redundant verifyRefreshToken round-trip after generateRefreshToken
backend/src/api/routes/auth/admin.routes.ts:45 and :87

const csrfToken = tokenManager.generateCsrfToken(tokenManager.verifyRefreshToken(refreshToken));

The payload is already known (you just assembled it in generateRefreshToken). Calling verifyRefreshToken immediately after forces an unnecessary sign→verify round-trip. generateCsrfToken accepts a RefreshTokenPayload, so you can construct the struct inline instead:

const nonce = tokenManager.generateCsrfNonce();
const refreshToken = tokenManager.generateRefreshToken(result.user.id, 'admin', nonce);
const payload: RefreshTokenPayload = { sub: result.user.id, type: 'refresh', iss: 'insforge', csrfNonce: nonce, sessionType: 'admin' };
const csrfToken = tokenManager.generateCsrfToken(payload);

Or export a helper that returns both at once.

[Security] CSRF cookie missing Secure attribute
packages/dashboard/src/lib/api/client.ts:25

document.cookie = `${CSRF_COOKIE_NAME}=${encodeURIComponent(csrfToken)}; expires=${expires}; path=/; SameSite=Lax`;

The Secure flag is absent. The CSRF token would be transmitted in plaintext over HTTP. The production dashboard is presumably HTTPS-only, but adding ; Secure is cheap defence-in-depth and consistent with how the refresh cookies are configured.

[Software Engineering] No integration tests for the new HTTP endpoints
backend/src/api/routes/auth/admin.routes.ts (all four routes)

The unit tests in auth-cookies.test.ts and token-manager-csrf.test.ts cover the helpers well. But there are no tests exercising the actual routes (correct cookie header set, 401 on missing cookie, 403 on bad CSRF, cookie preserved on 403 but cleared on 401, is_project_admin guard, etc.). The PR description itself says "Testing in progress" — these should land before or alongside merge.

[Security] Stable CSRF nonce → stolen CSRF token valid for full 7-day session
backend/src/infra/security/token.manager.ts:133 (admin refresh) / index.routes.ts:612 (user refresh)

The nonce is intentionally kept constant across rotations to solve the flakiness bug (good call). The consequence is that a leaked CSRF token (e.g., read via devtools, XSS, or shared browser profile) remains valid for the entire 7-day session lifetime — it never rotates. This trade-off is reasonable given the bug being fixed, but is worth noting in a code comment or SECURITY.md for future maintainers.

Information

Breaking change: legacy refresh tokens rejected on deploy
backend/src/infra/security/token.manager.ts:111-117

verifyRefreshToken now rejects tokens that lack csrfNonce or sessionType. Any session established before this deploy (all current logged-in users and admins) will be rejected and forced to re-authenticate. The PR mentions this in the Macroscope note. Ops should plan for a coordinated deploy or an in-browser banner; no code change needed, just awareness.

No matching spec/plan in /docs/superpowers/
No existing spec or plan document covers admin session separation or CSRF persistence. Assessing against PR description alone.

Global rate limiter covers admin routes (3 000 req / 15 min / IP)
backend/src/server.ts:86-91 — the global rate limiter is in place, so POST /api/auth/admin/sessions is not completely unguarded. A tighter, credential-specific limiter would be better hardening but is outside the stated scope of this PR.

Verdict

approved (informational — explicit GitHub approval via the approve flow is a separate human action)

The CSRF stability fix (nonce embedded in token, HMAC-derived CSRF) and the admin/user cookie separation are both implemented correctly. timingSafeEqual, httpOnly, path-scoping, and session-type guards are all in the right places. The Suggestions above — especially integration tests and the Secure cookie attribute — should be addressed before or shortly after merge.

Actionable comments posted: 1

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/tests/unit/auth-admin-routes.test.ts`:
- Around line 24-27: The assertion is checking for an auth failure (401) but the
test intends to verify non-auth transient refresh failures; update the
expectations in the test to look for a transient status (e.g., 503) instead of
401. Specifically, in the test that references adminRoutesSource, replace the
check that looks for 'error instanceof AppError && error.statusCode === 401'
with one that looks for 'error instanceof AppError && error.statusCode === 503',
and flip the negative assertion to ensure it does not contain 'error.statusCode
=== 401' so the test asserts non-auth transient behavior.

---

Outside diff comments:
In `@packages/dashboard/src/lib/api/client.ts`:
- Around line 54-59: The request function removed the ability to make
unauthenticated calls; restore an explicit skipAuth (or allowUnauthenticated)
flag in request's options signature and use it when building headers so the
dashboard bearer token / 401 refresh flow is only applied when skipAuth is
false; specifically, update the request(...) options to include skipAuth?:
boolean, and change the header logic in request (and related branches around the
token/refresh flow in the same file) to: if skipAuth is truthy or an
Authorization header is already present, do not inject the dashboard bearer
token or trigger the refresh flow, otherwise attach Authorization and proceed
with refresh-on-401 behavior.

---

Nitpick comments:
In `@backend/tests/unit/auth-admin-routes.test.ts`:
- Around line 5-36: The test uses brittle source-text assertions against
admin.routes.ts and auth route files (checking for logger.error strings,
ERROR_CODES.INTERNAL_ERROR, AppError checks, and specific calls like
generateCsrfToken(tokenManager.verifyRefreshToken) or
verifyRefreshToken(newRefreshToken)) — replace these with behavioral unit tests
that exercise the route handlers instead: invoke the admin auth exchange and
assert the HTTP response is a generic server error and that internal error codes
are returned rather than relying on the exact logger message; simulate non-auth
transient refresh failures and assert the admin refresh cookie is preserved
(check Set-Cookie/no cookie deletion) and that 401 vs 403 behavior matches
expectations rather than string-matching on "error instanceof AppError"; for
CSRF/refresh token behavior, call the refresh/token issuance flow and assert you
do not perform an extra verify step on a freshly issued refresh token (i.e.,
generated refresh token is returned with CSRF derived via
generateRefreshTokenWithCsrf semantics) instead of searching for occurrences of
generateCsrfToken(tokenManager.verifyRefreshToken) or
verifyRefreshToken(newRefreshToken) in source text.

Summary

Fixes flaky admin refresh and cross-session logout by embedding a stable csrfNonce + sessionType in every refresh JWT, and isolating the admin refresh cookie to /api/auth/admin. The approach is architecturally sound; no Critical blockers.

Requirements context

No spec or plan under /docs/superpowers/specs/ or /docs/superpowers/plans/ matched this PR's scope — assessing against the PR description alone.

Findings

Critical

(none)

Suggestion

Security

S1 — POST /api/auth/admin/sessions is unrate-limited (backend/src/api/routes/auth/admin.routes.ts:58–84)

This endpoint validates email+password against static env-variable credentials. It has no rate limiter. An attacker with network access to the backend can brute-force admin credentials without constraint. The pre-existing route in index.routes.ts was also unrate-limited, but the migration to a dedicated router is a clean opportunity to fix this. Consider adding a lightweight per-IP limiter (e.g., sendEmailOTPRateLimiter or a new adminLoginRateLimiter) as middleware on this route. The sessions/exchange OAuth path does not have this problem since it validates a cloud-issued JWT, not a password.

S2 — Logout endpoint can be CSRF-triggered without authentication (backend/src/api/routes/auth/admin.routes.ts:141–152)

POST /api/auth/admin/logout clears the admin refresh cookie unconditionally, with no CSRF token or valid-cookie check. Because the admin refresh cookie carries SameSite=none, a cross-origin page can trigger a logout request that includes the cookie and force the admin to re-authenticate. This is a session-disruption vector rather than a session-takeover, but it's cheap to close: either require X-CSRF-Token here (same as refresh), or at minimum verify the admin cookie exists before clearing it.

Software Engineering

S3 — auth-admin-routes.test.ts tests source text, not behavior (backend/tests/unit/auth-admin-routes.test.ts:1–37)

All three test cases read the .ts source file with readFileSync and assert on string literals (e.g., toContain("logger.error('[Auth:AdminSessionExchange]...")). This validates that a specific string exists in the source file, not that the route actually behaves correctly under those conditions. A log message rename or code reformat would fail the test with no real regression. These would be much more valuable as actual route-level tests (using supertest against an Express app, matching the pattern in other test files in this repo) that assert HTTP response codes and cookie behaviour.

S4 — generateCsrfNonce() is unintentionally public (backend/src/infra/security/token.manager.ts:250–252)

generateCsrfNonce() is an internal implementation detail of generateRefreshToken / generateRefreshTokenWithCsrf. Callers outside TokenManager have no reason to call it. Making it private keeps the interface clean and prevents future callers from accidentally generating nonces that bypass the standard token-creation path.

Information

I1 — Asymmetric cookie-clearing strategy between user and admin refresh handlers

• User /refresh (index.routes.ts:615): clears cookie on all errors except 403 (CSRF mismatch).
• Admin /refresh (admin.routes.ts:133): clears cookie only on 401; all other errors (including 500s) leave the cookie intact.

Both preserve the cookie on CSRF failure (the critical invariant), but the admin path is more conservative — a transient DB error won't end an admin session. This is a reasonable product decision, but the asymmetry is not documented and may surprise future maintainers. A brief comment in the admin catch block explaining why 500s are treated differently from user sessions would help.

I2 — generateRefreshTokenWithCsrf is called for non-web client token rotation (backend/src/api/routes/auth/index.routes.ts:591–592)

In the user /refresh endpoint, generateRefreshTokenWithCsrf is always called (even for non-web clients), and the resulting csrfToken is discarded for that branch. The cost is negligible (one HMAC), but using generateRefreshToken for the non-web path would be more explicit about intent and avoids computing a value that's immediately thrown away.

I3 — Breaking change: all active refresh tokens will be invalidated on deploy

verifyRefreshToken now hard-rejects any token missing csrfNonce or sessionType. Every existing session (user and admin) will fail its first refresh after this ships and require re-authentication. This is called out in the PR description, but worth ensuring is communicated in release notes / deployment runbook so operators aren't surprised by a support spike.

Verdict

approved (informational — no Critical findings; human approval still required via the approve flow)

The CSRF design is solid: nonce is embedded in the signed JWT (not derivable without the secret), HMAC input includes sessionType to prevent cross-session reuse, and timingSafeEqual is used for the comparison. The cookie-path separation correctly isolates admin and user sessions. The test coverage in token-manager-csrf.test.ts and auth-cookies.test.ts is good; the main gap is the source-text assertions in auth-admin-routes.test.ts (S3 above). Address S1 and S2 before or shortly after ship.

Actionable comments posted: 1

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/tests/unit/auth-admin-routes.test.ts`:
- Around line 67-83: The helper postAdminRefresh currently uses global fetch
which is being interfered with in tests; replace it to perform a test-local
request against the Express app returned by createAdminAuthApp instead (use
supertest or Node http.request) so you don't start a real listener or depend on
global fetch. Update postAdminRefresh to accept headers, call
createAdminAuthApp() and issue a POST to /api/auth/admin/refresh via supertest
(or create a local request against the app), then return the response.status and
response.headers['set-cookie'] (preserving the current return shape) and ensure
the server is not bound to a real port or global fetch is avoided.

---

Outside diff comments:
In `@backend/tests/unit/auth-admin-routes.test.ts`:
- Around line 1-211: Run the project's Prettier formatter on the test file to
fix formatting drift: apply the configured Prettier rules (e.g., via your local
npm script like npm run format or npx prettier --write) to the test suite
containing describe('admin auth route review regressions', ...) and the helper
functions createAdminAuthApp and postAdminRefresh so the file no longer reports
lint/format violations; commit the reformatted file.

LGTM, approved.