vectrumVectrumPublic

Merge branch 't3/smtp-email-sending'

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Browse Files

JjohannSocommitted last week2 parents 2704b3b e6cf1fccommit7b8afe3

Showing 27 changed files with 659 additions and 15 deletions.

Merge commit — showing changes against the first parent.

+3−0.gitignoreView File

@@ -27,3 +27,6 @@ yarn-error.log*
27	27	# editors
28	28	.idea/
29	29	*.iml
	30	+
	31	+ # example settings, safe to commit
	32	+ !.env.example

+13−0apps/web/.env.exampleaddedView File

++ # Copy to .env (Next.js reads it on start). See docs/installation.md#configuration.
++ # The address users reach Vectrum at; links in emails point here.
++ # PUBLIC_URL=https://vectrum.example.com
++ # Email: address confirmation, password resets, invitations. Without SMTP_HOST, nothing is sent.
++ # SMTP_HOST=smtp.example.com
++ # SMTP_PORT=587
++ # 1 for TLS from the start (the default for port 465); otherwise STARTTLS is used when the server offers it.
++ # SMTP_SECURE=0
++ # SMTP_USER=vectrum@example.com
++ # SMTP_PASSWORD=
++ # MAIL_FROM="Vectrum <vectrum@example.com>"

+23−1apps/web/app/actions/auth.tsView File

@@ -2,8 +2,10 @@
2	2
3	3	import { redirect } from "next/navigation";
4	4	import { completeSignIn, endSession, safeNext, signIn } from "@/lib/auth";
	5	+ import { requestPasswordReset, resetPassword, sendVerificationEmailLater } from "@/lib/emails";
	6	+ import { MAIL_ENABLED } from "@/lib/mail";
5	7	import { SIGNUPS_ENABLED } from "@/lib/signups";
6		- import { createUser, UserError } from "@/lib/users";
	8	+ import { createUser, UserError, validatePassword } from "@/lib/users";
7	9	import type { FormState } from "./types";
8	10
9	11	export async function signupAction(_prev: FormState, formData: FormData): Promise<FormState> {
@@ -16,6 +18,7 @@ export async function signupAction(_prev: FormState, formData: FormData): Promis
16	18	password,
17	19	name: String(formData.get("name") ?? ""),
18	20	});
	21	+ sendVerificationEmailLater(user);
19	22	await signIn(user.email, password);
20	23	} catch (e) {
21	24	if (e instanceof UserError) return { error: e.message };
@@ -41,6 +44,25 @@ export async function twoFactorLoginAction(_prev: FormState, formData: FormData)
41	44	redirect(next);
42	45	}
43	46
	47	+ export async function forgotPasswordAction(_prev: FormState, formData: FormData): Promise<FormState> {
	48	+ if (!MAIL_ENABLED) return { error: "This server can't send email. Ask the person who runs it to reset your password." };
	49	+ const login = String(formData.get("login") ?? "").trim();
	50	+ if (!login) return { error: "Enter your username or email address." };
	51	+ await requestPasswordReset(login);
	52	+ return { success: "If that's an account here, we've sent a link to choose a new password to its email address. It works for one hour." };
	53	+ }
	54	+
	55	+ export async function resetPasswordAction(_prev: FormState, formData: FormData): Promise<FormState> {
	56	+ const password = String(formData.get("password") ?? "");
	57	+ if (password !== formData.get("confirm")) return { error: "The passwords don't match." };
	58	+ const problem = validatePassword(password);
	59	+ if (problem) return { error: problem };
	60	+ if (!(await resetPassword(String(formData.get("token") ?? ""), password))) {
	61	+ return { error: "This link has expired or was already used. Ask for a new one." };
	62	+ }
	63	+ redirect("/login?reset=1");
	64	+ }
	65	+
44	66	export async function logoutAction() {
45	67	await endSession();
46	68	redirect("/");

+2−0apps/web/app/actions/orgs.tsView File

@@ -2,6 +2,7 @@
2	2
3	3	import { revalidatePath } from "next/cache";
4	4	import { redirect } from "next/navigation";
	5	+ import { notifyInvitation } from "@/lib/emails";
5	6	import {
6	7	answerInvitation,
7	8	cancelInvitation,
@@ -100,6 +101,7 @@ export async function inviteMemberAction(name: string, _prev: FormState, formDat
100	101	const { org, viewer } = await orgForAction(name, "owner");
101	102	const role = roleOf(formData);
102	103	const user = await inviteMember(org, viewer, String(formData.get("username") ?? ""), role);
	104	+ notifyInvitation(user, org, viewer, role);
103	105	revalidatePath(`/organizations/${org.username}/settings/members`);
104	106	return { success: `Invited ${user.username} as ${ROLE_INFO[role].title.toLowerCase()}. They’ll find the invitation on their dashboard.` };
105	107	});

+4−2apps/web/app/actions/repo.tsView File

@@ -16,6 +16,7 @@ import {
16	16	updateRepo,
17	17	type Visibility,
18	18	} from "@/lib/repos";
	19	+ import { notifyCollaborator } from "@/lib/emails";
19	20	import { getOrg, mayCreateRepos } from "@/lib/orgs";
20	21	import { ActionError, repoForAction, viewerOrThrow } from "./guard";
21	22	import type { FormState } from "./types";
@@ -134,9 +135,10 @@ export async function deleteRepoAction(owner: string, name: string, _prev: FormS
134	135
135	136	export async function addCollaboratorAction(owner: string, name: string, _prev: FormState, formData: FormData) {
136	137	return attempt(async () => {
137		- const { repo } = await repoForAction(owner, name, "admin");
	138	+ const { repo, viewer } = await repoForAction(owner, name, "admin");
138	139	const username = String(formData.get("username") ?? "").trim();
139		- await addCollaborator(repo, username);
	140	+ const { user, added } = await addCollaborator(repo, username);
	141	+ if (added) notifyCollaborator(user, repo, viewer);
140	142	revalidatePath(`/${repo.owner}/${repo.name}/settings`);
141	143	return { success: `${username} can now push to this repository.` };
142	144	});

+22−2apps/web/app/actions/settings.tsView File

@@ -2,6 +2,7 @@
2	2
3	3	import { revalidatePath } from "next/cache";
4	4	import { renewSession } from "@/lib/auth";
	5	+ import { notifyEmailChanged, notifyPasswordChanged, sendVerificationEmail, sendVerificationEmailLater } from "@/lib/emails";
5	6	import { addSshKey, deleteSshKey, KeyError } from "@/lib/keys";
6	7	import { createToken, deleteToken, TokenError, type TokenPermission } from "@/lib/tokens";
7	8	import {
@@ -19,13 +20,18 @@ import type { FormState } from "./types";
19	20	export async function updateProfileAction(_prev: FormState, formData: FormData): Promise<FormState> {
20	21	const viewer = await viewerOrThrow();
21	22	try {
22		- const { emailChanged } = await updateProfile(viewer.id, {
	23	+ const email = String(formData.get("email") ?? "").trim();
	24	+ const { emailChanged, newAddress } = await updateProfile(viewer.id, {
23	25	name: String(formData.get("name") ?? ""),
24		- email: String(formData.get("email") ?? ""),
	26	+ email,
25	27	bio: String(formData.get("bio") ?? ""),
26	28	});
27	29	// PocketBase revokes a user's tokens when their email changes; keep this browser signed in.
28	30	if (emailChanged) await renewSession(viewer.id);
	31	+ if (newAddress) {
	32	+ notifyEmailChanged(viewer, email);
	33	+ sendVerificationEmailLater({ ...viewer, email, verified: false });
	34	+ }
29	35	} catch (e) {
30	36	if (e instanceof UserError) return { error: e.message };
31	37	throw e;
@@ -34,6 +40,19 @@ export async function updateProfileAction(_prev: FormState, formData: FormData):
34	40	return { success: "Profile updated." };
35	41	}
36	42
	43	+ export async function resendVerificationAction(): Promise<FormState> {
	44	+ const viewer = await viewerOrThrow();
	45	+ try {
	46	+ const result = await sendVerificationEmail(viewer);
	47	+ if (result === "wait") return { error: "We just sent one. Wait a minute before asking again." };
	48	+ if (result === "verified") return { success: "Your email address is already confirmed." };
	49	+ } catch (e) {
	50	+ console.error("[mail] couldn't send the verification email:", e instanceof Error ? e.message : e);
	51	+ return { error: "The email couldn't be sent. Try again later." };
	52	+ }
	53	+ return { success: `Sent. Check ${viewer.email} for the link.` };
	54	+ }
	55	+
37	56	export async function changePasswordAction(_prev: FormState, formData: FormData): Promise<FormState> {
38	57	const viewer = await viewerOrThrow();
39	58	const current = String(formData.get("current") ?? "");
@@ -45,6 +64,7 @@ export async function changePasswordAction(_prev: FormState, formData: FormData)
45	64	// This signs the user out everywhere, so sign this browser back in.
46	65	await setPassword(viewer.id, next);
47	66	await renewSession(viewer.id);
	67	+ notifyPasswordChanged(viewer);
48	68	return { success: "Password changed." };
49	69	}
50	70

+35−0apps/web/app/login/forgot-password/page.tsxaddedView File

++ import type { Metadata } from "next";
++ import NextLink from "next/link";
++ import { notFound } from "next/navigation";
++ import { Link } from "@unlocalhosted/metalui";
++ import { ForgotPasswordForm } from "@/components/auth-forms";
++ import { KeyIcon } from "@/components/icons";
++ import { Box } from "@/components/ui";
++ import { MAIL_ENABLED } from "@/lib/mail";
++ export const metadata: Metadata = { title: "Forgot your password?" };
++ export default function ForgotPasswordPage() {
++   if (!MAIL_ENABLED) notFound();
++   return (
++     <main className="relative flex flex-1 flex-col items-center justify-center overflow-hidden px-4 py-16">
++       <div className="aurora pointer-events-none absolute inset-0" aria-hidden />
++       <div className="dot-grid pointer-events-none absolute inset-0" aria-hidden />
++       <div className="animate-fade-up relative w-full max-w-[380px]">
++         <div className="text-center">
++           <span className="mx-auto flex size-16 items-center justify-center rounded-hero material-cap [&_svg]:size-8">
++             <KeyIcon />
++           </span>
++           <h1 className="mt-6 text-[22px] leading-7 font-semibold tracking-[-0.025em] text-ink">Forgot your password?</h1>
++           <p className="mt-1 type-lead text-ink2">We’ll email you a link to choose a new one</p>
++         </div>
++         <Box className="mt-8 p-6">
++           <ForgotPasswordForm />
++         </Box>
++         <p className="mt-6 text-center type-body text-ink2">
++           Remembered it? <Link render={<NextLink href="/login" />}>Sign in</Link>
++         </p>
++       </div>
++     </main>
++   );
++ }

+7−1apps/web/app/login/page.tsxView File

@@ -6,6 +6,7 @@ import { LoginForm } from "@/components/auth-forms";
6	6	import { BRAND, LogoMark } from "@/components/brand";
7	7	import { Alert, Box } from "@/components/ui";
8	8	import { getViewer, safeNext } from "@/lib/auth";
	9	+ import { MAIL_ENABLED } from "@/lib/mail";
9	10	import { SIGNUPS_ENABLED } from "@/lib/signups";
10	11
11	12	export const metadata: Metadata = { title: "Sign in" };
@@ -32,8 +33,13 @@ export default async function LoginPage({ searchParams }: PageProps<"/login">) {
32	33	<Alert kind="info">Your sign-in timed out. Enter your password again.</Alert>
33	34	</div>
34	35	)}
	36	+ {params.reset && (
	37	+ <div className="mt-8">
	38	+ <Alert kind="success">Your password was changed. Sign in with the new one.</Alert>
	39	+ </div>
	40	+ )}
35	41	<Box className="mt-8 p-6">
36		- <LoginForm next={next} />
	42	+ <LoginForm next={next} canReset={MAIL_ENABLED} />
37	43	</Box>
38	44	{SIGNUPS_ENABLED && (
39	45	<p className="mt-6 text-center type-body text-ink2">

+45−0apps/web/app/login/reset-password/page.tsxaddedView File

++ import type { Metadata } from "next";
++ import NextLink from "next/link";
++ import { Link } from "@unlocalhosted/metalui";
++ import { ResetPasswordForm } from "@/components/auth-forms";
++ import { KeyIcon } from "@/components/icons";
++ import { Alert, Box } from "@/components/ui";
++ import { passwordResetUser } from "@/lib/emails";
++ export const metadata: Metadata = { title: "Choose a new password" };
++ /** Where the link in a password reset email (lib/emails.ts) leads. */
++ export default async function ResetPasswordPage({ searchParams }: PageProps<"/login/reset-password">) {
++   const token = (await searchParams).token;
++   const user = typeof token === "string" ? await passwordResetUser(token) : null;
++   return (
++     <main className="relative flex flex-1 flex-col items-center justify-center overflow-hidden px-4 py-16">
++       <div className="aurora pointer-events-none absolute inset-0" aria-hidden />
++       <div className="dot-grid pointer-events-none absolute inset-0" aria-hidden />
++       <div className="animate-fade-up relative w-full max-w-[380px]">
++         <div className="text-center">
++           <span className="mx-auto flex size-16 items-center justify-center rounded-hero material-cap [&_svg]:size-8">
++             <KeyIcon />
++           </span>
++           <h1 className="mt-6 text-[22px] leading-7 font-semibold tracking-[-0.025em] text-ink">Choose a new password</h1>
++           {user && <p className="mt-1 type-lead text-ink2">For @{user.username}</p>}
++         </div>
++         <Box className="mt-8 p-6">
++           {user && typeof token === "string" ? (
++             <ResetPasswordForm token={token} username={user.username} />
++           ) : (
++             <Alert>This link has expired or was already used.</Alert>
++           )}
++         </Box>
++         <p className="mt-6 text-center type-body text-ink2">
++           {user ? (
++             <Link render={<NextLink href="/login" />}>Back to sign in</Link>
++           ) : (
++             <Link render={<NextLink href="/login/forgot-password" />}>Ask for a new link</Link>
++           )}
++         </p>
++       </div>
++     </main>
++   );
++ }

+48−0apps/web/app/login/verify-email/page.tsxaddedView File

++ import type { Metadata } from "next";
++ import NextLink from "next/link";
++ import { Link } from "@unlocalhosted/metalui";
++ import { MailIcon } from "@/components/icons";
++ import { Alert, Box } from "@/components/ui";
++ import { getViewer } from "@/lib/auth";
++ import { confirmEmail } from "@/lib/emails";
++ export const metadata: Metadata = { title: "Confirm your email address" };
++ /** Where the link in a verification email (lib/emails.ts) leads. Opening it confirms the address. */
++ export default async function VerifyEmailPage({ searchParams }: PageProps<"/login/verify-email">) {
++   const token = (await searchParams).token;
++   const [user, viewer] = await Promise.all([typeof token === "string" ? confirmEmail(token) : null, getViewer()]);
++   return (
++     <main className="relative flex flex-1 flex-col items-center justify-center overflow-hidden px-4 py-16">
++       <div className="aurora pointer-events-none absolute inset-0" aria-hidden />
++       <div className="dot-grid pointer-events-none absolute inset-0" aria-hidden />
++       <div className="animate-fade-up relative w-full max-w-[380px]">
++         <div className="text-center">
++           <span className="mx-auto flex size-16 items-center justify-center rounded-hero material-cap [&_svg]:size-8">
++             <MailIcon />
++           </span>
++           <h1 className="mt-6 text-[22px] leading-7 font-semibold tracking-[-0.025em] text-ink">Confirm your email address</h1>
++         </div>
++         <Box className="mt-8 p-6">
++           {user ? (
++             <Alert kind="success">
++               {user.email} is confirmed as the address of @{user.username}.
++             </Alert>
++           ) : (
++             <Alert>
++               This link has expired, or the account’s email address has changed since. Send a new one from your profile settings.
++             </Alert>
++           )}
++         </Box>
++         <p className="mt-6 text-center type-body text-ink2">
++           {viewer ? (
++             <Link render={<NextLink href={user ? "/" : "/settings/profile"} />}>{user ? "Go to your dashboard" : "Open profile settings"}</Link>
++           ) : (
++             <Link render={<NextLink href={user ? "/login" : "/login?next=%2Fsettings%2Fprofile"} />}>Sign in</Link>
++           )}
++         </p>
++       </div>
++     </main>
++   );
++ }

+8−0apps/web/app/page.tsxView File

@@ -23,10 +23,12 @@ import {
23	23	import { CardDescription, CardTitle } from "@/components/metal";
24	24	import { RepoFilterList } from "@/components/repo-filter-list";
25	25	import { Avatar, avatarUrl, Blankslate, Box, ButtonLink, Counter, Label, RefChip, RepoAvatar } from "@/components/ui";
	26	+ import { VerifyEmailNotice } from "@/components/verify-email-notice";
26	27	import { getViewer } from "@/lib/auth";
27	28	import { shortSha, timeAgo } from "@/lib/format";
28	29	import { recentActivity, withActivity } from "@/lib/listing";
29	30	import { listListsOf, listPath } from "@/lib/lists";
	31	+ import { MAIL_ENABLED } from "@/lib/mail";
30	32	import { listInvitationsFor, listOrgsOf } from "@/lib/orgs";
31	33	import { listReposForUser, searchRepos } from "@/lib/repos";
32	34	import { serverHost } from "@/lib/request-origin";
@@ -217,6 +219,12 @@ async function Dashboard({ viewer }: { viewer: User }) {
217	219	</div>
218	220	</div>
219	221
	222	+ {MAIL_ENABLED && !viewer.verified && (
	223	+ <div className="mb-6">
	224	+ <VerifyEmailNotice email={viewer.email} />
	225	+ </div>
	226	+ )}
	227	+
220	228	{invitations.length > 0 && (
221	229	<div className="mb-6">
222	230	<OrgInvitations invitations={invitations} />

+3−0apps/web/app/settings/profile/page.tsxView File

@@ -1,7 +1,9 @@
1	1	import type { Metadata } from "next";
2	2	import { PlateSection } from "@/components/settings-plate";
3	3	import { PageTitle } from "@/components/ui";
	4	+ import { VerifyEmailNotice } from "@/components/verify-email-notice";
4	5	import { requireViewer } from "@/lib/auth";
	6	+ import { MAIL_ENABLED } from "@/lib/mail";
5	7	import { PasswordForm, ProfileForm } from "./forms";
6	8
7	9	export const metadata: Metadata = { title: "Your profile" };
@@ -12,6 +14,7 @@ export default async function ProfileSettingsPage() {
12	14	<div>
13	15	<PageTitle title="Public profile" description="How you appear to others across the instance." />
14	16	<div className="flex flex-col gap-7">
	17	+ {MAIL_ENABLED && !viewer.verified && <VerifyEmailNotice email={viewer.email} />}
15	18	<PlateSection title="Profile">
16	19	<ProfileForm user={viewer} />
17	20	</PlateSection>

+51−3apps/web/components/auth-forms.tsxView File

@@ -3,18 +3,26 @@
3	3	import NextLink from "next/link";
4	4	import { useActionState } from "react";
5	5	import { Link } from "@unlocalhosted/metalui";
6		- import { loginAction, signupAction, twoFactorLoginAction } from "@/app/actions/auth";
	6	+ import { forgotPasswordAction, loginAction, resetPasswordAction, signupAction, twoFactorLoginAction } from "@/app/actions/auth";
7	7	import { TextField } from "./settings-fields";
8	8	import { Alert, Button } from "./ui";
9	9
10		- export function LoginForm({ next }: { next: string }) {
	10	+ /** With `canReset`, links to resetting a forgotten password (only when the server can send email). */
	11	+ export function LoginForm({ next, canReset }: { next: string; canReset?: boolean }) {
11	12	const [state, action, pending] = useActionState(loginAction, undefined);
12	13	return (
13	14	<form action={action} className="flex flex-col gap-4">
14	15	<input type="hidden" name="next" value={next} />
15	16	{state?.error && <Alert>{state.error}</Alert>}
16	17	<TextField label="Username or email address" name="login" required autoFocus autoComplete="username" />
17		- <TextField label="Password" name="password" type="password" required autoComplete="current-password" />
	18	+ <TextField
	19	+ label="Password"
	20	+ description={canReset && <Link render={<NextLink href="/login/forgot-password" />}>Forgot your password?</Link>}
	21	+ name="password"
	22	+ type="password"
	23	+ required
	24	+ autoComplete="current-password"
	25	+ />
18	26	<Button variant="primary" className="mt-1 w-full" disabled={pending}>
19	27	{pending ? "Signing in…" : "Sign In"}
20	28	</Button>
@@ -82,3 +90,43 @@ export function SignupForm({ next }: { next: string }) {
82	90	</form>
83	91	);
84	92	}
	93	+
	94	+ export function ForgotPasswordForm() {
	95	+ const [state, action, pending] = useActionState(forgotPasswordAction, undefined);
	96	+ if (state?.success) return <Alert kind="success">{state.success}</Alert>;
	97	+ return (
	98	+ <form action={action} className="flex flex-col gap-4">
	99	+ {state?.error && <Alert>{state.error}</Alert>}
	100	+ <TextField label="Username or email address" name="login" required autoFocus autoComplete="username" />
	101	+ <Button variant="primary" className="mt-1 w-full" disabled={pending}>
	102	+ {pending ? "Sending…" : "Send Link"}
	103	+ </Button>
	104	+ </form>
	105	+ );
	106	+ }
	107	+
	108	+ export function ResetPasswordForm({ token, username }: { token: string; username: string }) {
	109	+ const [state, action, pending] = useActionState(resetPasswordAction, undefined);
	110	+ return (
	111	+ <form action={action} className="flex flex-col gap-4">
	112	+ <input type="hidden" name="token" value={token} />
	113	+ {/* For password managers. */}
	114	+ <input type="hidden" name="username" value={username} autoComplete="username" />
	115	+ {state?.error && <Alert>{state.error}</Alert>}
	116	+ <TextField
	117	+ label="New password"
	118	+ description="At least 8 characters."
	119	+ name="password"
	120	+ type="password"
	121	+ required
	122	+ minLength={8}
	123	+ autoFocus
	124	+ autoComplete="new-password"
	125	+ />
	126	+ <TextField label="Confirm new password" name="confirm" type="password" required minLength={8} autoComplete="new-password" />
	127	+ <Button variant="primary" className="mt-1 w-full" disabled={pending}>
	128	+ {pending ? "Saving…" : "Set Password"}
	129	+ </Button>
	130	+ </form>
	131	+ );
	132	+ }

+21−0apps/web/components/verify-email-notice.tsxaddedView File

++ import { resendVerificationAction } from "@/app/actions/settings";
++ import { ActionButton } from "./action-button";
++ import { MailIcon } from "./icons";
++ import { Alert } from "./ui";
++ /** For a signed-in person who hasn't confirmed their email address yet (lib/emails.ts). */
++ export function VerifyEmailNotice({ email }: { email: string }) {
++   return (
++     <Alert kind="info">
++       <div className="flex flex-wrap items-center justify-between gap-3">
++         <span>
++           Confirm your email address: we sent a link to <strong className="font-semibold">{email}</strong>. Until then, you won’t get
++           emails about invitations and your account.
++         </span>
++         <ActionButton action={resendVerificationAction} icon={<MailIcon />}>
++           Send Again
++         </ActionButton>
++       </div>
++     </Alert>
++   );
++ }

+2−0apps/web/lib/app-api.tsView File

@@ -1,6 +1,7 @@
1	1	import "server-only";
2	2	import { person, type Actor } from "./actor";
3	3	import { checkSecondFactor, userForSession } from "./auth";
	4	+ import { sendVerificationEmailLater } from "./emails";
4	5	import { describeEvent } from "./event-text";
5	6	import { listEvents as listRepoEvents, type RepoEvent } from "./events";
6	7	import { commitCount, defaultBranch, diffCommit, getCommit, GitError, listBranches, listTags, listTree, log, normalizeRepoName, objectType, readBlob, revParse, type Commit, type FileDiff } from "./git";
@@ -148,6 +149,7 @@ export async function signUp(request: Request) {
148	149	const password = text(body.password, 200);
149	150	try {
150	151	const user = await createUser({ username: text(body.username, 100), email: text(body.email, 200), password, name: text(body.name, 100) });
	152	+ sendVerificationEmailLater(user);
151	153	const auth = await authenticateUser(user.email, password);
152	154	if (!auth) throw new ApiError(500, "The account was created, but signing in failed. Try signing in.");
153	155	return { token: auth.token, user: userJson(auth.user) };

+187−0apps/web/lib/emails.tsaddedView File

++ import "server-only";
++ import { createHash, randomBytes } from "node:crypto";
++ import { db, filter, findFirst, withLock } from "./db";
++ import { linkTo, MAIL_ENABLED, sendMail, sendMailLater, type Message } from "./mail";
++ import { ROLE_INFO, type OrgRole } from "./org-roles";
++ import { getPersonByLogin, getUserById, setPassword, type User } from "./users";
++ /*
++  * The emails Vectrum sends (through lib/mail.ts), and the links in them that confirm an address
++  * or set a new password. A link carries a random token; only its hash is kept (in email_tokens),
++  * with the address it went to, so it stops working once the account's email changes.
++  *
++  * Notifications (invitations, access, security notices) only go to confirmed addresses: anyone can
++  * sign up with someone else's.
++  */
++ const LIFETIME_MS = { verify: 3 * 86400_000, reset: 60 * 60_000 };
++ /** At most one link of a kind per account in this time, so nobody can flood an inbox with them. */
++ const RESEND_MS = 60_000;
++ type Purpose = keyof typeof LIFETIME_MS;
++ const hash = (token: string) => createHash("sha256").update(token).digest("hex");
++ const tokens = async () => (await db()).collection("email_tokens");
++ /** A new token for a link, or null if one went out too recently. */
++ async function issueToken(user: User, purpose: Purpose) {
++   return withLock(`email-tokens:${user.id}`, async () => {
++     const now = Date.now();
++     const since = now - RESEND_MS;
++     if (await findFirst("email_tokens", filter("user = {:id} && purpose = {:purpose} && created_at > {:since}", { id: user.id, purpose, since }), { fields: "id" })) {
++       return null;
++     }
++     const collection = await tokens();
++     const expired = await collection.getFullList({ filter: filter("user = {:id} && expires_at < {:now}", { id: user.id, now }), fields: "id" });
++     await Promise.all(expired.map((r) => collection.delete(r.id)));
++     const token = randomBytes(32).toString("base64url");
++     await collection.create({ user: user.id, purpose, email: user.email, token_hash: hash(token), expires_at: now + LIFETIME_MS[purpose], created_at: now });
++     return token;
++   });
++ }
++ /** Sends an email with a new link, or returns false if one went out too recently. A link that couldn't be sent doesn't count. */
++ async function sendLink(user: User, purpose: Purpose, message: (url: string) => Message) {
++   const token = await issueToken(user, purpose);
++   if (!token) return false;
++   try {
++     await sendMail(message(linkTo(`/login/${purpose === "verify" ? "verify-email" : "reset-password"}?token=${token}`)));
++   } catch (e) {
++     const row = await findFirst("email_tokens", filter("token_hash = {:hash}", { hash: hash(token) }), { fields: "id" });
++     if (row) await (await tokens()).delete(row.id);
++     throw e;
++   }
++   return true;
++ }
++ /** The account a link is for, while it's good. */
++ async function tokenUser(token: string, purpose: Purpose) {
++   if (!token || token.length > 100) return null;
++   const row = await findFirst("email_tokens", filter("token_hash = {:hash} && purpose = {:purpose}", { hash: hash(token), purpose }));
++   if (!row || row.expires_at < Date.now()) return null;
++   const user = await getUserById(row.user);
++   if (!user || user.email.toLowerCase() !== String(row.email).toLowerCase()) return null;
++   return user;
++ }
++ const markVerified = async (userId: string) => void (await (await db()).collection("users").update(userId, { verified: true }));
++ const logFailure = (what: string) => (e: unknown) => console.error(`[mail] couldn't send ${what}:`, e instanceof Error ? e.message : e);
++ // ---------------------------------------------------------------------------
++ // Confirming an address
++ /** Emails a link that confirms the user's address. "wait" if one went out less than a minute ago. */
++ export async function sendVerificationEmail(user: User): Promise<"sent" | "wait" | "verified"> {
++   if (user.verified) return "verified";
++   const sent = await sendLink(user, "verify", (url) => ({
++     to: user.email,
++     subject: "Confirm your email address",
++     body: [`Hi ${user.name || user.username},`, `Confirm that ${user.email} is the email address of your account, @${user.username}.`],
++     action: { label: "Confirm email address", url },
++     footer: "The link works for 3 days. If you didn't sign up or change your email address, ignore this email.",
++   }));
++   return sent ? "sent" : "wait";
++ }
++ /** After signing up or changing the address: sends the link without holding up the request. */
++ export function sendVerificationEmailLater(user: User) {
++   if (MAIL_ENABLED) sendVerificationEmail(user).catch(logFailure("the verification email"));
++ }
++ /**
++  * Confirms the address a link was sent to. The link keeps working until it expires: mail
++  * scanners open links before people do.
++  */
++ export async function confirmEmail(token: string) {
++   const user = await tokenUser(token, "verify");
++   if (user && !user.verified) await markVerified(user.id);
++   return user;
++ }
++ // ---------------------------------------------------------------------------
++ // Resetting a forgotten password
++ /**
++  * Emails a link to set a new password if `login` (a username or email address) is someone's
++  * account. It doesn't tell whether it is, and doesn't wait for the email, as how long that takes
++  * would tell too.
++  */
++ export async function requestPasswordReset(login: string) {
++   const user = await getPersonByLogin(login);
++   if (!user?.email) return;
++   sendLink(user, "reset", (url) => ({
++     to: user.email,
++     subject: "Reset your password",
++     body: [`Hi ${user.name || user.username},`, `Someone asked to reset the password of your account, @${user.username}. Choose a new one here:`],
++     action: { label: "Choose a new password", url },
++     footer: "The link works for one hour, once. If you didn't ask for it, ignore this email: your password stays the same.",
++   })).catch(logFailure("the password reset email"));
++ }
++ /** The account a password reset link is for, while it's good. */
++ export const passwordResetUser = (token: string) => tokenUser(token, "reset");
++ /** Sets a new password with a reset link, which then stops working (as do the account's sessions). */
++ export async function resetPassword(token: string, password: string) {
++   const user = await passwordResetUser(token);
++   if (!user) return false;
++   await setPassword(user.id, password);
++   // The link reached them, so the address is theirs.
++   if (!user.verified) await markVerified(user.id);
++   notifyPasswordChanged({ ...user, verified: true });
++   return true;
++ }
++ // ---------------------------------------------------------------------------
++ // Notifications
++ function notify(user: User, message: Omit<Message, "to">) {
++   if (MAIL_ENABLED && user.verified && user.email) sendMailLater({ ...message, to: user.email });
++ }
++ export function notifyInvitation(user: User, org: User, inviter: User, role: OrgRole) {
++   notify(user, {
++     subject: `@${inviter.username} invited you to join ${org.username}`,
++     body: [
++       `Hi ${user.name || user.username},`,
++       `@${inviter.username} invited you to join the organization ${org.name || org.username}, with the ${ROLE_INFO[role].title} role.`,
++       "Accept or decline the invitation on your dashboard.",
++     ],
++     action: { label: "View invitation", url: linkTo("/settings/organizations") },
++     footer: `You're getting this because @${inviter.username} invited your account, @${user.username}.`,
++   });
++ }
++ export function notifyCollaborator(user: User, repo: { owner: string; name: string }, by: User) {
++   notify(user, {
++     subject: `You can now push to ${repo.owner}/${repo.name}`,
++     body: [`Hi ${user.name || user.username},`, `@${by.username} added you as a collaborator to ${repo.owner}/${repo.name}. You can now push to it.`],
++     action: { label: "Open repository", url: linkTo(`/${repo.owner}/${repo.name}`) },
++     footer: `You're getting this because @${by.username} gave your account, @${user.username}, access.`,
++   });
++ }
++ export function notifyPasswordChanged(user: User) {
++   notify(user, {
++     subject: "Your password was changed",
++     body: [
++       `Hi ${user.name || user.username},`,
++       `The password of your account, @${user.username}, was just changed, and its other sessions were signed out.`,
++       "If that wasn't you, reset your password right away.",
++     ],
++     action: { label: "Reset password", url: linkTo("/login/forgot-password") },
++   });
++ }
++ /** Tells the old address (`before`) that the account's email changed, in case someone else did it. */
++ export function notifyEmailChanged(before: User, newEmail: string) {
++   notify(before, {
++     subject: "Your email address was changed",
++     body: [
++       `Hi ${before.name || before.username},`,
++       `The email address of your account, @${before.username}, was changed from ${before.email} to ${newEmail}. Emails go to the new address from now on.`,
++       "If that wasn't you, someone else has your account: tell whoever runs this server.",
++     ],
++   });
++ }

+76−0apps/web/lib/mail.tsaddedView File

++ import "server-only";
++ import { createTransport } from "nodemailer";
++ import { BRAND } from "@/components/brand";
++ import { PUBLIC_ORIGIN } from "./request-origin";
++ /*
++  * Email goes out through the SMTP server in SMTP_HOST (with SMTP_PORT, SMTP_USER, SMTP_PASSWORD and
++  * SMTP_SECURE), from MAIL_FROM. Without SMTP_HOST nothing is sent, and what needs email (confirming
++  * addresses, resetting a forgotten password) isn't offered. The messages are in lib/emails.ts.
++  */
++ export const MAIL_ENABLED = !!process.env.SMTP_HOST;
++ const PORT = Number(process.env.SMTP_PORT) || 587;
++ // Port 465 speaks TLS from the start; others upgrade with STARTTLS when the server offers it.
++ const SECURE = process.env.SMTP_SECURE ? ["1", "true"].includes(process.env.SMTP_SECURE.toLowerCase()) : PORT === 465;
++ const FROM = process.env.MAIL_FROM || process.env.SMTP_USER;
++ const g = globalThis as unknown as { __mailer?: ReturnType<typeof createTransport>; __mailOriginWarned?: boolean };
++ function mailer() {
++   if (!FROM) throw new Error("Set MAIL_FROM to the address emails are sent from.");
++   return (g.__mailer ??= createTransport({
++     host: process.env.SMTP_HOST,
++     port: PORT,
++     secure: SECURE,
++     auth: process.env.SMTP_USER ? { user: process.env.SMTP_USER, pass: process.env.SMTP_PASSWORD ?? "" } : undefined,
++   }));
++ }
++ /** An absolute link to a page of this server. */
++ export function linkTo(path: string) {
++   if (!PUBLIC_ORIGIN && !g.__mailOriginWarned) {
++     g.__mailOriginWarned = true;
++     console.warn("[mail] PUBLIC_URL isn't set, so links in emails point at localhost.");
++   }
++   return `${PUBLIC_ORIGIN ?? `http://localhost:${process.env.PORT ?? 3000}`}${path}`;
++ }
++ export type Message = {
++   to: string;
++   subject: string;
++   /** Paragraphs of plain text. */
++   body: string[];
++   /** The one thing to do, as a button. */
++   action?: { label: string; url: string };
++   /** Smaller print below, e.g. why the email was sent. */
++   footer?: string;
++ };
++ const escape = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
++ function html({ body, action, footer }: Message) {
++   const p = (text: string) => `<p style="margin:0 0 16px">${escape(text)}</p>`;
++   const button = action
++     ? `<p style="margin:24px 0"><a href="${escape(action.url)}" style="display:inline-block;padding:10px 18px;border-radius:8px;background:#111827;color:#ffffff;text-decoration:none;font-weight:600">${escape(action.label)}</a></p>` +
++       `<p style="margin:0 0 16px;font-size:13px;color:#6b7280">Or open this link: <a href="${escape(action.url)}" style="color:#6b7280">${escape(action.url)}</a></p>`
++     : "";
++   const small = footer ? `<p style="margin:24px 0 0;font-size:13px;color:#6b7280">${escape(footer)}</p>` : "";
++   return `<!doctype html><html><body style="margin:0;padding:24px;background:#f9fafb"><div style="max-width:520px;margin:0 auto;padding:28px;background:#ffffff;border-radius:12px;font:15px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:#111827">${body.map(p).join("")}${button}${small}</div></body></html>`;
++ }
++ function text({ body, action, footer }: Message) {
++   return [...body, ...(action ? [`${action.label}: ${action.url}`] : []), ...(footer ? [`--\n${footer}`] : [])].join("\n\n");
++ }
++ /** Sends an email; throws when the SMTP server refuses it. */
++ export async function sendMail(message: Message) {
++   if (!MAIL_ENABLED) return;
++   await mailer().sendMail({ from: FROM, to: message.to, subject: `[${BRAND.name}] ${message.subject}`, text: text(message), html: html(message) });
++ }
++ /** Sends an email without waiting for it, for when the request shouldn't fail (or take longer) because of it. */
++ export function sendMailLater(message: Message) {
++   sendMail(message).catch((e) => console.error(`[mail] couldn't send "${message.subject}":`, e instanceof Error ? e.message : e));
++ }

+3−0apps/web/lib/repos.tsView File

@@ -423,15 +423,18 @@ export async function listCollaborators(repoId: string) {
423	423	.sort((a, b) => a.username.localeCompare(b.username));
424	424	}
425	425
	426	+ /** Returns the person, and whether they weren't a collaborator yet. */
426	427	export async function addCollaborator(repo: RepoRecord, username: string) {
427	428	const user = await getPersonByUsername(username.trim());
428	429	if (!user) throw new RepoError(`No user named ${username}.`);
429	430	if (user.id === repo.ownerId) throw new RepoError("The owner already has full access.");
430	431	try {
431	432	await (await db()).collection("collaborators").create({ repo: repo.id, user: user.id, created_at: Date.now() });
	433	+ return { user, added: true };
432	434	} catch (e) {
433	435	// Already a collaborator.
434	436	if (!isUniqueViolation(e)) throw e;
	437	+ return { user, added: false };
435	438	}
436	439	}
437	440

+3−0apps/web/lib/request-origin.tsView File

@@ -9,6 +9,9 @@ const PUBLIC_URL = process.env.PUBLIC_URL ? new URL(process.env.PUBLIC_URL) : nu
9	9	/** Session cookies are marked Secure when the instance is served over HTTPS (or SECURE_COOKIES=1). */
10	10	export const SECURE_COOKIES = process.env.SECURE_COOKIES === "1" \|\| PUBLIC_URL?.protocol === "https:";
11	11
	12	+ /** PUBLIC_URL's origin, or null. Links in emails use it, never the Host header (lib/mail.ts). */
	13	+ export const PUBLIC_ORIGIN = PUBLIC_URL?.origin ?? null;
	14	+
12	15	/** The address users reach this server at, e.g. https://vectrum.cc. */
13	16	export async function serverOrigin() {
14	17	if (PUBLIC_URL) return PUBLIC_URL.origin;

+34−6apps/web/lib/users.tsView File

@@ -16,6 +16,8 @@ export type User = {
16	16	isOrg: boolean;
17	17	/** When an avatar was uploaded (used to bust caches), or null to draw the initials. */
18	18	avatarVersion: number \| null;
	19	+ /** Whether the person confirmed their email address with a link sent to it (lib/emails.ts). */
	20	+ verified: boolean;
19	21	};
20	22
21	23	/** PocketBase dates read "2026-01-02 03:04:05.678Z". */
@@ -31,6 +33,7 @@ export function toUser(r: RecordModel): User {
31	33	createdAt: parseDate(r.created),
32	34	isOrg: r.kind === "org",
33	35	avatarVersion: r.avatar ? orNull(r.avatar_updated_at) : null,
	36	+ verified: !!r.verified,
34	37	};
35	38	}
36	39
@@ -79,10 +82,10 @@ export async function authenticateUser(login: string, password: string) {
79	82	login = login.trim();
80	83	if (!login \|\| !password) return null;
81	84	// PocketBase signs in by email; usernames are resolved here, case-insensitively.
82		- const record = await findFirst("users", filter("kind != 'org' && (username:lower = {:login} \|\| email:lower = {:login})", { login: login.toLowerCase() }));
	85	+ const person = await getPersonByLogin(login);
83	86	try {
84	87	// Unknown logins are still checked, so usernames can't be probed by timing.
85		- const auth = await client().collection("users").authWithPassword(record?.email ?? login, password);
	88	+ const auth = await client().collection("users").authWithPassword(person?.email ?? login, password);
86	89	return { user: toUser(auth.record), token: auth.token };
87	90	} catch (e) {
88	91	if (e instanceof ClientResponseError && e.status === 400) return null;
@@ -95,9 +98,25 @@ export async function verifyUserPassword(userId: string, password: string) {
95	98	return !!user && !!(await authenticateUser(user.email, password));
96	99	}
97	100
98		- /** Changes the password. PocketBase then rejects the user's existing session tokens. */
	101	+ /** Changes the password. PocketBase then rejects the user's existing session tokens, and links to reset it stop working. */
99	102	export async function setPassword(userId: string, password: string) {
100	103	await (await db()).collection("users").update(userId, { password, passwordConfirm: password });
	104	+ await revokeEmailTokens(userId, "reset");
	105	+ }
	106	+
	107	+ /** Makes the unused links emailed to a user (lib/emails.ts) for `purpose` stop working. */
	108	+ export async function revokeEmailTokens(userId: string, purpose: "verify" \| "reset") {
	109	+ const tokens = (await db()).collection("email_tokens");
	110	+ const rows = await tokens.getFullList({ filter: filter("user = {:userId} && purpose = {:purpose}", { userId, purpose }), fields: "id" });
	111	+ await Promise.all(rows.map((r) => tokens.delete(r.id)));
	112	+ }
	113	+
	114	+ /** A person by username or email address, as they sign in. */
	115	+ export async function getPersonByLogin(login: string) {
	116	+ login = login.trim().toLowerCase();
	117	+ if (!login) return null;
	118	+ const record = await findFirst("users", filter("kind != 'org' && (username:lower = {:login} \|\| email:lower = {:login})", { login }));
	119	+ return record ? toUser(record) : null;
101	120	}
102	121
103	122	export async function getUserById(id: string) {
@@ -116,19 +135,28 @@ export async function getPersonByUsername(username: string) {
116	135	return user && !user.isOrg ? user : null;
117	136	}
118	137
119		- /** Returns whether the email changed; PocketBase then rejects the user's existing session tokens. */
	138	+ /**
	139	+ * Returns whether the email changed; PocketBase then rejects the user's existing session tokens. A
	140	+ * new address needs confirming again, and links sent to the old one stop working.
	141	+ */
120	142	export async function updateProfile(userId: string, data: { name: string; email: string; bio: string }) {
121	143	const email = data.email.trim();
122	144	if (!isEmail(email)) throw new UserError("Email address is invalid.");
123	145	if (await emailTaken(email, userId)) throw new UserError("That email address is already in use.");
124	146	const before = await getUserById(userId);
125	147	try {
126		- await (await db()).collection("users").update(userId, { name: data.name.trim().slice(0, 100), email, bio: data.bio.trim().slice(0, 300) });
	148	+ const emailChanged = before?.email !== email;
	149	+ // Not just a change of case.
	150	+ const newAddress = before?.email.toLowerCase() !== email.toLowerCase();
	151	+ await (await db())
	152	+ .collection("users")
	153	+ .update(userId, { name: data.name.trim().slice(0, 100), email, bio: data.bio.trim().slice(0, 300), ...(newAddress && { verified: false }) });
	154	+ if (newAddress) await Promise.all([revokeEmailTokens(userId, "verify"), revokeEmailTokens(userId, "reset")]);
	155	+ return { emailChanged, newAddress };
127	156	} catch (e) {
128	157	if (isUniqueViolation(e)) throw new UserError("That email address is already in use.");
129	158	throw e;
130	159	}
131		- return { emailChanged: before?.email !== email };
132	160	}
133	161
134	162	export async function searchUsers(query: string, limit = 8) {

+1−0apps/web/package.jsonView File

@@ -20,6 +20,7 @@
20	20	"@uiw/react-codemirror": "^4.25.12",
21	21	"@unlocalhosted/metalui": "^0.3.3",
22	22	"next": "16.3.7",
	23	+ "nodemailer": "^10.0.16",
23	24	"pocketbase": "^0.28.1",
24	25	"react": "19.2.8",
25	26	"react-dom": "19.2.8",

+35−0apps/web/pb_migrations/1791700000_email_tokens.jsaddedView File

++ // Links sent by email (lib/emails.ts): "verify" confirms an address, "reset" sets a new password.
++ //
++ // Only a SHA-256 hash of the token in the link is stored. `email` is the address it went to, so a
++ // link stops working once the account's email changes. Only the server (a superuser) reads them.
++ migrate(
++   (app) => {
++     const users = app.findCollectionByNameOrId("users");
++     const collection = new Collection({
++       type: "base",
++       name: "email_tokens",
++       listRule: null,
++       viewRule: null,
++       createRule: null,
++       updateRule: null,
++       deleteRule: null,
++       fields: [
++         { type: "relation", name: "user", collectionId: users.id, maxSelect: 1, required: true, cascadeDelete: true },
++         { type: "select", name: "purpose", values: ["verify", "reset"], maxSelect: 1, required: true },
++         { type: "text", name: "email", max: 200, required: true },
++         { type: "text", name: "token_hash", max: 64, required: true },
++         { type: "number", name: "expires_at", onlyInt: true, min: 0, required: true },
++         { type: "number", name: "created_at", onlyInt: true, min: 0, required: true },
++       ],
++       indexes: [
++         "CREATE UNIQUE INDEX idx_email_tokens_hash ON email_tokens (token_hash)",
++         "CREATE INDEX idx_email_tokens_user ON email_tokens (user, purpose)",
++       ],
++     });
++     app.save(collection);
++   },
++   (app) => {
++     app.delete(app.findCollectionByNameOrId("email_tokens"));
++   },
++ );

+3−0bun.lockView File

@@ -21,6 +21,7 @@
21	21	"@uiw/react-codemirror": "^4.25.12",
22	22	"@unlocalhosted/metalui": "^0.3.3",
23	23	"next": "16.3.7",
	24	+ "nodemailer": "^10.0.16",
24	25	"pocketbase": "^0.28.1",
25	26	"react": "19.2.8",
26	27	"react-dom": "19.2.8",
@@ -1030,6 +1031,8 @@
1030	1031
1031	1032	"node-releases": ["node-releases@2.0.57", "", {}, "sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw=="],
1032	1033
	1034	+ "nodemailer": ["nodemailer@10.0.16", "", {}, "sha512-VL9xKErxN+el77o8eBOuYKUPMyEx7F9hfnDCuiUKJRp9v3wnWMOudYgP/SWbwSHy8rUL4cylobuXtki1LpQS7A=="],
	1035	+
1033	1036	"object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
1034	1037
1035	1038	"object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],

+6−0docker-compose.ymlView File

@@ -18,6 +18,12 @@ services:
18	18	# SSH_HOST: vectrum.example.com
19	19	# Set to 1 to turn off the built-in SSH server (and remove the 2222 port above).
20	20	# SSH_DISABLED: "1"
	21	+ # Send email (address confirmation, password resets, invitations) through this SMTP server.
	22	+ # SMTP_HOST: smtp.example.com
	23	+ # SMTP_PORT: "587" # 465 uses TLS from the start (or set SMTP_SECURE: "1")
	24	+ # SMTP_USER: vectrum@example.com
	25	+ # SMTP_PASSWORD: change-me
	26	+ # MAIL_FROM: Vectrum <vectrum@example.com>
21	27	volumes:
22	28	- vectrum-data:/data # repositories, the PocketBase database and the SSH host key
23	29

+1−0docs/features.mdView File

@@ -1,6 +1,7 @@
1	1	# Features
2	2
3	3	- Accounts: sign up, sign in, profiles, password change (PocketBase auth: bcrypt-hashed passwords, token sessions)
	4	+ - Email through an SMTP server of your own ([Configuration](installation.md#email)): confirming addresses, resetting a forgotten password, organization invitations, collaborator access, and notices when a password or email address changes
4	5	- Two-factor authentication with an authenticator app (TOTP: 1Password, Google Authenticator, Authy…): set up under Settings → Two-factor auth by scanning a QR code, with ten one-time recovery codes for a lost device. It guards signing in with a password, on the website and in the Android app; SSH keys, API tokens and connected apps work as before
5	6	- Repositories: public or private, rename, transfer to an organization (or back to your account), delete, optional README on creation
6	7	- Collaborators: give other users push access to a repository

+22−0docs/installation.mdView File

@@ -46,6 +46,28 @@ To build the image without Compose, run `docker build -f apps/web/Dockerfile -t
46	46	\| `SSH_DISABLED` \| — \| Set to `1` to not start the SSH server \|
47	47	\| `SIGNUPS_DISABLED` \| — \| Set to `1` to close registration (add users with `scripts/create-user.mjs`) \|
48	48	\| `WEBHOOKS_ALLOW_PRIVATE` \| — \| Set to `1` to let webhooks reach private and local addresses (a trusted, single-team server) \|
	49	+ \| `SMTP_HOST` \| — \| SMTP server to send email through (see [Email](#email)); without it, Vectrum sends none \|
	50	+ \| `SMTP_PORT` \| `587` \| Its port \|
	51	+ \| `SMTP_SECURE` \| on for port 465 \| `1` for TLS from the start (port 465); otherwise the connection upgrades with STARTTLS when the server offers it \|
	52	+ \| `SMTP_USER`, `SMTP_PASSWORD` \| — \| Login for the SMTP server, if it needs one \|
	53	+ \| `MAIL_FROM` \| `SMTP_USER` \| Sender, e.g. `Vectrum <noreply@vectrum.cc>` \|
	54	+
	55	+ ### Email
	56	+
	57	+ With `SMTP_HOST` set, Vectrum sends email: a link to confirm the address after signing up or changing it, a link to reset a forgotten password (Forgot your password? on the sign-in page), organization invitations, being added as a collaborator, and notices when an account's password or email address changes. Notifications only go to confirmed addresses. Set `PUBLIC_URL` too, as the links in emails point there.
	58	+
	59	+ Outside Docker, put the settings in `apps/web/.env` (see `apps/web/.env.example`), which Next.js reads on start:
	60	+
	61	+ ```bash
	62	+ SMTP_HOST=smtp.example.com
	63	+ SMTP_PORT=587
	64	+ SMTP_USER=vectrum@example.com
	65	+ SMTP_PASSWORD=…
	66	+ MAIL_FROM="Vectrum <vectrum@example.com>"
	67	+ PUBLIC_URL=https://vectrum.example.com
	68	+ ```
	69	+
	70	+ With Docker Compose, add them under `environment:`, or put them in a `.env` file next to `docker-compose.yml` and list it under `env_file:`. Failures to send are logged.
49	71
50	72	Data layout:
51	73

+1−0docs/security.mdView File

@@ -8,4 +8,5 @@
8	8	- OAuth for agents follows the MCP authorization spec: public clients only, PKCE (S256) required, exact redirect URIs (any port for `localhost`), one-time codes that expire in 5 minutes, access tokens that last an hour, and refresh tokens that rotate on every use (presenting an old one revokes the grant). Only hashes of codes and tokens are stored. The consent page can't be framed, and it shows where it will send you, because anyone can register an application under any name.
9	9	- Release files are always served as `application/octet-stream` attachments with `nosniff` and a sandboxing CSP. Uploads signed in with the browser session must come from the site's own origin; scripts use tokens.
10	10	- Raw files are served with `nosniff` and a sandboxing CSP, so repository HTML/SVG can't run scripts in the app's origin.
	11	+ - Links in emails (confirming an address, resetting a password) carry 256-bit random tokens; only their SHA-256 hashes are stored, with the address they went to, so they stop working when the email changes. Reset links work for an hour, once, and are revoked by any password change. At most one link of a kind goes to an account per minute. Asking for a reset link answers the same for unknown accounts and doesn't wait for the email. Links always use `PUBLIC_URL`, never the request's `Host` header. Notifications only go to confirmed addresses, as anyone can sign up with someone else's.
11	12	- Two-factor authentication (TOTP, RFC 6238) is checked after the password, before any session exists: the password's session token waits on the server for 5 minutes and 5 codes. Wrong codes also count per account (10 in 15 minutes locks codes out for that long). A code works once (also no older one after it), recovery codes are stored as hashes and deleted when used, and the secret is a hidden field only the server reads. Turning 2FA off takes a code.

@@ -1,6 +1,7 @@
1	1	# Features
2	2
3	3	- Accounts: sign up, sign in, profiles, password change (PocketBase auth: bcrypt-hashed passwords, token sessions)
	4	+ - Email through an SMTP server of your own ([Configuration](installation.md#email)): confirming addresses, resetting a forgotten password, organization invitations, collaborator access, and notices when a password or email address changes
4	5	- Two-factor authentication with an authenticator app (TOTP: 1Password, Google Authenticator, Authy…): set up under Settings → Two-factor auth by scanning a QR code, with ten one-time recovery codes for a lost device. It guards signing in with a password, on the website and in the Android app; SSH keys, API tokens and connected apps work as before
5	6	- Repositories: public or private, rename, transfer to an organization (or back to your account), delete, optional README on creation
6	7	- Collaborators: give other users push access to a repository