feat(auth): OAuth2 role-based mailbox access for OAUTHBEARER

[Aravinda-HWK]

📌 Description

Adds OAuth2 role-based mailbox access to the OAUTHBEARER SASL flow. A token holder can authenticate to a shared role mailbox (e.g. support@example.com) when the validated JWT contains a matching entry in its roles (or role) claim. Personal mailbox authentication is unchanged.

• Closes [FEATURE] OAuth2 Authentication Support for Role-Based Email Access #273

---

🔍 Changes Made

• Parse roles (array or string) and singular role claims in extractClaims (internal/auth/oauthbearer/oauthbearer.go).
• Add EvaluateRoleAccess helper that returns a RoleAccessRequest (role, domain, mailbox identity role_<role>@<domain>.db) when the SASL user=<email> is a role address and the role appears in the token's roles. Case-insensitive; trims trailing dots from the domain.
• Wire role evaluation into the SASL server (internal/sasl/server.go) — falls back to role access when the SASL user does not match the resolved token email.
• Wire role evaluation into the IMAP AUTHENTICATE handler (internal/server/auth/auth.go) so the resolved mailbox identity is used for ExtractUsername and EnsureUserAndMailboxes, and stored on session state.
• Add unit tests covering claim extraction (array / string / singular role / missing) and EvaluateRoleAccess (match, case-insensitive, non-role address, missing @, empty roles, trailing-dot domain).

✅ Checklist (Email System)

• Core IMAP commands tested (LOGIN, CAPABILITY, LIST, SELECT, FETCH, LOGOUT).
• Authentication is tested.
• Docker build & run validated.
• Configuration loading verified for default and custom paths.
• Persistent storage with Docker volume verified.
• Error handling and logging verified.
• Documentation updated (README, config samples).

---

🧪 Testing Instructions

Unit tests:

go test ./internal/auth/oauthbearer/...

Manual / IMAP:

1. Issue an OAuth2 JWT whose roles claim contains support (or singular "role": "support").
2. From an IMAP client, AUTHENTICATE OAUTHBEARER with user=support@<your-domain> and the token above.
3. The server should authenticate the session against the shared mailbox identity role_support@<your-domain>.db — look for OAUTHBEARER: role-based access granted ... in the logs.
4. Repeat with a non-role personal address (e.g. alice@<your-domain>) — behaviour must be unchanged.
5. Negative case: SASL user=support@<your-domain> with a token whose roles do not include support must fail with Authentication failed.

Broader IMAP setup: see the test README.

---

📷 Screenshots / Logs (if applicable)

N/A — relevant log lines emitted by the new branches:

• OAUTHBEARER: role-based access granted token_user=... role=... mailbox=...
• SASL OAUTHBEARER: role-based access granted ...

---

⚠️ Notes for Reviewers

• The mailbox identity format role_<role>@<domain>.db is chosen to align with the role-mailbox naming used by the socketmap path in 271 feature support role based email validation in socketmap user exist check #272 — please flag if a different convention is preferred.
• EvaluateRoleAccess returns nil for anything that is not exactly role@domain, so personal-mailbox auth always falls through to the existing equality check (no behaviour change for non-role logins).
• No config or schema changes; no new dependencies.

[gemini-code-assist]

Code Review

This pull request introduces role-based mailbox access for OAUTHBEARER authentication by extracting roles from JWT claims and evaluating access for role-based SASL identities. Feedback highlights critical security concerns, including a lack of domain validation in EvaluateRoleAccess that could lead to unauthorized cross-domain access and a potential path traversal vulnerability due to unsanitized input in mailbox identity construction. Additionally, a minor code improvement was suggested to remove redundant whitespace trimming.

[maneesha-xyz]

Lgtm.