Protected routes and middleware in Astro - Deep Dive

Overview - Protected routes and middleware

What is it?

Protected routes are parts of a website or app that only certain users can access, usually after logging in. Middleware is a piece of code that runs before reaching these routes to check if the user has permission. In Astro, middleware helps control access by running checks on requests before showing pages. This keeps private information safe and ensures only authorized users see certain content.

Why it matters

Without protected routes and middleware, anyone could see private pages or data, which can cause security problems and privacy leaks. Middleware acts like a gatekeeper, stopping unauthorized users early. This makes websites safer and builds trust with users. Imagine a locked door that only lets in people with the right key; middleware is that lock for your website.

Where it fits

Before learning protected routes and middleware, you should understand basic routing and how Astro serves pages. After this, you can learn about authentication methods like JWT or OAuth, and how to manage user sessions. Later, you might explore advanced security patterns and server-side rendering with Astro middleware.

Mental Model

Core Idea

Middleware acts as a checkpoint that inspects every request to protected routes and decides if access should be allowed or denied.

Think of it like...

Think of middleware as a security guard at a building entrance who checks your ID before letting you into restricted rooms.

┌───────────────┐
│ User Request  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│  Middleware   │───Checks if user is authorized
└──────┬────────┘
       │
  Yes  │  No
       ▼     ▼
┌───────────┐  ┌───────────────┐
│ Protected │  │ Redirect to   │
│  Route    │  │ Login or Error│
└───────────┘  └───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Routes in Astro

Concept: Learn what routes are and how Astro handles them.

In Astro, routes are files inside the 'src/pages' folder. Each file corresponds to a URL path. For example, 'src/pages/about.astro' is the '/about' page. When a user visits a URL, Astro serves the matching page file.

Result

You can create pages that users can visit by adding files in the pages folder.

Knowing how Astro maps files to URLs is essential before adding any access control.

2

Foundation

What is Middleware in Astro?

Concept: Middleware is code that runs before a route loads to inspect or modify requests.

Astro middleware runs on the server before a page is served. It can check things like cookies or headers to decide if the user should see the page or be redirected. Middleware files live in 'src/middleware.ts' or similar.

Result

You can intercept requests and run logic before pages load.

Middleware gives you a chance to control access and behavior before the user sees anything.

3

Intermediate

Creating a Simple Protected Route

🤔Before reading on: do you think a protected route blocks access by returning an error or redirecting? Commit to your answer.

Concept: Use middleware to check if a user is logged in before allowing access to a route.

In middleware, check for a cookie or token that shows the user is logged in. If missing, redirect to the login page. If present, let the request continue to the protected page.

Result

Users who are not logged in get sent to login; logged-in users see the protected page.

Understanding how to check user state in middleware is key to protecting routes.

4

Intermediate

Handling Redirects in Middleware

🤔Before reading on: do you think middleware can modify the response to redirect users? Commit to your answer.

Concept: Middleware can send a redirect response to guide users to different pages.

If a user is unauthorized, middleware returns a Response with status 302 and a 'Location' header pointing to the login page. This stops the original request and sends the user elsewhere.

Result

Unauthorized users never see the protected content and are smoothly redirected.

Knowing how to send redirects in middleware helps create smooth user experiences.

5

Advanced

Protecting Multiple Routes with Middleware

🤔Before reading on: do you think one middleware can protect many routes or do you need one per route? Commit to your answer.

Concept: Middleware can inspect the request path and apply protection to many routes at once.

In middleware, check the request URL path. If it matches any protected route pattern (like '/dashboard' or '/profile'), run the auth check. Otherwise, let the request pass freely.

Result

You can protect groups of pages with one middleware file, making code simpler and consistent.

Centralizing route protection reduces errors and makes maintenance easier.

6

Expert

Middleware Performance and Edge Cases

🤔Before reading on: do you think middleware runs on every request, even for static assets? Commit to your answer.

Concept: Middleware runs on every request, so it should be efficient and handle edge cases like static files or API calls.

Middleware runs for all requests by default. To avoid slowing down your site, exclude static assets or public files by checking request paths. Also, handle cases where cookies might be missing or malformed gracefully to avoid crashes.

Result

Your site stays fast and reliable even with middleware protecting routes.

Understanding middleware's scope and performance impact helps build scalable, user-friendly apps.

Under the Hood

Astro middleware runs on the server as a function that receives each incoming request. It can read request headers, cookies, and URL paths. Based on logic, it returns either the original response, a redirect response, or an error. This happens before the page rendering, so unauthorized users never get the protected content.

Why designed this way?

Middleware was designed to provide a centralized, reusable way to control access and modify requests without changing each page. This separation keeps code clean and secure. Alternatives like embedding checks inside pages are error-prone and scattered, so middleware offers a better pattern.

┌───────────────┐
│ Incoming Req  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│  Middleware   │
│  (Check Auth) │
└──────┬────────┘
       │
  Yes  │  No
       ▼     ▼
┌───────────┐  ┌───────────────┐
│  Serve    │  │ Redirect to   │
│ Protected │  │ Login Page    │
│  Page     │  └───────────────┘
└───────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does middleware only run on page requests, or on all requests including images and scripts? Commit to your answer.

Common Belief: Middleware only runs on page requests, so static files are not affected.

Reality: Middleware runs on every request by default, including static assets like images and scripts.

Why it matters: If middleware is slow or blocks static files, it can slow down the whole site or break asset loading.

Quick: Can middleware directly render page content? Commit to your answer.

Common Belief: Middleware can generate and send the full page content itself.

Reality: Middleware only controls the request flow; it cannot render pages but can redirect or block requests before rendering.

Why it matters: Misunderstanding this leads to trying to put page logic in middleware, which won't work and causes confusion.

Quick: Is it safe to trust client-side cookies without verification in middleware? Commit to your answer.

Common Belief: Client cookies can be trusted as-is to verify user identity.

Reality: Client cookies can be tampered with; middleware should verify tokens or session data securely.

Why it matters: Trusting unverified cookies can let attackers bypass protections and access private data.

Quick: Does protecting a route in middleware guarantee full security? Commit to your answer.

Common Belief: Middleware protection alone fully secures the route and data.

Reality: Middleware protects route access but backend APIs and data must also be secured separately.

Why it matters: Relying only on middleware can leave APIs exposed, risking data leaks.

Expert Zone

1

Middleware order matters: stacking multiple middleware functions can cause unexpected behavior if not ordered correctly.

2

Middleware runs on the server side only, so client-side state changes do not affect it directly.

3

Using middleware to protect routes is efficient, but combining it with server-side session validation adds stronger security.

When NOT to use

Middleware is not ideal for protecting static-only sites without server logic or for client-only apps where route protection happens on the client side. In those cases, use client-side guards or serverless functions for security.

Production Patterns

In production, middleware often integrates with authentication providers (like OAuth or JWT) to verify tokens. It also handles role-based access control by checking user roles before allowing route access. Middleware is combined with logging and error handling for robust security.

Connections

Authentication

Middleware builds on authentication by enforcing access control after user identity is established.

Understanding authentication helps you know what middleware checks to perform and why.

HTTP Status Codes

Middleware uses HTTP status codes like 302 for redirects and 401 for unauthorized access.

Knowing status codes helps you create correct responses that browsers understand for access control.

Airport Security

Middleware acts like airport security screening passengers before boarding, similar to how middleware screens requests before serving pages.

This cross-domain connection shows how layered checks improve safety and flow in different systems.

Common Pitfalls

#1 Middleware blocks static assets causing broken images and styles.

Wrong approach:

export async function middleware(request) {
// Always check auth without exceptions
if (!request.cookies.get('token')) {
return Response.redirect('/login', 302);
}
return;
}

Correct approach:

export async function middleware(request) {
const url = new URL(request.url);
if (url.pathname.startsWith('/assets') || url.pathname.endsWith('.css')) {
return;
}
if (!request.cookies.get('token')) {
return Response.redirect('/login', 302);
}
return;
}

Root cause:

Not excluding static files from middleware checks causes unnecessary blocking.

#2 Trusting client cookies without verification leads to security holes.

Wrong approach:

const token = request.cookies.get('token');
if (!token) {
return Response.redirect('/login', 302);
}
// Assume token is valid without checking

Correct approach:

const token = request.cookies.get('token');
if (!token || !verifyToken(token)) {
return Response.redirect('/login', 302);
}

Root cause:

Assuming client data is trustworthy without server-side validation.

#3 Trying to render page content inside middleware causes errors.

Wrong approach:

export async function middleware(request) {
return new Response('Protected Content', { headers: { 'Content-Type': 'text/html' } });
}

Correct approach:

export async function middleware(request) {
if (!request.cookies.get('token')) {
return Response.redirect('/login', 302);
}
return;
}

Root cause:

Misunderstanding middleware's role as a request interceptor, not a page renderer.

Key Takeaways

Protected routes keep sensitive pages safe by allowing access only to authorized users.

Middleware in Astro runs before pages load and can check user permissions to protect routes.

Middleware can redirect unauthorized users smoothly to login pages, improving user experience.

Efficient middleware excludes static assets to avoid slowing down the site or breaking resources.

Always verify client data like cookies securely in middleware to prevent security risks.

Practice

1. What is the main purpose of middleware in Astro when protecting routes?

easy

A. To check user access before loading a page

B. To style the page content dynamically

C. To fetch data after the page loads

D. To optimize images on the page

Solution

1. Step 1: Understand middleware role

   Middleware runs before a page loads to perform checks or actions.

2. Step 2: Identify middleware use in protected routes

   It checks if a user has permission to access certain pages before showing them.

3. Final Answer:

   To check user access before loading a page -> Option A

4. Quick Check:

   Middleware checks access = D [OK]

Hint: Middleware runs first to check access before page loads [OK]

Common Mistakes:

• Thinking middleware styles pages
• Assuming middleware fetches data after load
• Confusing middleware with image optimization

2. Which syntax correctly defines a middleware matcher for protecting all routes under /dashboard in Astro?

easy

A. export const matcher = '/dashboard/*';

B. export const matcher = ['/dashboard/*'];

C. export const matcher = ['/dashboard'];

D. export const matcher = '/dashboard';

Solution

1. Step 1: Recall matcher syntax

   Matcher must be an array of strings specifying route patterns.

2. Step 2: Match all routes under /dashboard

   Using '/dashboard/*' inside an array matches all subpaths.

3. Final Answer:

   export const matcher = ['/dashboard/*']; -> Option B

4. Quick Check:

   Matcher is array with pattern string = A [OK]

Hint: Matcher must be an array of route strings [OK]

Common Mistakes:

• Using string instead of array for matcher
• Missing wildcard * to match subroutes
• Using exact path without wildcard for nested routes

3. Given this middleware code in Astro, what happens when a user visits /profile without a valid token?

export const matcher = ['/profile'];

export async function middleware({ request, redirect }) {
  const token = request.headers.get('authorization');
  if (!token) {
    return redirect('/login');
  }
  return;
}

medium

A. Middleware throws an error

B. User sees the /profile page

C. User is redirected to /login

D. User is redirected to /home

Solution

1. Step 1: Check token presence

   The middleware checks if the 'authorization' header exists in the request.

2. Step 2: Redirect if no token

   If token is missing, middleware redirects user to '/login'.

3. Final Answer:

   User is redirected to /login -> Option C

4. Quick Check:

   No token means redirect to /login = A [OK]

Hint: No token triggers redirect to login [OK]

Common Mistakes:

• Assuming user sees page without token
• Expecting error instead of redirect
• Redirecting to wrong path

4. Identify the error in this Astro middleware code meant to protect /admin routes:

export const matcher = '/admin/*';

export function middleware({ request, redirect }) {
  const user = request.headers.get('user');
  if (user !== 'admin') {
    redirect('/not-authorized');
  }
}

medium

A. request.headers.get does not exist

B. redirect should be called with await

C. middleware must be async function

D. matcher should be an array, not a string

Solution

1. Step 1: Check matcher syntax

   Matcher must be an array of strings, not a single string.

2. Step 2: Confirm redirect usage

   Redirect can be called synchronously; no await needed here.

3. Final Answer:

   matcher should be an array, not a string -> Option D

4. Quick Check:

   Matcher array required = C [OK]

Hint: Matcher must always be an array even for one route [OK]

Common Mistakes:

• Using string instead of array for matcher
• Thinking redirect needs await
• Confusing request.headers API

5. You want to protect both /dashboard and /settings routes using middleware in Astro. Which matcher setup correctly protects both paths and their subpaths?

hard

A. export const matcher = ['/dashboard/*', '/settings/*'];

B. export const matcher = ['/dashboard', '/settings'];

C. export const matcher = ['/dashboard*', '/settings*'];

D. export const matcher = ['/dashboard/**', '/settings/**'];

Solution

1. Step 1: Understand wildcard usage

   '/*' matches all subpaths under a route, ensuring protection of nested pages.

2. Step 2: Verify matcher array format

   Matcher must be an array of strings with correct wildcard patterns.

3. Final Answer:

   export const matcher = ['/dashboard/*', '/settings/*']; -> Option A

4. Quick Check:

   Array with '/*' wildcard protects subpaths = B [OK]

Hint: Use '/*' wildcard in array to protect all subroutes [OK]

Common Mistakes:

• Omitting wildcard to protect subpaths
• Using incorrect wildcard like '**'
• Using string instead of array for matcher