Design and implement an authentication & role-based authorization architecture for the dashboard

[Lakes41]

Difficulty: Expert
Type: security

Background
The GuildPass dashboard manages admin controls and gated community experiences, but per the README, local development currently requires no environment variables and runs entirely on mock data — implying there's no real authentication layer wired in yet.

Problem
Without a real auth architecture, every admin control (guild creation, member/pass management, settings) is effectively unprotected once a real backend is introduced, and there's no defined session/role model to build authorization checks on top of.

Expected outcome
A documented, implemented authentication architecture (e.g., NextAuth.js with a credentials/OAuth provider, or a JWT-based session system) establishes user identity, and a role-based authorization layer (owner/admin/moderator/member, scoped per guild) gates every sensitive route and server action.

Suggested implementation

• Choose and integrate an auth solution appropriate for Next.js 14 App Router (e.g., NextAuth.js with JWT sessions).
• Design a role model: global roles vs. per-guild roles (a user can be admin in Guild A and a plain member in Guild B).
• Add middleware (Next.js middleware.ts) that protects /dashboard, /passes, /guilds, /members, /activity, /settings behind authentication.
• Add a server-side authorization helper (e.g., requireRole(guildId, minRole)) used in server actions and route handlers, not just hidden in the UI.
• Update .env.example with the new required auth-related environment variables and update README.md's environment variables section accordingly.
• Write an architecture doc in docs/ covering session strategy, role model, and how future backend integration should respect it.

Acceptance criteria

• Unauthenticated users are redirected away from all protected routes
• Role checks are enforced server-side, not just via conditional UI rendering
• Per-guild role scoping works (a user can have different roles in different guilds)
• .env.example and README updated to reflect new required configuration
• Architecture documented in docs/

Likely affected files/directories

• apps/dashboard/middleware.ts (new)
• apps/dashboard/app/**
• packages/integration-client/
• .env.example
• README.md
• docs/

[mr-abims]

Hello, i will like to work on this

[grantfox-oss]

🦊 GrantFox — @mr-abims has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #299)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.