setup email

plans/task-p.7.2.md

@@ -0,0 +1,192 @@
+# 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>;
+}