193 lines
3.3 KiB
Markdown
193 lines
3.3 KiB
Markdown
# 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
|
||
|
||
```ts
|
||
export interface EmailProvider {
|
||
testConnection(config: EmailProviderConfig): Promise<EmailTestResult>;
|
||
sendEmail(input: SendEmailInput): Promise<SendEmailResult>;
|
||
}
|