Mindful Auth - Astro configuration

The following routes are publicly accessible without authentication:

Authentication Pages (UI)

/ - Root (redirects to login page)
/login - Password login
/register - Password registration
/magic-login - Magic link login
/magic-register - Magic link registration
/forgot-password - Password reset request
/resend-verification - Resend email verification
/reset-password/* - Password reset with token
/verify-email/* - Email verification with token
/email-verified/* - Email verified confirmation
/verify-magic-link/* - Magic link verification

Authentication API Endpoints

/auth/* - All API proxy endpoints to Mindful Auth (login, register, 2FA, etc.)

Static Assets (No Session Validation)

/favicon.ico
/robots.txt
/.well-known/security.txt

Protected Routes

All protected routes require a valid session and must include the memberid in the URL path:

/{memberid}/ - User profile and security settings
/{memberid}/dashboard - User dashboard
/{memberid}/* - Any dynamic protected pages

Accessing User Data in Components

Every page and component in protected routes has access to Astro.locals which contains the authenticated user’s data:

---
// In any .astro component, page, or layout
const { recordId } = Astro.locals;
---

<div>
   <p>User ID: {recordId}</p>
</div>

Available in Astro.locals:

recordId: string | null - The authenticated user’s unique ID

Important: Astro.locals is automatically populated by the middleware for all protected routes. You don’t need to pass props or import anything — just use Astro.locals.recordId directly in any component.

To extend Astro.locals: Add custom properties to the Locals interface in src/env.d.ts:

import type { MindfulAuthLocals } from '@mindfulauth/core';

declare namespace App {
    interface Locals extends MindfulAuthLocals {
        // ADD YOUR CUSTOM LOCALS HERE
        customUserId?: string;
        customData?: Record<string, unknown>;
    }
}

The base types (recordId, runtime) are provided by @mindfulauth/core and don’t need to be manually defined.

URL Authorization

All protected routes enforce memberid validation in the URL path:

/{memberid}/
/{memberid}/dashboard
/{memberid}/*

Routes under /{memberid}/ require the memberid in the URL to match the authenticated user’s session. Users cannot access another user’s pages by changing the memberid in the URL.

Security Benefits:

✅ Memberid validated at middleware level (early rejection before page render)
✅ URL structure makes it obvious which user’s data is being accessed
✅ Prevents accidental access - users can’t type /wrong-memberid/dashboard and get their own data
✅ Better for multi-tenant scenarios - clear resource ownership in the URL
✅ Audit-friendly - logs clearly show which memberid was accessed

Implementation:

The src/pages/[memberid]/ folder structure handles dynamic memberid routing
Middleware validates memberid at every request
Users cannot access other users’ pages by changing the URL

Customization

Authentication Pages

src/pages/login.astro
src/pages/register.astro
src/pages/magic-login.astro
src/pages/magic-register.astro
src/pages/forgot-password.astro
src/pages/resend-verification.astro
src/pages/reset-password/[...token].astro
src/pages/verify-magic-link/[...params].astro
src/pages/email-verified/[...params].astro
src/pages/auth/[...slug].ts

These files are critical for Mindful Auth to function. They contain:

Form structures required by Mindful Auth CDN scripts
Dynamic token/parameter handling for password reset and email verification
2FA setup and verification flows

You can modify styling, but do not remove data-mindfulauth-* attributes. Removing these will break authentication entirely.

Adding Custom Pages

You can add additional pages to the protected routes by creating new .astro files directly in the src/pages/[memberid]/ directory or in subdirectories for organizing your pages.

Supported file types:

.astro - Astro components
.mdx / .md - Markdown/MDX content
.tsx / .jsx - React components
.vue - Vue components
.svelte - Svelte components
.ts / .js - TypeScript/JavaScript

Examples:

Add a new page:

---
import ProtectedLayout from "@/layouts/ProtectedLayout.astro";
const recordId = Astro.locals.recordId;
---

<ProtectedLayout title="Billing">
   <h1>Billing Information</h1>
   <p>User {recordId}'s billing details</p>
</ProtectedLayout>

Automatically accessible at: /{memberid}/billing

Nested static folder:

---
import ProtectedLayout from "@/layouts/ProtectedLayout.astro";
const recordId = Astro.locals.recordId;
---

<ProtectedLayout title="Sample">
   <h1>Sample Page</h1>
   <p>Static route for {recordId}</p>
</ProtectedLayout>

Automatically accessible at: /{memberid}/folder-1/sample

Using dynamic routes:

---
import ProtectedLayout from "@/layouts/ProtectedLayout.astro";
const { page } = Astro.params;
const recordId = Astro.locals.recordId;
---

<ProtectedLayout title={page}>
   <h1>{page}</h1>
   <p>Dynamic page for {recordId}</p>
</ProtectedLayout>

Automatically accessible at: /{memberid}/[dynamic-page-value]/sample

Folder structure example:

[memberid]/
├── index.astro                    → /{memberid}/
├── dashboard.astro                → /{memberid}/dashboard
├── billing.astro                  → /{memberid}/billing
├── [page]/
│   └── sample.astro              → /{memberid}/[dynamic-page-value]/sample
└── static-folder/
    └── static-page.astro         → /{memberid}/static-folder/static-page

Customizing Layouts

The template includes base layouts that you should customize for your needs:

AuthLayout.astro

This layout wraps all authentication pages. You can customize the styling and page structure, but do not remove data-mindfulauth-* attributes..

DO NOT DELETE these scripts:

<script src="https://cdn.mindfulauth.com/astro/main.js"></script>
<script is:inline src="https://challenges.cloudflare.com/turnstile/v0/api.js"></script>

The first script handles core authentication functionality, and the second provides Turnstile protection for public forms.

ProtectedLayout.astro

This layout wraps all protected pages and includes the navigation bar. You should customize the navigation structure and styling to match your design.

DO NOT DELETE the Mindful Auth CDN script:

<script src="https://cdn.mindfulauth.com/astro/main.js"></script>

This script handles logout functionality and other critical authentication features.

Route Configuration

Route configuration (public routes, protected routes, and security headers) is managed by the @mindfulauth/core library and configured in src/middleware.ts.

If you need to add public pages to your portal (marketing pages, documentation, etc.), keep the portal strictly for authenticated users. Instead:

Host public content on your main website (e.g., mysite.com)
Keep the portal (e.g., portal.mysite.com) exclusively for authenticated users

This approach:

Keeps authentication logic simple and secure
Provides a clear separation between public and authenticated content
Prevents accidental security vulnerabilities from misconfiguration

Security Features

Server-side session validation: All protected routes validated before rendering
Path sanitization: Prevents directory traversal attacks
Request timeouts: Prevents hanging connections
Secure headers: CSP, HSTS, X-Frame-Options, etc.
HttpOnly cookies: Session cookies not accessible via JavaScript
CSRF protection: Via Mindful Auth’s Turnstile integration