erik/slugkit

Fork 0

Send magic links through SMTP email #197

New issue

Closed

opened 2026-06-23 22:47:41 -05:00 by erik · 3 comments

erik commented

2026-06-23 22:47:41 -05:00

Owner

Goal

Add real SMTP email delivery for magic-link authentication so production sites can send login links by email instead of relying on dev-mode log output.

Requirements

Add SMTP configuration for the template site using environment variables.
Document required SMTP settings for production and how they differ from AUTH_DEV_MODE=true local behavior.
Implement an email delivery path that sends the magic login link to the requested address when dev mode is disabled.
Preserve the current local development behavior where AUTH_DEV_MODE=true logs magic links instead of sending email.
Fail clearly when email delivery is required but SMTP configuration is missing or invalid.
Include tests for SMTP configuration, successful magic-link email delivery, dev-mode logging behavior, and missing/invalid SMTP configuration.

Acceptance criteria

Production-style configuration can send a magic-link email via SMTP.
AUTH_DEV_MODE=true still logs the magic link and does not require SMTP.
Missing SMTP configuration with dev mode disabled returns a clear error and does not silently drop the login link.
SMTP host, port, authentication, TLS/secure mode, sender address, and sender name are configurable.
Template .env.example and setup documentation explain SMTP configuration and magic-link delivery.
Tests cover SMTP delivery success, dev-mode behavior, and configuration failure cases.

Dependencies

None

## Goal Add real SMTP email delivery for magic-link authentication so production sites can send login links by email instead of relying on dev-mode log output. ## Requirements - Add SMTP configuration for the template site using environment variables. - Document required SMTP settings for production and how they differ from `AUTH_DEV_MODE=true` local behavior. - Implement an email delivery path that sends the magic login link to the requested address when dev mode is disabled. - Preserve the current local development behavior where `AUTH_DEV_MODE=true` logs magic links instead of sending email. - Fail clearly when email delivery is required but SMTP configuration is missing or invalid. - Include tests for SMTP configuration, successful magic-link email delivery, dev-mode logging behavior, and missing/invalid SMTP configuration. ## Acceptance criteria - [ ] Production-style configuration can send a magic-link email via SMTP. - [ ] `AUTH_DEV_MODE=true` still logs the magic link and does not require SMTP. - [ ] Missing SMTP configuration with dev mode disabled returns a clear error and does not silently drop the login link. - [ ] SMTP host, port, authentication, TLS/secure mode, sender address, and sender name are configurable. - [ ] Template `.env.example` and setup documentation explain SMTP configuration and magic-link delivery. - [ ] Tests cover SMTP delivery success, dev-mode behavior, and configuration failure cases. ## Dependencies - None

erik added the

labels

2026-06-23 22:47:41 -05:00

erik commented

2026-06-23 23:04:20 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-24T04:03:25.560Z

PR review completed for slugkit PR #198.

Result: approved

Acceptance criteria: 6/6 met, 0 missing.

Verification:

Reviewed task scope, PR body, and diff for SMTP-backed magic-link delivery.
Local targeted tests passed: npm exec --workspace @slugkit/template-site -- vitest run --config ../../vitest.config.ts src/auth/__tests__/delivery.test.ts src/auth/__tests__/magic-links.test.ts src/routes/__tests__/auth.test.ts (3 files, 23 tests).
Local full gate passed: ./scripts/pre-pr.sh (format, lint, typecheck, all workspace tests: 49 files, 369 tests).
Forgejo Actions #275 succeeded for commit a322fd6685 (build-lint-test, pull_request).

Blocking issues: none.
Warnings: none.

PR review comment posted. Merge gate remains waiting for explicit human approval.

_Synced from todu comment by @todu on 2026-06-24T04:03:25.560Z_ PR review completed for slugkit PR #198. Result: approved Acceptance criteria: 6/6 met, 0 missing. Verification: - Reviewed task scope, PR body, and diff for SMTP-backed magic-link delivery. - Local targeted tests passed: `npm exec --workspace @slugkit/template-site -- vitest run --config ../../vitest.config.ts src/auth/__tests__/delivery.test.ts src/auth/__tests__/magic-links.test.ts src/routes/__tests__/auth.test.ts` (3 files, 23 tests). - Local full gate passed: `./scripts/pre-pr.sh` (format, lint, typecheck, all workspace tests: 49 files, 369 tests). - Forgejo Actions #275 succeeded for commit `a322fd6685` (`build-lint-test`, pull_request). Blocking issues: none. Warnings: none. PR review comment posted. Merge gate remains waiting for explicit human approval.

erik commented

2026-06-23 23:54:12 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-24T04:53:11.929Z

PR review completed for slugkit PR #198 after update 9f2d44d.

Result: approved

Acceptance criteria: 6/6 met, 0 missing.

Verification:

Reviewed updated PR diff and commit 9f2d44d.
Confirmed AUTH_DEV_MODE=false now forces SMTP delivery even when NODE_ENV is non-production.
Confirmed test coverage was updated for explicit dev-mode disabling under NODE_ENV=development.
Local targeted tests passed: npm exec --workspace @slugkit/template-site -- vitest run --config ../../vitest.config.ts src/auth/__tests__/delivery.test.ts src/auth/__tests__/magic-links.test.ts src/routes/__tests__/auth.test.ts (3 files, 23 tests).
Local full gate passed: ./scripts/pre-pr.sh (format, lint, typecheck, all workspace tests: 49 files, 369 tests).
Forgejo Actions #276 succeeded for commit 9f2d44d (build-lint-test, pull_request).
Manual SMTP validation: after updating the local Migadu password and restarting dev, the app is configured to use SMTP rather than logging links.

Blocking issues: none.
Warnings: none.

Merge gate: waiting for explicit human merge approval.

_Synced from todu comment by @todu on 2026-06-24T04:53:11.929Z_ PR review completed for slugkit PR #198 after update `9f2d44d`. Result: approved Acceptance criteria: 6/6 met, 0 missing. Verification: - Reviewed updated PR diff and commit `9f2d44d`. - Confirmed `AUTH_DEV_MODE=false` now forces SMTP delivery even when `NODE_ENV` is non-production. - Confirmed test coverage was updated for explicit dev-mode disabling under `NODE_ENV=development`. - Local targeted tests passed: `npm exec --workspace @slugkit/template-site -- vitest run --config ../../vitest.config.ts src/auth/__tests__/delivery.test.ts src/auth/__tests__/magic-links.test.ts src/routes/__tests__/auth.test.ts` (3 files, 23 tests). - Local full gate passed: `./scripts/pre-pr.sh` (format, lint, typecheck, all workspace tests: 49 files, 369 tests). - Forgejo Actions #276 succeeded for commit `9f2d44d` (`build-lint-test`, pull_request). - Manual SMTP validation: after updating the local Migadu password and restarting dev, the app is configured to use SMTP rather than logging links. Blocking issues: none. Warnings: none. Merge gate: waiting for explicit human merge approval.

erik

2026-06-23 23:59:49 -05:00

closed this issue
added
status:done
and removed
status:active
labels

erik commented

2026-06-23 23:59:49 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-24T04:54:13.183Z

Completed and merged in slugkit PR #198.

Acceptance criteria: 6/6 met.

Evidence:

Added SMTP-backed magic-link delivery with environment configuration for host, port, secure/TLS mode, auth credentials, sender email, and sender name.
Preserved AUTH_DEV_MODE=true log-link behavior.
Fixed explicit AUTH_DEV_MODE=false so it forces SMTP even under non-production NODE_ENV.
Missing/invalid required SMTP config uses a clear delivery-not-configured path and does not silently keep a failed login link.
Updated template/site/.env.example and template/site/README.md.
Tests cover SMTP success, dev-mode logging, and config failure cases.
Verification passed: targeted auth tests, ./scripts/pre-pr.sh, and Forgejo Actions #276.
PR #198 merged into main and local main fast-forwarded.

_Synced from todu comment by @todu on 2026-06-24T04:54:13.183Z_ Completed and merged in slugkit PR #198. Acceptance criteria: 6/6 met. Evidence: - Added SMTP-backed magic-link delivery with environment configuration for host, port, secure/TLS mode, auth credentials, sender email, and sender name. - Preserved `AUTH_DEV_MODE=true` log-link behavior. - Fixed explicit `AUTH_DEV_MODE=false` so it forces SMTP even under non-production `NODE_ENV`. - Missing/invalid required SMTP config uses a clear delivery-not-configured path and does not silently keep a failed login link. - Updated `template/site/.env.example` and `template/site/README.md`. - Tests cover SMTP success, dev-mode logging, and config failure cases. - Verification passed: targeted auth tests, `./scripts/pre-pr.sh`, and Forgejo Actions #276. - PR #198 merged into `main` and local `main` fast-forwarded.