242 task add group email support to raven lmtp

[Aravinda-HWK]

📌 Description

This PR implements group email delivery support in Raven's LMTP server. When an email is addressed to a group email (format: <group_name>-group@<domain_name>), the system now resolves all member users (including recursively nested groups), deduplicates the final recipient list, and delivers the email to each user's individual mailbox.

• Closes [TASK] Add group email support to Raven LMTP #242

---

🔍 Changes Made

• Added group email address detection in the LMTP delivery handler using the <group_name>-group@<domain> pattern
• Implemented IDP authentication flow to obtain a system-scoped Bearer assertion (two-step: flow initiation → credential submission)
• Implemented group lookup by name via GET /groups and member resolution via GET /groups/{group_id}/members
• Added recursive group resolution to handle nested groups, with cycle detection to guard against circular group membership
• Integrated resolveDomainFromOrganizationUnit (from internal/server/auth/auth.go) to build fully qualified email addresses for resolved users
• Deduplicated the final recipient list before delivery
• Delivered and stored the email in each resolved user's mailbox using the existing LMTP delivery path
• Added assertion caching with JWT exp-based expiry to avoid re-authenticating on every delivery

---

✅ 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)
• Group email detection correctly parses <group_name>-group@<domain> format
• Single-level group email resolves to correct member mailboxes
• Nested group email resolves recursively to all leaf users
• Circular group references are handled without infinite loops
• Duplicate recipients across nested groups are deduplicated before delivery
• LMTP returns a proper error response if IDP is unreachable or group is not found
• IDP assertion is cached and reused within its expiry window
• Application ID is read from environment variable (not hardcoded)

---

🧪 Testing Instructions

To test the server, use the instructions in the README in the test directory.

Group email specific scenarios to verify:

1. Basic group delivery — Send an email to testgroup-group@<domain>. Confirm it arrives in each direct member's mailbox.
2. Nested group delivery — Ensure a group containing another group delivers to all leaf users in both groups.
3. Duplicate deduplication — Place a user in two groups that are both members of a parent group. Confirm the user receives only one copy of the email.
4. Circular group guard — If Group A contains Group B and Group B contains Group A, confirm the resolution terminates cleanly without an infinite loop.
5. IDP unavailable — Bring down the IDP and send a group email. Confirm a proper LMTP error is returned and no silent drop occurs.
6. Non-existent group — Send to unknown-group@<domain>. Confirm appropriate error handling.

---

📷 Screenshots / Logs (if applicable)

---

⚠️ Notes for Reviewers

• The IDP base URL is derived from auth_server_url in config/raven.yaml by stripping the /auth/credentials/authenticate path suffix.
• The application ID used for the IDP authentication flow is injected as an environment variable via Docker Compose — ensure it is set in your local environment before testing.
• The assertion caching mechanism relies on the exp claim in the JWT. If clock skew is a concern in your environment, a small buffer (e.g. 30s) before expiry is advisable.
• resolveDomainFromOrganizationUnit in internal/server/auth/auth.go is reused as-is — no changes were made to that function.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant new feature to the Raven LMTP server: the ability to deliver emails to group addresses. This enhancement allows the system to dynamically resolve group members from an external Identity Provider, handle complex group structures including nesting and circular references, and ensure efficient delivery to all intended individual recipients. The changes streamline email management for organizations using group aliases by automating recipient expansion and delivery.

Highlights

• Group Email Delivery: Implemented support for group email delivery in Raven's LMTP server, allowing emails addressed to <group_name>-group@<domain_name> to be resolved and delivered to all individual members, including those in nested groups.
• IDP Integration for Group Resolution: Integrated with an Identity Provider (IDP) to authenticate, look up groups by name, fetch group members, and resolve user email addresses, including deriving domains from organizational units.
• Recursive Group Resolution and Deduplication: Developed logic for recursively resolving members of nested groups, incorporating cycle detection to prevent infinite loops and deduplicating the final list of recipients to ensure each user receives only one copy of the email.
• Assertion Caching: Added a caching mechanism for IDP assertions, using JWT exp-based expiry to minimize re-authentication requests and improve performance.
• Configuration Enhancements: Updated the delivery service configuration to load IDP base URL and domain from the main raven.yaml file, making group resolution configurable.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces group email support, a significant feature enhancement. The implementation involves a new groupresolver package to handle communication with an IDP for resolving group members recursively. The changes are comprehensive, including configuration loading, authentication assertion caching, and integration into the LMTP session handling.

My review has identified two critical security vulnerabilities: the use of InsecureSkipVerify: true which disables TLS verification, and the use of default credentials for the IDP system user. These must be addressed. Additionally, I've noted several medium-severity issues related to code duplication, missing or incomplete tests for the new functionality, and areas where robustness could be improved, such as error handling and concurrency patterns. Addressing these points will greatly improve the security, maintainability, and reliability of this new feature.

[maneeshaxyz]

LGTM.