[PB-6134]: feat/stalwart admin api principals by jzunigax2 · Pull Request #7 · internxt/mail-server

jzunigax2 · 2026-03-24T02:59:08Z

Add StalwartService, HTTP client for the Stalwart admin REST API (principals CRUD via undici/HTTP2)
Add StalwartAccountProvider extending AccountProvider port, maps account operations to Stalwart principal operations
Add AccountService with address management: add/remove addresses, set primary (delete+recreate principal for rename), delete account with provider cleanup and rollback on failure
Add repositories (AccountRepository, AddressRepository, DomainRepository) with Sequelize queries and provider link tracking
Add domain models (MailAccount, MailAddress, MailDomain) with builder pattern
Unit tests for AccountService, StalwartAccountProvider, and StalwartService

apsantiso · 2026-03-25T15:45:57Z

src/modules/account/account.service.ts

+    const principalName = this.requirePrincipalName(account);
+
+    await this.provider.removeAddress(principalName, address);
+    await Promise.all([
+      this.addresses.deleteProviderLink(addressRecord.id),
+      this.addresses.delete(addressRecord.id),
+    ]);
+
+    this.logger.log(
+      `Removed address '${address}' from account '${driveUserUuid}'`,
+    );
+  }


It is somehow hard to wrap my head around this concept as you're using stalwart's implementation names (principal name) in the bussiness layer instead of our domain names such as mainAddress/primaryAddress, I may be wrong tho.

you are right, my bad. some methods existed before creating our domain names and missed renaming variables creating this odd mix of domain names and stalwart names. addressed

apsantiso · 2026-03-25T15:52:22Z

src/modules/infrastructure/stalwart/stalwart-account.provider.ts

@@ -0,0 +1,91 @@
+import { Injectable, Logger } from '@nestjs/common';


A quick tip if you feel this module gets too big: instead of /modules/infrastructure, you can create a infrastructure folder in the module that requires this service.

Each module can have its own bussiness (usecases), infrastructure (external services, controllers), domain layers it you think things get too crazy. We do not follow a hardcore ports/adapters structure as we tend to be more pragmatic, so it is always up to you @jzunigax2

hmm lets wait and see how it evolves, I would think we wont need to add much to /infrastructure

apsantiso · 2026-03-25T15:54:47Z

src/modules/account/repositories/address.repository.ts

+  async delete(id: string): Promise<void> {
+    await this.addressModel.destroy({ where: { id } });
+  }


Beware of hard deletes here. We're handling emails so we might want to use soft deletes just in case. You can enable the paranoid option so sequelize handles automatically this for you (by setting a deleted_at), you'll probably need to modify your existent migrations tho

I suggested the paranoid option but let's see what @sg-gs thinks

paranoid sounds good, I added it to mail-addresses and mail-accounts. let me know if that sounds good to you

sg-gs

There are js imports across multiple files @jzunigax2.

Btw, there is a ton heck of code here, let's avoid this gigantic PRs

sg-gs · 2026-03-26T09:35:14Z

src/modules/account/domain/mail-account.domain.ts

+
+export interface MailAccountAttributes {
+  id: string;
+  driveUserUuid: string;


The user's uuid is common over all the services (drive, network, payments, meet...), therefore, this wording is not accurate. It's better to use userId, as also the format is something not relevant, as the type itself clarifies that is not the incremental id, that btw, we will eventually remove

you are right, addressed

sg-gs · 2026-03-26T09:38:03Z

src/modules/account/domain/mail-address.domain.ts

+  address: string;
+  domainId: string;
+  isDefault: boolean;
+  providerExternalId: string | null;


How can this be null?

right, it really should never be.. Made it non-nullable. Each address always has a provider link

sg-gs · 2026-03-26T09:44:17Z

src/modules/account/domain/mail-domain.domain.ts

+export interface MailDomainAttributes {
+  id: string;
+  domain: string;
+  status: string;


Should this status be an enum?

added MailDomainStatus enum with Active and Inactive values

sg-gs · 2026-03-26T09:52:57Z

src/modules/account/repositories/account.repository.ts

@@ -0,0 +1,43 @@
+import { Injectable } from '@nestjs/common';
+import { InjectModel } from '@nestjs/sequelize';
+import { MailAccount } from '../domain/mail-account.domain.js';


Shouldn't this be typescript files?

see #7 (comment)

sg-gs · 2026-03-26T09:53:22Z

src/modules/account/repositories/account.repository.ts

+    private readonly accountModel: typeof MailAccountModel,
+  ) {}
+
+  async findByDriveUserUuid(uuid: string): Promise<MailAccount | null> {


findByUserId

sg-gs · 2026-03-26T10:14:21Z

src/modules/infrastructure/stalwart/stalwart-account.provider.ts

+  ): Promise<void> {
+    // Stalwart uses the principal name as the login.
+    // Changing the primary address means renaming the principal.
+    // Current REST API does not support rename — we must recreate.


Maybe we should use a principal handled by us consisting on the user uuid and the mail extension so we prevent these things. Also, which are the consequences of recreating? Would other addresses or the mailbox be deleted from Stalwart?

recreating would lose all stored emails and mailbox data since the new principal gets a fresh internal id. however this isn't actually needed this was left over code from an earlier iteration, each address is its own principal, so there's no rename scneario now.

Removed setPrimaryAddress from the provider entirely, it's now a DB-only operation. Also removed addAddress/removeAddress from the port since adding/removing an address means creating/deleting a whole principal via createAccount/deleteAccount rather than adding them as aliasses.

Yeah, it's better, if possible, to decouple a rename on our UI to a rename on the Mail tool itself, if possible

jzunigax2 · 2026-03-26T20:59:52Z

There are js imports across multiple files @jzunigax2.

Btw, there is a ton heck of code here, let's avoid this gigantic PRs

hey @sg-gs the project uses nodenext for compiler options compilerOptions.module and compilerOptions.moduleResolution, with these options, TypeScript expects the relative import specifiers to match what Node will resolve from the compiled dist files (which are .js) so the extensions are required.

as for the big PR you are right, my bad. initially this was supposed to only include the stalwart api abstraction and I made the mistake to keep building on top of this to see how it would shape out

- Added AccountProvider interface for managing email accounts with methods for creating, deleting, and updating accounts and addresses. - Implemented StalwartAccountProvider class to interact with the Stalwart service for account management. - Introduced CreateAccountParams and AccountInfo types for structured account data handling. - Created StalwartService to manage API interactions with the Stalwart backend, including principal creation, retrieval, and updates. - Established StalwartModule to provide the StalwartAccountProvider as a dependency for other modules.

- Replaced adminToken with adminUser and adminSecret in the configuration. - Updated StalwartService to use basic authentication with adminUser and adminSecret instead of bearer token. - Adjusted headers method to include basic auth credentials for API requests.

- Introduced AccountProvider interface for managing email accounts, including methods for creating, deleting, and updating accounts and addresses. - Added AccountService to handle business logic for account operations, including address management and primary address setting. - Created repositories for account, address, and domain management, integrating with Sequelize for data persistence. - Defined domain models for MailAccount, MailAddress, and MailDomain to structure account-related data. - Updated .env.template to include new configuration parameters for Stalwart account management.

- Introduced comprehensive unit tests for AccountService, covering account retrieval, deletion, and address management functionalities. - Added unit tests for StalwartAccountProvider, validating account creation, deletion, and address manipulation methods. - Updated ESLint configuration to disable unbound-method rule for test files. - Enhanced test fixtures to support new account and address attributes for improved test coverage.

…ables - Introduced migrations to add a nullable deleted_at column to both mail_accounts and mail_addresses tables for soft deletion functionality. - Updated the MailAccount and MailAddress models to include the deletedAt field with paranoid option enabled for Sequelize. - Refactored AccountService to replace references from principalName to providerAccountId for consistency in account management.

- Created a migration to rename the column drive_user_uuid to user_id in the mail_accounts table for improved clarity and consistency. - Updated related code in seeders, services, and repositories to reflect the new user_id field. - Adjusted unit tests to ensure proper functionality with the updated user identification method.

…hods - Removed addAddress, removeAddress, and setPrimaryAddress methods from the AccountProvider interface and StalwartAccountProvider implementation to streamline account management. - Updated AccountService to handle address management directly, ensuring proper deletion and linking of addresses during account operations. - Adjusted related unit tests to reflect the changes in address handling and account deletion processes.

sonarqubecloud · 2026-03-27T12:29:53Z

Quality Gate failed

Failed conditions
71.8% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

jzunigax2 requested review from apsantiso and sg-gs March 24, 2026 02:59

jzunigax2 self-assigned this Mar 24, 2026

jzunigax2 added the enhancement New feature or request label Mar 24, 2026

jzunigax2 force-pushed the feat/stalwart-admin-api-principals branch from e31054d to 1a01822 Compare March 25, 2026 02:33

jzunigax2 changed the title ~~Feat/stalwart admin api principals~~ [PB-6134]: feat/stalwart admin api principals Mar 25, 2026

jzunigax2 marked this pull request as ready for review March 25, 2026 03:31

apsantiso reviewed Mar 25, 2026

View reviewed changes

apsantiso approved these changes Mar 25, 2026

View reviewed changes

sg-gs requested changes Mar 26, 2026

View reviewed changes

jzunigax2 force-pushed the feat/stalwart-admin-api-principals branch from 5046358 to 2919836 Compare March 26, 2026 16:30

jzunigax2 requested a review from sg-gs March 26, 2026 21:09

sg-gs approved these changes Mar 27, 2026

View reviewed changes

Base automatically changed from feat/sequelize-models-wiring to master March 27, 2026 12:17

jzunigax2 added 7 commits March 27, 2026 06:28

jzunigax2 force-pushed the feat/stalwart-admin-api-principals branch from 3efc3a3 to ec2b9e9 Compare March 27, 2026 12:28

jzunigax2 merged commit 990bf15 into master Mar 27, 2026
4 of 5 checks passed

jzunigax2 deleted the feat/stalwart-admin-api-principals branch March 27, 2026 12:31

		@@ -0,0 +1,91 @@
		import { Injectable, Logger } from '@nestjs/common';

Conversation

jzunigax2 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apsantiso Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sg-gs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jzunigax2 Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jzunigax2 commented Mar 26, 2026

Uh oh!

sonarqubecloud bot commented Mar 27, 2026

Quality Gate failed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jzunigax2 commented Mar 24, 2026 •

edited

Loading

apsantiso Mar 25, 2026 •

edited

Loading

jzunigax2 Mar 26, 2026 •

edited

Loading