nuxt4-demo/docs/superpowers/plans/2026-04-16-auth-access-control-implementation-plan.md

Auth Access Control Implementation Plan

For agentic workers: Execute tasks in order and keep scope fixed to the approved spec. Use checkbox (- [ ]) tracking and verify each task before moving on.

Goal: Implement login-first access control for both pages and APIs, with code-based allowlists, safe login redirect handling, and dual-mode homepage rendering support.

Architecture: Introduce centralized route rule utilities, a global page guard (auth.global), a server API guard middleware (10.auth-guard), and a unified auth session composable. Default policy is deny-by-default for pages and /api/**, with narrow allowlists.

Tech Stack: Nuxt 4/Nitro middleware, existing session-cookie auth service, TypeScript utilities, Bun dev/build workflow.

---

File Structure Map

• Create: app/utils/auth-routes.ts
• Create: app/composables/useAuthSession.ts
• Create: app/middleware/auth.global.ts
• Create: server/utils/auth-api-routes.ts
• Create: server/middleware/10.auth-guard.ts
• Modify: app/pages/login/index.vue (handle redirect after login success)
• Modify: app/pages/index/index.vue (guest/authenticated split rendering)
• Optional small adjustments: shared HTTP wrapper for uniform 401 handling if needed

---

Task 1: Build shared page-route auth rules and redirect sanitizer

Files:

• Create: app/utils/auth-routes.ts

• Test: utility behavior via unit-like local checks (or temporary assertions)

• Step 1: Define route policy constants

Include:

• public routes exact set (initial: /, /login, /register)

• guest-only routes exact set (initial: /login, /register)

• default authenticated landing path

• Step 2: Implement safe redirect parser

Implement helper like normalizeSafeRedirect(input, fallback):

• allow only same-site relative paths

• must start with /

• reject //, protocol-like payloads (http:, https:, javascript:), empty strings

• return fallback when invalid

• Step 3: Implement route match helpers

Provide concise helpers:

• isPublicRoute(path)

• isGuestOnlyRoute(path)

• matching mode: exact + explicit prefix helper only (no broad regex)

• Step 4: Verify sanitizer edge cases

Validate examples:

• accept: /dashboard, /a?b=1
• reject: http://evil.com, //evil.com, javascript:alert(1)

---

Task 2: Add unified auth session composable

Files:

• Create: app/composables/useAuthSession.ts

• Test: manual behavior from multiple pages without duplicated calls

• Step 1: Implement canonical session state

Expose:

• loggedIn
• user
• pending
• refresh()
• clear()

Use /api/auth/me as source of truth.

• Step 2: Handle unauthorized consistently

When /api/auth/me returns 401:

• clear local state

• return loggedIn=false instead of throwing noisy UI errors

• Step 3: Ensure composable is reusable

Guarantee all pages/middleware consume this composable, not ad-hoc login checks.

---

Task 3: Implement global page guard middleware (default deny)

Files:

• Create: app/middleware/auth.global.ts

• Reuse: app/utils/auth-routes.ts, app/composables/useAuthSession.ts

• Step 1: Enforce default login-required policy

For every route:

• if route is not public and user not logged in, navigate to /login?redirect=<fullPath>

• Step 2: Enforce guest-only behavior

If logged-in user visits guest-only routes:

• resolve safe redirect target

• prioritize validated redirect query

• fallback to default authenticated landing path

• Step 3: Prevent redirect loops

Guarantee no self-loop on /login and /register.

• Step 4: Manual route-flow verification

Check:

• unauth -> protected page -> login redirect with query
• logged-in -> /login -> redirected away
• public routes remain reachable when unauthenticated

---

Task 4: Implement server API auth guard middleware (default deny for /api/**)

Files:

• Create: server/utils/auth-api-routes.ts

• Create: server/middleware/10.auth-guard.ts

• Step 1: Define API allowlist rules

Initial allowlist:

• /api/auth/login
• /api/auth/register
• required public-read APIs (e.g. GET /api/config/global)

Use exact + explicit prefix helpers only.

• Step 2: Guard /api/** requests

Middleware logic:

• non-API request -> skip

• allowlisted API -> skip

• others -> require valid session from event.context.auth.getCurrent()

• Step 3: Return unified unauthorized response

On unauthorized:

• return HTTP 401

• use generic status message

• do not leak auth internals

• Step 4: Validate API behavior

Check with/without cookie:

• protected APIs return 401 when unauthenticated
• allowlisted APIs still work

---

Task 5: Wire login/home pages to new access-control behavior

Files:

• Modify: app/pages/login/index.vue

• Modify: app/pages/index/index.vue

• Step 1: Login page post-success redirect

After successful login:

• call useAuthSession().refresh()

• read redirect query and sanitize

• navigate to safe target/fallback

• Step 2: Homepage dual-mode rendering

On /:

• unauthenticated: show guest-facing UI

• authenticated: show signed-in UI

• rely on useAuthSession state

• Step 3: Session-loss UX consistency

If session expires during interaction:

• state clears
• protected route access re-routes to login

---

Task 6: Verification matrix and polish

Files:

• Test-focused task; no intended new feature files

• Step 1: Route verification matrix

Run through:

• unauth + public route

• unauth + protected route

• auth + guest-only route

• auth + protected route

• Step 2: Redirect security matrix

Try login URL examples:

• /login?redirect=/safe/path (accepted)

• /login?redirect=http://evil.com (rejected)

• /login?redirect=//evil.com (rejected)

• Step 3: API verification matrix

Confirm:

• unauth -> protected /api/** => 401

• allowlisted APIs accessible unauthenticated

• expired session behaves as unauthorized

• Step 4: Build/lint sanity

Run:

• bun run build
• lint/type checks used by the repo

Fix only issues introduced by this scope.

---

Delivery Constraints

• Keep allowlists in code (no remote config source for auth policy)
• No RBAC/role granularity in this iteration
• No OAuth/SSO/password reset in this iteration
• Avoid broad route regexes that can accidentally expand exposure

Done Criteria

All below must be true:

• Page policy is deny-by-default with explicit public routes
• API policy is deny-by-default under /api/** with explicit allowlist
• Redirect handling is safe against open-redirect payloads
• Login and homepage behavior matches agreed UX
• Verification matrix passes without known regressions