alla-allaos-fullstack/plans/task-p.7.2.md

Task P.7.2 – SMTP / Email Configuration Platform

Objective

Implement a secure SMTP / Email Configuration Platform for ALLA OS.

The goal is to let administrators configure, verify, and use outbound email safely for system notifications such as approval alerts, password reset, invitation emails, setup warnings, and future workflow notifications.

This task must integrate with the existing Setup Platform as an optional readiness/verification step.

Email configuration must not block First-run Setup unless explicitly required by the selected installation profile.

---

Review Before Implementation

Review:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/ui-ux-rules.md
• docs/standards/task-review-checklist.md
• docs/setup/verification-matrix.md
• docs/setup/setup-wizard-blueprint.md
• docs/setup/installation-profiles.md
• src/features/setup/**
• src/features/foundation/notifications/**
• src/app/api/setup/readiness/route.ts
• src/app/api/setup/verify/route.ts
• src/db/schema.ts
• existing Auth.js password reset / invitation flow if present

---

Scope

Create email configuration foundation.

Required features:

• SMTP configuration CRUD
• Secure secret handling
• SMTP connection test
• Send test email
• Email provider readiness check
• Integration with Setup Readiness / Verification
• Optional Setup Wizard step
• Audit-safe reporting
• No secret exposure in API responses

---

Data Model

Add table:

email_configurations

Suggested fields:

id

organization_id nullable

provider_type

name

host

port

secure

username

password_encrypted

from_email

from_name

reply_to_email

is_default

is_active

last_test_status

last_tested_at

last_test_error

created_by

updated_by

created_at

updated_at

Provider type values:

smtp

future values:

sendgrid ses mailgun microsoft_graph

---

Secret Handling

SMTP password must never be stored as plain text.

Use existing encryption utility if available.

If none exists, create foundation crypto helper:

src/features/foundation/secrets/server/crypto.ts

Rules:

• encryption key from environment variable
• missing key blocks saving password
• API never returns password_encrypted
• UI shows password as "configured" or "not configured"
• password can be replaced, not read

Required environment:

EMAIL_CONFIG_ENCRYPTION_KEY

Suggested validation:

• minimum 32 bytes
• base64 or hex recommended

---

Server Services

Create:

src/features/foundation/email/server/email-config.service.ts src/features/foundation/email/server/email-test.service.ts src/features/foundation/email/server/email-provider.ts src/features/foundation/email/server/smtp-provider.ts

Responsibilities:

email-config.service.ts

• list configs
• get config
• create config
• update config
• delete/deactivate config
• set default config
• validate config
• mask secret output

email-test.service.ts

• test SMTP connection
• send test email
• update last_test_status
• update last_tested_at
• store safe last_test_error

email-provider.ts

• provider interface

smtp-provider.ts

• nodemailer implementation or existing mail library integration

---

Provider Interface

export interface EmailProvider {
  testConnection(config: EmailProviderConfig): Promise<EmailTestResult>;
  sendEmail(input: SendEmailInput): Promise<SendEmailResult>;
}