ReviewOS

also looking at this

mail-os/mail

feat: mailbox recovery addresses and password reset by email

#13
Merged chris wants to merge feat/mailbox-recovery into main
21 files +1503 -10
packages/zig/src/api/webmail_http.zigmodified+296-0
Changes to packages/zig/src/api/webmail_http.zig
@@ -8,6 +8,12 @@
88//! POST /webmail/auth/login {username,password} -> sets session cookie
99//! POST /webmail/auth/logout -> clears cookie
1010//! GET /webmail/auth/me -> {user}
11//! POST /webmail/auth/forgot {address} -> always {ok:true}; mails a reset
12//! link to the mailbox's recovery address
13//! POST /webmail/auth/reset/verify {token} -> {account} | 400 invalid_token
14//! POST /webmail/auth/reset {token,password} -> sets the new password
15//! GET /webmail/auth/recovery -> {recovery,setBy}
16//! PUT /webmail/auth/recovery {currentPassword,recovery} -> changes it
1117//! GET /webmail/api/folders -> [{name,total,unread}]
1218//! GET /webmail/api/messages?folder=&page=&per_page= -> {items,total,page}
1319//! GET /webmail/api/messages/:uid?folder= -> {message}
@@ -41,12 +47,14 @@ const store = @import("webmail_store.zig");
4147const threads = @import("webmail_threads.zig");
4248const ascii_compat = @import("ascii-compat");
4349const caldav_store = @import("../storage/caldav_store.zig");
50const recovery = @import("webmail_recovery.zig");
4451
4552// SPA static assets, rendered by packages/webmail/build.ts into webmail_dist/
4653// (gitignored, regenerated by `zig build`) and baked into the binary so the whole
4754// webmail UI ships as one executable — same single-binary model as admin.html.
4855const index_html = @embedFile("webmail_dist/index.html");
4956const login_html = @embedFile("webmail_dist/login.html");
57const recover_html = @embedFile("webmail_dist/recover.html");
5058const styles_css = @embedFile("webmail_dist/styles.css");
5159
5260pub const WebmailHttpConfig = struct {
@@ -86,6 +94,10 @@ pub const WebmailHttpServer = struct {
8694 /// Throttles login attempts per IP to blunt credential brute-forcing.
8795 /// Its own internal mutex makes it safe to share across connection threads.
8896 login_limiter: security.RateLimiter,
97 /// Throttles the unauthenticated password reset endpoints per IP: asking
98 /// for links (by IP) and presenting tokens (by "token:<ip>"). The per
99 /// mailbox cap on links sent lives in the database (webmail_recovery.zig).
100 reset_limiter: security.RateLimiter,
89101 /// Loaded once at init when TLS is enabled (shared read-only across threads).
90102 cert_key_pair: ?tls.config.CertKeyPair = null,
91103 listener: ?socket.Server = null,
@@ -125,6 +137,7 @@ pub const WebmailHttpServer = struct {
125137 config.login_rate_max,
126138 config.login_rate_window_seconds,
127139 ),
140 .reset_limiter = security.RateLimiter.init(allocator, 15 * 60, 10, 30, 15 * 60),
128141 .running = std.atomic.Value(bool).init(false),
129142 };
130143 if (config.enable_tls and config.tls_cert_path != null and config.tls_key_path != null) {
@@ -145,6 +158,7 @@ pub const WebmailHttpServer = struct {
145158 pub fn deinit(self: *WebmailHttpServer) void {
146159 self.stop();
147160 self.login_limiter.deinit();
161 self.reset_limiter.deinit();
148162 }
149163
150164 pub fn start(self: *WebmailHttpServer) !void {
@@ -455,6 +469,21 @@ fn handleConnection(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena
455469 if (std.mem.eql(u8, p, "/webmail/auth/me") and std.mem.eql(u8, req.method, "GET")) {
456470 return handleMe(server, conn, arena, req);
457471 }
472 if (std.mem.eql(u8, p, "/webmail/auth/forgot") and std.mem.eql(u8, req.method, "POST")) {
473 return handleForgot(server, conn, arena, req);
474 }
475 if (std.mem.eql(u8, p, "/webmail/auth/reset/verify") and std.mem.eql(u8, req.method, "POST")) {
476 return handleResetVerify(server, conn, arena, req);
477 }
478 if (std.mem.eql(u8, p, "/webmail/auth/reset") and std.mem.eql(u8, req.method, "POST")) {
479 return handleResetComplete(server, conn, arena, req);
480 }
481 if (std.mem.eql(u8, p, "/webmail/auth/recovery") and std.mem.eql(u8, req.method, "GET")) {
482 return handleRecoveryGet(server, conn, arena, req);
483 }
484 if (std.mem.eql(u8, p, "/webmail/auth/recovery") and std.mem.eql(u8, req.method, "PUT")) {
485 return handleRecoveryUpdate(server, conn, arena, req);
486 }
458487 if (std.mem.eql(u8, p, "/webmail/api/compose") and std.mem.eql(u8, req.method, "POST")) {
459488 return handleCompose(server, conn, arena, req);
460489 }
@@ -495,6 +524,10 @@ fn handleConnection(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena
495524 if (std.mem.eql(u8, p, "/login")) {
496525 return serveAsset(conn, arena, login_html, "text/html; charset=utf-8");
497526 }
527 // One page asks for a link (/forgot) and spends it (/reset#token=...).
528 if (std.mem.eql(u8, p, "/forgot") or std.mem.eql(u8, p, "/reset")) {
529 return serveAsset(conn, arena, recover_html, "text/html; charset=utf-8");
530 }
498531 if (std.mem.eql(u8, p, "/styles.css")) {
499532 return serveAsset(conn, arena, styles_css, "text/css; charset=utf-8");
500533 }
@@ -515,6 +548,9 @@ fn serveAsset(conn: *webmail_tls.Stream, arena: std.mem.Allocator, body: []const
515548 try w.writeAll("X-Frame-Options: DENY\r\n");
516549 if (std.mem.indexOf(u8, content_type, "text/html") != null) {
517550 try w.writeAll("Cache-Control: no-cache\r\n");
551 // A reset page carries its token in the URL fragment; no link on any
552 // page should hand the URL to another site.
553 try w.writeAll("Referrer-Policy: no-referrer\r\n");
518554 } else {
519555 try w.writeAll("Cache-Control: public, max-age=3600\r\n");
520556 }
@@ -681,6 +717,266 @@ fn handleMe(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.me
681717 try sendJson(conn, arena, 200, body.items, null);
682718}
683719
720// ── Password reset and recovery address ─────────────────────────────────────
721
722fn clientIp(req: Request, conn: *webmail_tls.Stream) []const u8 {
723 return if (req.trust_forwarded_headers) req.header("X-Real-IP") orelse conn.peerIp() else conn.peerIp();
724}
725
726/// The authority the browser used, as isSameOrigin reads it.
727fn requestHost(req: Request) ?[]const u8 {
728 return if (req.trust_forwarded_headers) req.header("X-Forwarded-Host") orelse req.header("Host") else req.header("Host");
729}
730
731/// Links point at https whenever the browser is on https: direct TLS here, or
732/// a TLS gateway in front of a listener that sets Secure cookies.
733fn publicHttps(server: *const WebmailHttpServer) bool {
734 return server.config.enable_tls or server.config.secure_cookies;
735}
736
737const SystemMail = struct {
738 server: *WebmailHttpServer,
739 arena: std.heap.ArenaAllocator,
740 message: compose.Message,
741 what: []const u8,
742 about: []const u8,
743};
744
745/// Deliver a server-written message off the request thread, so a reset
746/// request is answered in the same time whether or not anything is sent, and
747/// a slow remote MX cannot hold a connection open. Counted as an active
748/// connection so shutdown waits for it. Takes ownership of `job_arena`, which
749/// must hold every byte `message` points at.
750fn dispatchSystemMail(server: *WebmailHttpServer, job_arena: std.heap.ArenaAllocator, message: compose.Message, what: []const u8, about: []const u8) void {
751 var owned = job_arena;
752 const job = std.heap.page_allocator.create(SystemMail) catch {
753 owned.deinit();
754 logger.err("Webmail {s} for {s} not sent: out of memory", .{ what, about });
755 return;
756 };
757 job.* = .{ .server = server, .arena = owned, .message = message, .what = what, .about = about };
758 _ = server.active_connections.fetchAdd(1, .monotonic);
759 const thread = std.Thread.spawn(.{}, systemMailThread, .{job}) catch |err| {
760 _ = server.active_connections.fetchSub(1, .release);
761 logger.err("Webmail {s} for {s} not sent: {}", .{ what, about, err });
762 job.arena.deinit();
763 std.heap.page_allocator.destroy(job);
764 return;
765 };
766 thread.detach();
767}
768
769fn systemMailThread(job: *SystemMail) void {
770 const server = job.server;
771 defer {
772 job.arena.deinit();
773 std.heap.page_allocator.destroy(job);
774 _ = server.active_connections.fetchSub(1, .release);
775 }
776 const cfg = compose.SendConfig{
777 .hostname = server.config.hostname,
778 .delivery_method = server.config.delivery_method,
779 .ses_region = server.config.ses_region,
780 .sender_user = "",
781 .mail_config = server.config.mail_config,
782 .auth = server.auth,
783 };
784 compose.deliverSystem(job.arena.allocator(), job.message, cfg) catch |err| {
785 logger.warn("Webmail {s} for {s} could not be delivered: {}", .{ job.what, job.about, err });
786 return;
787 };
788 logger.info("Webmail {s} for {s} delivered to its recovery address", .{ job.what, job.about });
789}
790
791const reset_accepted = "{\"ok\":true}";
792
793/// A server-written message plus the mailbox it is about, both in a job arena.
794const Built = struct { message: compose.Message, about: []const u8 };
795
796/// POST /webmail/auth/forgot {address}
797///
798/// Always answers {ok:true}, whether or not the mailbox exists, has a recovery
799/// address, or was sent anything: the answer must not tell anyone which
800/// mailboxes exist. The link goes to the recovery address, never to the
801/// requester, and is sent from another thread so timing tells nothing either.
802fn handleForgot(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {
803 if (!isSameOrigin(req)) return sendError(conn, arena, 403, "forbidden", "Cross-origin request rejected");
804 const ip = clientIp(req, conn);
805 if (ip.len > 0 and !(server.reset_limiter.checkAndIncrement(ip) catch true)) {
806 logger.warn("Webmail password reset requests rate-limited for {s}", .{ip});
807 return sendError(conn, arena, 429, "rate_limited", "Too many requests. Please wait a few minutes.");
808 }
809 const raw = (try jsonStringFieldAlloc(arena, req.body, "address")) orelse return sendError(conn, arena, 400, "bad_request", "Enter your mailbox address");
810 const address = std.mem.trim(u8, raw, " \t\r\n");
811 if (address.len == 0 or address.len > 320) return sendError(conn, arena, 400, "bad_request", "Enter your mailbox address");
812 for (address) |c| if (c <= 0x20 or c == 0x7f) return sendError(conn, arena, 400, "bad_request", "Enter your mailbox address");
813
814 const username = try server.auth.canonicalUsername(address, arena);
815 const result = recovery.issue(arena, server.db, username, if (ip.len > 0) ip else null, time_compat.timestamp()) catch |err| {
816 logger.err("Webmail password reset for {s} failed: {}", .{ username, err });
817 return sendJson(conn, arena, 200, reset_accepted, null);
818 };
819 switch (result) {
820 .issued => |issued| {
821 var job = std.heap.ArenaAllocator.init(std.heap.page_allocator);
822 const ja = job.allocator();
823 const message: ?Built = blk: {
824 const about = ja.dupe(u8, username) catch break :blk null;
825 const base = recovery.linkBase(ja, requestHost(req), about, server.config.hostname, publicHttps(server)) catch break :blk null;
826 const link = recovery.resetLink(ja, base, &issued.token) catch break :blk null;
827 const built = recovery.resetMessage(ja, .{
828 .username = about,
829 .recovery = ja.dupe(u8, issued.recovery) catch break :blk null,
830 .link = link,
831 .ip = if (ip.len > 0) (ja.dupe(u8, ip) catch null) else null,
832 .hostname = server.config.hostname,
833 }) catch break :blk null;
834 break :blk .{ .message = built, .about = about };
835 };
836 if (message) |m| {
837 logger.info("Webmail password reset link requested for {s} from {s}", .{ username, ip });
838 dispatchSystemMail(server, job, m.message, "password reset link", m.about);
839 } else {
840 job.deinit();
841 logger.err("Webmail password reset link for {s} could not be built", .{username});
842 }
843 },
844 else => logger.info("Webmail password reset requested for {s} from {s}: nothing sent ({s})", .{ username, ip, @tagName(result) }),
845 }
846 return sendJson(conn, arena, 200, reset_accepted, null);
847}
848
849fn resetTokenAllowed(server: *WebmailHttpServer, arena: std.mem.Allocator, req: Request, conn: *webmail_tls.Stream) !bool {
850 const ip = clientIp(req, conn);
851 if (ip.len == 0) return true;
852 const key = try std.fmt.allocPrint(arena, "token:{s}", .{ip});
853 return server.reset_limiter.checkAndIncrementUser(key) catch true;
854}
855
856const invalid_token_message = "This reset link is invalid, already used or expired. Ask for a new one.";
857
858/// POST /webmail/auth/reset/verify {token} -> {ok, account}
859/// Lets the reset page say which mailbox it is for before asking for a
860/// password. Does not spend the token.
861fn handleResetVerify(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {
862 if (!isSameOrigin(req)) return sendError(conn, arena, 403, "forbidden", "Cross-origin request rejected");
863 if (!try resetTokenAllowed(server, arena, req, conn)) return sendError(conn, arena, 429, "rate_limited", "Too many attempts. Please wait a few minutes.");
864 const token = (try jsonStringFieldAlloc(arena, req.body, "token")) orelse return sendError(conn, arena, 400, "invalid_token", invalid_token_message);
865 const account = (recovery.lookup(arena, server.db, token, time_compat.timestamp()) catch {
866 return sendError(conn, arena, 500, "server_error", "Could not check this link");
867 }) orelse return sendError(conn, arena, 400, "invalid_token", invalid_token_message);
868 var body: std.ArrayList(u8) = .empty;
869 const w = jw(&body, arena);
870 try w.writeAll("{\"ok\":true,\"account\":");
871 try writeJsonString(w, account);
872 try w.writeAll("}");
873 try sendJson(conn, arena, 200, body.items, null);
874}
875
876/// POST /webmail/auth/reset {token, password}
877/// Spends the token, sets the password (webmail, IMAP and SMTP share it),
878/// signs out every session of that mailbox, and tells the recovery address.
879fn handleResetComplete(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {
880 if (!isSameOrigin(req)) return sendError(conn, arena, 403, "forbidden", "Cross-origin request rejected");
881 if (!try resetTokenAllowed(server, arena, req, conn)) return sendError(conn, arena, 429, "rate_limited", "Too many attempts. Please wait a few minutes.");
882 const token = (try jsonStringFieldAlloc(arena, req.body, "token")) orelse return sendError(conn, arena, 400, "invalid_token", invalid_token_message);
883 const password = (try jsonStringFieldAlloc(arena, req.body, "password")) orelse return sendError(conn, arena, 400, "bad_request", "Missing new password");
884 if (password.len < recovery.min_password_len or password.len > recovery.max_password_len)
885 return sendError(conn, arena, 400, "bad_request", "Use a password between 12 and 1024 characters");
886 const done = (recovery.complete(arena, server.db, server.auth, token, password, time_compat.timestamp()) catch |err| {
887 logger.err("Webmail password reset could not be completed: {}", .{err});
888 return sendError(conn, arena, 500, "server_error", "The password could not be changed. Please try again.");
889 }) orelse return sendError(conn, arena, 400, "invalid_token", invalid_token_message);
890
891 logger.info("Webmail password reset completed for {s} from {s}", .{ done.username, clientIp(req, conn) });
892
893 var job = std.heap.ArenaAllocator.init(std.heap.page_allocator);
894 const ja = job.allocator();
895 const notice: ?Built = blk: {
896 const about = ja.dupe(u8, done.username) catch break :blk null;
897 const to = ja.dupe(u8, done.recovery) catch break :blk null;
898 const built = recovery.passwordResetNotice(ja, about, to, server.config.hostname) catch break :blk null;
899 break :blk .{ .message = built, .about = about };
900 };
901 if (notice) |n| dispatchSystemMail(server, job, n.message, "password reset notice", n.about) else job.deinit();
902
903 var body: std.ArrayList(u8) = .empty;
904 const w = jw(&body, arena);
905 try w.writeAll("{\"ok\":true,\"account\":");
906 try writeJsonString(w, done.username);
907 try w.writeAll("}");
908 try sendJson(conn, arena, 200, body.items, try server.sessions.buildClearCookie());
909}
910
911fn writeRecovery(w: anytype, current: ?recovery.Recovery) !void {
912 try w.writeAll("{\"recovery\":");
913 if (current) |r| {
914 if (r.address) |address| try writeJsonString(w, address) else try w.writeAll("null");
915 try w.writeAll(",\"setBy\":");
916 if (r.address != null and r.source != null) try writeJsonString(w, @tagName(r.source.?)) else try w.writeAll("null");
917 } else try w.writeAll("null,\"setBy\":null");
918 try w.writeAll("}");
919}
920
921/// GET /webmail/auth/recovery -> {recovery, setBy}
922fn handleRecoveryGet(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {
923 var sess = (try requireSession(server, conn, arena, req)) orelse return;
924 defer sess.deinit(server.allocator);
925 const current = recovery.get(arena, server.db, sess.username) catch return sendError(conn, arena, 500, "server_error", "Could not read the recovery address");
926 var body: std.ArrayList(u8) = .empty;
927 try writeRecovery(jw(&body, arena), current);
928 try sendJson(conn, arena, 200, body.items, null);
929}
930
931/// PUT /webmail/auth/recovery {currentPassword, recovery}
932/// Re-authenticates with the mailbox password: a borrowed session must not be
933/// enough to redirect the account's reset links. An empty `recovery` removes
934/// it. The previous address, if any, is told about the change.
935fn handleRecoveryUpdate(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {
936 if (!isSameOrigin(req)) return sendError(conn, arena, 403, "forbidden", "Cross-origin request rejected");
937 var sess = (try requireSession(server, conn, arena, req)) orelse return;
938 defer sess.deinit(server.allocator);
939 const current_password = (try jsonStringFieldAlloc(arena, req.body, "currentPassword")) orelse return sendError(conn, arena, 400, "bad_request", "Enter your current password");
940 const wanted_raw = (try jsonStringFieldAlloc(arena, req.body, "recovery")) orelse return sendError(conn, arena, 400, "bad_request", "Missing recovery address");
941 const key = try std.fmt.allocPrint(arena, "recovery:{s}", .{sess.username});
942 if (!try server.login_limiter.checkAndIncrementUser(key)) return sendError(conn, arena, 429, "rate_limited", "Too many attempts. Please wait five minutes");
943 if (!try server.auth.verifyCredentials(sess.username, current_password)) return sendError(conn, arena, 400, "invalid_credentials", "Current password is incorrect");
944
945 const trimmed = std.mem.trim(u8, wanted_raw, " \t\r\n");
946 const wanted: ?[]const u8 = if (trimmed.len == 0) null else recovery.validateAddress(sess.username, trimmed) catch |err| return switch (err) {
947 recovery.RecoveryError.SameAsMailbox => sendError(conn, arena, 400, "bad_request", "Use an address outside this mailbox: a reset link sent here could not be read without the password"),
948 else => sendError(conn, arena, 400, "bad_request", "Enter a valid email address"),
949 };
950
951 const previous = recovery.get(arena, server.db, sess.username) catch return sendError(conn, arena, 500, "server_error", "Could not read the recovery address");
952 recovery.set(server.db, sess.username, wanted, .user, time_compat.timestamp()) catch |err| {
953 logger.err("Webmail recovery address update for {s} failed: {}", .{ sess.username, err });
954 return sendError(conn, arena, 500, "server_error", "Could not save the recovery address");
955 };
956 logger.info("Webmail recovery address {s} for {s} from {s}", .{ if (wanted == null) "removed" else "changed", sess.username, clientIp(req, conn) });
957
958 const old: ?[]const u8 = if (previous) |p| p.address else null;
959 if (old) |old_address| {
960 const same = if (wanted) |w| std.ascii.eqlIgnoreCase(w, old_address) else false;
961 if (!same) {
962 var job = std.heap.ArenaAllocator.init(std.heap.page_allocator);
963 const ja = job.allocator();
964 const notice: ?Built = blk: {
965 const about = ja.dupe(u8, sess.username) catch break :blk null;
966 const to = ja.dupe(u8, old_address) catch break :blk null;
967 const built = recovery.recoveryChangedNotice(ja, about, to, server.config.hostname) catch break :blk null;
968 break :blk .{ .message = built, .about = about };
969 };
970 if (notice) |n| dispatchSystemMail(server, job, n.message, "recovery address change notice", n.about) else job.deinit();
971 }
972 }
973
974 const now_value = recovery.get(arena, server.db, sess.username) catch null;
975 var body: std.ArrayList(u8) = .empty;
976 try writeRecovery(jw(&body, arena), now_value);
977 try sendJson(conn, arena, 200, body.items, null);
978}
979
684980const ComposePayload = service_mod.Payload;
685981
686982fn handleDraftSave(server: *WebmailHttpServer, conn: *webmail_tls.Stream, arena: std.mem.Allocator, req: Request) !void {