feat(portal): replace magic-link with email/password + admin-initiated activation

The client portal no longer uses passwordless / magic-link sign-in. Each client now has a `portal_users` row with a scrypt-hashed password, created by an admin from the client detail page; the admin's invite mails an activation link that the client uses to set their own password. Forgot-password is wired through the same token mechanism. Schema (migration `0009_outgoing_rumiko_fujikawa.sql`): - `portal_users` — one per client account, separate from the CRM `users` table (better-auth) so the auth realms stay isolated. Email is globally unique, password is null until activation. - `portal_auth_tokens` — single-use activation / reset tokens. Stores only the SHA-256 hash so a DB compromise never leaks live tokens. Services: - `src/lib/portal/passwords.ts` — scrypt hash/verify (no new deps; uses node:crypto), token mint+hash helpers. - `src/lib/services/portal-auth.service.ts` — createPortalUser, resendActivation, activateAccount, signIn (timing-safe), requestPasswordReset, resetPassword. Auth failures throw the new UnauthorizedError (401); enumeration-safe behaviour everywhere. Routes: - POST /api/portal/auth/sign-in — sets the existing portal JWT cookie. - POST /api/portal/auth/forgot-password — always 200. - POST /api/portal/auth/reset-password — token + new password. - POST /api/portal/auth/activate — token + initial password. - POST /api/v1/clients/:id/portal-user — admin invite (and `?action=resend`). - Removed: /api/portal/auth/request, /api/portal/auth/verify (magic link). UI: - /portal/login — replaced email-only magic-link form with email + password + "forgot password" link. - /portal/forgot-password, /portal/reset-password, /portal/activate — new. - New shared `PasswordSetForm` component used by activate + reset. - New `PortalInviteButton` rendered on the client detail header. Email send: - `createTransporter` now wires SMTP auth when SMTP_USER+SMTP_PASS are set (gmail app-password or marina-server creds, configured via env). - `SMTP_FROM` env var lets the sender address be overridden without pinning it to `noreply@${SMTP_HOST}`. Tests: - Smoke spec 17 (client-portal) updated to the new flow: 7/7 green. - Smoke specs 02-crud-spine, 05-invoices, 20-critical-path updated to match the post-refactor client + invoice forms (drop companyName, use OwnerPicker + billingEmail). - Vitest 652/652 still green; type-check clean. Drops the dead `requestMagicLink` from portal.service.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 15:34:02 +02:00
parent 4da8ed3ae4
commit 475b051e29
33 changed files with 10129 additions and 331 deletions
--- a/src/app/(portal)/portal/activate/page.tsx
+++ b/src/app/(portal)/portal/activate/page.tsx
@@ -0,0 +1,24 @@
+import { Suspense } from 'react';
+
+import { PasswordSetForm } from '@/components/portal/password-set-form';
+
+export default function PortalActivatePage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen flex items-center justify-center bg-gray-50 text-sm text-gray-500">
+          Loading…
+        </div>
+      }
+    >
+      <PasswordSetForm
+        endpoint="/api/portal/auth/activate"
+        title="Activate your account"
+        description="Welcome — choose a password to finish setting up your client portal account."
+        successTitle="Account activated"
+        successDescription="You can now sign in with your new password."
+        submitLabel="Activate account"
+      />
+    </Suspense>
+  );
+}
--- a/src/app/(portal)/portal/forgot-password/page.tsx
+++ b/src/app/(portal)/portal/forgot-password/page.tsx
@@ -0,0 +1,107 @@
+'use client';
+
+import Link from 'next/link';
+import { useState } from 'react';
+import { Loader2, Mail } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+export default function PortalForgotPasswordPage() {
+  const [email, setEmail] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    try {
+      // Always returns 200 — caller never sees whether email exists.
+      await fetch('/api/portal/auth/forgot-password', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email }),
+      });
+    } finally {
+      setSubmitted(true);
+      setLoading(false);
+    }
+  }
+
+  if (submitted) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+        <div className="w-full max-w-md text-center">
+          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
+            <Mail className="h-7 w-7 text-green-600" />
+          </div>
+          <h1 className="text-xl font-semibold text-gray-900 mb-2">Check your email</h1>
+          <p className="text-gray-500 text-sm leading-relaxed">
+            If <strong>{email}</strong> matches a portal account, we&apos;ve sent a reset link. The
+            link expires in 30 minutes.
+          </p>
+          <Link
+            href="/portal/login"
+            className="mt-6 inline-block text-sm text-[#1e2844] hover:underline"
+          >
+            Back to sign in
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+      <div className="w-full max-w-sm">
+        <div className="bg-white rounded-lg border p-8 shadow-sm">
+          <div className="text-center mb-6">
+            <h1 className="text-xl font-semibold text-gray-900">Reset your password</h1>
+            <p className="text-sm text-gray-500 mt-1">
+              Enter your email and we&apos;ll send you a reset link.
+            </p>
+          </div>
+
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-1.5">
+              <Label htmlFor="email">Email address</Label>
+              <Input
+                id="email"
+                type="email"
+                placeholder="you@example.com"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                required
+                autoFocus
+                disabled={loading}
+              />
+            </div>
+
+            <Button
+              type="submit"
+              className="w-full bg-[#1e2844] hover:bg-[#1e2844]/90 text-white"
+              disabled={loading || !email}
+            >
+              {loading ? (
+                <>
+                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                  Sending…
+                </>
+              ) : (
+                'Send reset link'
+              )}
+            </Button>
+          </form>
+
+          <Link
+            href="/portal/login"
+            className="block mt-4 text-center text-xs text-gray-500 hover:underline"
+          >
+            Back to sign in
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
--- a/src/app/(portal)/portal/login/page.tsx
+++ b/src/app/(portal)/portal/login/page.tsx
@@ -1,15 +1,22 @@
 'use client';

+import Link from 'next/link';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { useState } from 'react';
-import { Mail, Loader2 } from 'lucide-react';
+import { Loader2 } from 'lucide-react';
+
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';

 export default function PortalLoginPage() {
+  const router = useRouter();
+  const search = useSearchParams();
+  const next = search.get('next') ?? '/portal/dashboard';
+
  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);
-  const [submitted, setSubmitted] = useState(false);
  const [error, setError] = useState('');

  async function handleSubmit(e: React.FormEvent) {
@@ -18,59 +25,35 @@ export default function PortalLoginPage() {
    setLoading(true);

    try {
-      const res = await fetch('/api/portal/auth/request', {
+      const res = await fetch('/api/portal/auth/sign-in', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email }),
+        body: JSON.stringify({ email, password }),
      });

      if (!res.ok) {
        const data = await res.json().catch(() => ({}));
-        setError((data as { error?: string }).error ?? 'Something went wrong. Please try again.');
+        setError((data as { error?: string }).error ?? 'Invalid email or password');
        return;
      }

-      setSubmitted(true);
+      // typedRoutes: `next` is a runtime string we can't statically check.
+      router.replace(next as never);
+      router.refresh();
    } catch {
-      setError('Unable to connect. Please check your connection and try again.');
+      setError('Unable to connect. Please try again.');
    } finally {
      setLoading(false);
    }
  }

-  if (submitted) {
-    return (
-      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
-        <div className="w-full max-w-md text-center">
-          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
-            <Mail className="h-7 w-7 text-green-600" />
-          </div>
-          <h1 className="text-xl font-semibold text-gray-900 mb-2">Check your email</h1>
-          <p className="text-gray-500 text-sm leading-relaxed">
-            If <strong>{email}</strong> is associated with a client account, you will receive a
-            sign-in link shortly. The link expires in 24 hours.
-          </p>
-          <button
-            type="button"
-            onClick={() => { setSubmitted(false); setEmail(''); }}
-            className="mt-6 text-sm text-[#1e2844] hover:underline"
-          >
-            Try a different email
-          </button>
-        </div>
-      </div>
-    );
-  }
-
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
      <div className="w-full max-w-sm">
        <div className="bg-white rounded-lg border p-8 shadow-sm">
          <div className="text-center mb-6">
            <h1 className="text-xl font-semibold text-gray-900">Client Portal</h1>
-            <p className="text-sm text-gray-500 mt-1">
-              Enter your email to receive a sign-in link
-            </p>
+            <p className="text-sm text-gray-500 mt-1">Sign in to your account</p>
          </div>

          <form onSubmit={handleSubmit} className="space-y-4">
@@ -84,26 +67,46 @@ export default function PortalLoginPage() {
                onChange={(e) => setEmail(e.target.value)}
                required
                autoFocus
+                autoComplete="email"
                disabled={loading}
              />
            </div>

-            {error && (
-              <p className="text-sm text-red-600">{error}</p>
-            )}
+            <div className="space-y-1.5">
+              <div className="flex items-center justify-between">
+                <Label htmlFor="password">Password</Label>
+                <Link
+                  href="/portal/forgot-password"
+                  className="text-xs text-[#1e2844] hover:underline"
+                >
+                  Forgot password?
+                </Link>
+              </div>
+              <Input
+                id="password"
+                type="password"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                required
+                autoComplete="current-password"
+                disabled={loading}
+              />
+            </div>
+
+            {error && <p className="text-sm text-red-600">{error}</p>}

            <Button
              type="submit"
              className="w-full bg-[#1e2844] hover:bg-[#1e2844]/90 text-white"
-              disabled={loading || !email}
+              disabled={loading || !email || !password}
            >
              {loading ? (
                <>
                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
-                  Sending link...
+                  Signing in…
                </>
              ) : (
-                'Send sign-in link'
+                'Sign in'
              )}
            </Button>
          </form>
--- a/src/app/(portal)/portal/reset-password/page.tsx
+++ b/src/app/(portal)/portal/reset-password/page.tsx
@@ -0,0 +1,24 @@
+import { Suspense } from 'react';
+
+import { PasswordSetForm } from '@/components/portal/password-set-form';
+
+export default function PortalResetPasswordPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen flex items-center justify-center bg-gray-50 text-sm text-gray-500">
+          Loading…
+        </div>
+      }
+    >
+      <PasswordSetForm
+        endpoint="/api/portal/auth/reset-password"
+        title="Choose a new password"
+        description="Enter a new password to regain access to your client portal."
+        successTitle="Password updated"
+        successDescription="You can now sign in with your new password."
+        submitLabel="Update password"
+      />
+    </Suspense>
+  );
+}
--- a/src/app/(portal)/portal/verify/page.tsx
+++ b/src/app/(portal)/portal/verify/page.tsx
@@ -1,49 +0,0 @@
-'use client';
-
-import { Suspense, useEffect, useRef } from 'react';
-import { useRouter, useSearchParams } from 'next/navigation';
-import { Loader2 } from 'lucide-react';
-
-function PortalVerifyInner() {
-  const router = useRouter();
-  const searchParams = useSearchParams();
-  const calledRef = useRef(false);
-
-  useEffect(() => {
-    if (calledRef.current) return;
-    calledRef.current = true;
-
-    const token = searchParams.get('token');
-
-    if (!token) {
-      router.replace('/portal/login?error=missing_token');
-      return;
-    }
-
-    // Redirect to the verify API route which will set the cookie and redirect
-    window.location.href = `/api/portal/auth/verify?token=${encodeURIComponent(token)}`;
-  }, [searchParams, router]);
-
-  return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50">
-      <div className="text-center">
-        <Loader2 className="h-8 w-8 animate-spin text-[#1e2844] mx-auto mb-3" />
-        <p className="text-sm text-gray-500">Verifying your access...</p>
-      </div>
-    </div>
-  );
-}
-
-export default function PortalVerifyPage() {
-  return (
-    <Suspense
-      fallback={
-        <div className="min-h-screen flex items-center justify-center bg-gray-50">
-          <Loader2 className="h-8 w-8 animate-spin text-[#1e2844]" />
-        </div>
-      }
-    >
-      <PortalVerifyInner />
-    </Suspense>
-  );
-}
--- a/src/app/api/portal/auth/activate/route.ts
+++ b/src/app/api/portal/auth/activate/route.ts
@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { activateAccount } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  token: z.string().min(1),
+  password: z.string().min(12),
+});
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.errors[0]?.message ?? 'Invalid input' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    await activateAccount(parsed.data.token, parsed.data.password);
+    return NextResponse.json({ success: true });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
--- a/src/app/api/portal/auth/forgot-password/route.ts
+++ b/src/app/api/portal/auth/forgot-password/route.ts
@@ -0,0 +1,30 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { logger } from '@/lib/logger';
+import { requestPasswordReset } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({ email: z.string().email() });
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid email address' }, { status: 400 });
+  }
+
+  // Always return 200 to prevent account-enumeration. Errors are logged
+  // server-side, never surfaced to the client.
+  try {
+    await requestPasswordReset(parsed.data.email);
+  } catch (err) {
+    logger.error({ err }, 'Portal forgot-password failed (swallowed)');
+  }
+  return NextResponse.json({ success: true });
+}
--- a/src/app/api/portal/auth/request/route.ts
+++ b/src/app/api/portal/auth/request/route.ts
@@ -1,28 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { z } from 'zod';
-
-import { requestMagicLink } from '@/lib/services/portal.service';
-import { logger } from '@/lib/logger';
-
-const bodySchema = z.object({
-  email: z.string().email(),
-});
-
-export async function POST(req: NextRequest): Promise<NextResponse> {
-  try {
-    const body = await req.json();
-    const parsed = bodySchema.safeParse(body);
-
-    if (!parsed.success) {
-      return NextResponse.json({ error: 'Invalid email address' }, { status: 400 });
-    }
-
-    await requestMagicLink(parsed.data.email);
-
-    // Always return success to prevent email enumeration
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    logger.error({ error }, 'Portal magic link request failed');
-    return NextResponse.json({ error: 'Failed to process request' }, { status: 500 });
-  }
-}
--- a/src/app/api/portal/auth/reset-password/route.ts
+++ b/src/app/api/portal/auth/reset-password/route.ts
@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { resetPassword } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  token: z.string().min(1),
+  password: z.string().min(12),
+});
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.errors[0]?.message ?? 'Invalid input' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    await resetPassword(parsed.data.token, parsed.data.password);
+    return NextResponse.json({ success: true });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
--- a/src/app/api/portal/auth/sign-in/route.ts
+++ b/src/app/api/portal/auth/sign-in/route.ts
@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { PORTAL_COOKIE } from '@/lib/portal/auth';
+import { signIn } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24; // 24h, matches createPortalToken
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid email or password' }, { status: 400 });
+  }
+
+  try {
+    const result = await signIn(parsed.data);
+    const res = NextResponse.json({ success: true });
+    res.cookies.set(PORTAL_COOKIE, result.token, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      path: '/',
+      maxAge: SESSION_MAX_AGE_SECONDS,
+    });
+    return res;
+  } catch (err) {
+    return errorResponse(err);
+  }
+}
--- a/src/app/api/portal/auth/verify/route.ts
+++ b/src/app/api/portal/auth/verify/route.ts
@@ -1,38 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-
-import { verifyPortalToken, PORTAL_COOKIE } from '@/lib/portal/auth';
-import { env } from '@/lib/env';
-import { logger } from '@/lib/logger';
-
-export async function GET(req: NextRequest): Promise<NextResponse> {
-  try {
-    const token = req.nextUrl.searchParams.get('token');
-
-    if (!token) {
-      return NextResponse.redirect(new URL('/portal/login?error=missing_token', env.APP_URL));
-    }
-
-    const session = await verifyPortalToken(token);
-
-    if (!session) {
-      return NextResponse.redirect(new URL('/portal/login?error=invalid_token', env.APP_URL));
-    }
-
-    const response = NextResponse.redirect(new URL('/portal/dashboard', env.APP_URL));
-
-    response.cookies.set(PORTAL_COOKIE, token, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
-      sameSite: 'lax',
-      path: '/',
-      maxAge: 60 * 60 * 24, // 24 hours
-    });
-
-    logger.info({ clientId: session.clientId }, 'Portal session created');
-
-    return response;
-  } catch (error) {
-    logger.error({ error }, 'Portal token verification failed');
-    return NextResponse.redirect(new URL('/portal/login?error=server_error', env.APP_URL));
-  }
-}
--- a/src/app/api/v1/clients/[id]/portal-user/route.ts
+++ b/src/app/api/v1/clients/[id]/portal-user/route.ts
@@ -0,0 +1,59 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createPortalUser, resendActivation } from '@/lib/services/portal-auth.service';
+import { db } from '@/lib/db';
+import { eq } from 'drizzle-orm';
+import { portalUsers } from '@/lib/db/schema/portal';
+
+const inviteSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(200).optional(),
+});
+
+/**
+ * POST /api/v1/clients/:id/portal-user
+ *
+ * Admin creates a portal account for a client and triggers the activation
+ * email. Idempotent in spirit: if a portal user already exists for the
+ * email, returns 409 — the admin can resend the activation via
+ * ?action=resend.
+ */
+export const POST = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const url = new URL(req.url);
+      const action = url.searchParams.get('action');
+
+      if (action === 'resend') {
+        // Body is optional in resend mode; the portal user id is the path id
+        // in this case (not the client id). Looking up by client+email so
+        // admins don't have to track portal-user ids.
+        const body = await parseBody(req, inviteSchema);
+        const existing = await db.query.portalUsers.findFirst({
+          where: eq(portalUsers.email, body.email.toLowerCase().trim()),
+        });
+        if (!existing) {
+          return NextResponse.json({ error: 'Portal user not found' }, { status: 404 });
+        }
+        await resendActivation(existing.id, ctx.portId);
+        return NextResponse.json({ success: true });
+      }
+
+      const body = await parseBody(req, inviteSchema);
+      const result = await createPortalUser({
+        clientId: params.id!,
+        portId: ctx.portId,
+        email: body.email,
+        name: body.name,
+        createdBy: ctx.userId,
+      });
+      return NextResponse.json({ data: result }, { status: 201 });
+    } catch (err) {
+      return errorResponse(err);
+    }
+  }),
+);
--- a/src/components/clients/client-detail-header.tsx
+++ b/src/components/clients/client-detail-header.tsx
@@ -9,6 +9,7 @@ import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
 import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
 import { ClientForm } from '@/components/clients/client-form';
+import { PortalInviteButton } from '@/components/clients/portal-invite-button';
 import { apiFetch } from '@/lib/api/client';

 interface ClientDetailHeaderProps {
@@ -127,6 +128,13 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {

          {/* Actions */}
          <div className="flex items-center gap-2">
+            {!isArchived && (
+              <PortalInviteButton
+                clientId={client.id}
+                clientName={client.fullName}
+                defaultEmail={primaryEmail?.value}
+              />
+            )}
            <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
              <Pencil className="mr-1.5 h-3.5 w-3.5" />
              Edit
--- a/src/components/clients/portal-invite-button.tsx
+++ b/src/components/clients/portal-invite-button.tsx
@@ -0,0 +1,154 @@
+'use client';
+
+import { useState } from 'react';
+import { UserPlus, Loader2, Check } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { apiFetch } from '@/lib/api/client';
+
+interface PortalInviteButtonProps {
+  clientId: string;
+  clientName: string;
+  defaultEmail?: string;
+}
+
+/**
+ * Admin button on the client detail header that creates a portal user for
+ * the client and sends them an activation email. Uses the client's primary
+ * email as the default but lets the admin override.
+ */
+export function PortalInviteButton({
+  clientId,
+  clientName,
+  defaultEmail,
+}: PortalInviteButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState(defaultEmail ?? '');
+  const [name, setName] = useState(clientName);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [success, setSuccess] = useState(false);
+
+  function reset() {
+    setEmail(defaultEmail ?? '');
+    setName(clientName);
+    setError('');
+    setSuccess(false);
+    setLoading(false);
+  }
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      await apiFetch(`/api/v1/clients/${clientId}/portal-user`, {
+        method: 'POST',
+        body: { email, name },
+      });
+      setSuccess(true);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to send invitation');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => {
+          reset();
+          setOpen(true);
+        }}
+      >
+        <UserPlus className="mr-1.5 h-3.5 w-3.5" />
+        Invite to portal
+      </Button>
+
+      <Dialog
+        open={open}
+        onOpenChange={(o) => {
+          if (!o) reset();
+          setOpen(o);
+        }}
+      >
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Invite to client portal</DialogTitle>
+            <DialogDescription>
+              We&apos;ll email an activation link. The client picks their own password from there.
+            </DialogDescription>
+          </DialogHeader>
+
+          {success ? (
+            <div className="py-4 flex items-center gap-3 text-sm text-green-700">
+              <Check className="h-5 w-5" />
+              Activation email sent to <strong>{email}</strong>.
+            </div>
+          ) : (
+            <form onSubmit={submit} className="space-y-4 py-2">
+              <div className="space-y-1.5">
+                <Label htmlFor="invite-email">Email address</Label>
+                <Input
+                  id="invite-email"
+                  type="email"
+                  required
+                  autoFocus
+                  value={email}
+                  onChange={(e) => setEmail(e.target.value)}
+                  disabled={loading}
+                  placeholder="client@example.com"
+                />
+              </div>
+              <div className="space-y-1.5">
+                <Label htmlFor="invite-name">Display name (optional)</Label>
+                <Input
+                  id="invite-name"
+                  value={name}
+                  onChange={(e) => setName(e.target.value)}
+                  disabled={loading}
+                />
+              </div>
+              {error && <p className="text-sm text-destructive">{error}</p>}
+            </form>
+          )}
+
+          <DialogFooter>
+            {success ? (
+              <Button onClick={() => setOpen(false)}>Done</Button>
+            ) : (
+              <>
+                <Button type="button" variant="outline" onClick={() => setOpen(false)}>
+                  Cancel
+                </Button>
+                <Button onClick={submit} disabled={loading || !email}>
+                  {loading ? (
+                    <>
+                      <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                      Sending…
+                    </>
+                  ) : (
+                    'Send invitation'
+                  )}
+                </Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
--- a/src/components/portal/password-set-form.tsx
+++ b/src/components/portal/password-set-form.tsx
@@ -0,0 +1,181 @@
+'use client';
+
+import Link from 'next/link';
+import { useSearchParams } from 'next/navigation';
+import { useState } from 'react';
+import { CheckCircle2, Loader2 } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+interface PasswordSetFormProps {
+  /** API endpoint that accepts `{ token, password }` and sets / resets the password. */
+  endpoint: string;
+  title: string;
+  description: string;
+  successTitle: string;
+  successDescription: string;
+  submitLabel: string;
+}
+
+const MIN_LENGTH = 12;
+
+/**
+ * Shared form used by both the activation and password-reset flows. The
+ * activation token is read from the `?token=` query string. Empty / missing
+ * tokens land the user in an explicit error state instead of submitting a
+ * doomed request.
+ */
+export function PasswordSetForm({
+  endpoint,
+  title,
+  description,
+  successTitle,
+  successDescription,
+  submitLabel,
+}: PasswordSetFormProps) {
+  const search = useSearchParams();
+  const token = search.get('token') ?? '';
+
+  const [password, setPassword] = useState('');
+  const [confirm, setConfirm] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [done, setDone] = useState(false);
+
+  const tooShort = password.length > 0 && password.length < MIN_LENGTH;
+  const mismatch = confirm.length > 0 && password !== confirm;
+  const canSubmit = !!token && password.length >= MIN_LENGTH && password === confirm && !loading;
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!canSubmit) return;
+    setLoading(true);
+    setError('');
+    try {
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token, password }),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        setError((data as { error?: string }).error ?? 'Something went wrong. Please try again.');
+        return;
+      }
+      setDone(true);
+    } catch {
+      setError('Unable to connect. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (!token) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+        <div className="w-full max-w-md text-center space-y-3">
+          <h1 className="text-xl font-semibold text-gray-900">Link is missing or invalid</h1>
+          <p className="text-sm text-gray-500">
+            Please use the link from the email we sent you. If the link is broken, request a new
+            one.
+          </p>
+          <Link
+            href="/portal/forgot-password"
+            className="inline-block text-sm text-[#1e2844] hover:underline"
+          >
+            Request a new link
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  if (done) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+        <div className="w-full max-w-md text-center">
+          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
+            <CheckCircle2 className="h-7 w-7 text-green-600" />
+          </div>
+          <h1 className="text-xl font-semibold text-gray-900 mb-2">{successTitle}</h1>
+          <p className="text-gray-500 text-sm">{successDescription}</p>
+          <Link
+            href="/portal/login"
+            className="mt-6 inline-block text-sm text-[#1e2844] hover:underline"
+          >
+            Sign in
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+      <div className="w-full max-w-sm">
+        <div className="bg-white rounded-lg border p-8 shadow-sm">
+          <div className="mb-6">
+            <h1 className="text-xl font-semibold text-gray-900">{title}</h1>
+            <p className="text-sm text-gray-500 mt-1">{description}</p>
+          </div>
+
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-1.5">
+              <Label htmlFor="password">New password</Label>
+              <Input
+                id="password"
+                type="password"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                required
+                autoFocus
+                autoComplete="new-password"
+                minLength={MIN_LENGTH}
+                disabled={loading}
+              />
+              <p className="text-xs text-gray-500">At least {MIN_LENGTH} characters.</p>
+              {tooShort && (
+                <p className="text-xs text-red-600">
+                  Password must be at least {MIN_LENGTH} characters.
+                </p>
+              )}
+            </div>
+
+            <div className="space-y-1.5">
+              <Label htmlFor="confirm">Confirm password</Label>
+              <Input
+                id="confirm"
+                type="password"
+                value={confirm}
+                onChange={(e) => setConfirm(e.target.value)}
+                required
+                autoComplete="new-password"
+                disabled={loading}
+              />
+              {mismatch && <p className="text-xs text-red-600">Passwords don&apos;t match.</p>}
+            </div>
+
+            {error && <p className="text-sm text-red-600">{error}</p>}
+
+            <Button
+              type="submit"
+              className="w-full bg-[#1e2844] hover:bg-[#1e2844]/90 text-white"
+              disabled={!canSubmit}
+            >
+              {loading ? (
+                <>
+                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                  Saving…
+                </>
+              ) : (
+                submitLabel
+              )}
+            </Button>
+          </form>
+        </div>
+      </div>
+    </div>
+  );
+}
--- a/src/lib/db/migrations/0009_outgoing_rumiko_fujikawa.sql
+++ b/src/lib/db/migrations/0009_outgoing_rumiko_fujikawa.sql
@@ -0,0 +1,32 @@
+CREATE TABLE "portal_auth_tokens" (
+	"id" text PRIMARY KEY NOT NULL,
+	"portal_user_id" text NOT NULL,
+	"token_hash" text NOT NULL,
+	"type" text NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"used_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "portal_users" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"client_id" text NOT NULL,
+	"email" text NOT NULL,
+	"password_hash" text,
+	"name" text,
+	"is_active" boolean DEFAULT true NOT NULL,
+	"last_login_at" timestamp with time zone,
+	"created_by" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "portal_auth_tokens" ADD CONSTRAINT "portal_auth_tokens_portal_user_id_portal_users_id_fk" FOREIGN KEY ("portal_user_id") REFERENCES "public"."portal_users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "portal_users" ADD CONSTRAINT "portal_users_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "portal_users" ADD CONSTRAINT "portal_users_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_portal_tokens_hash_unique" ON "portal_auth_tokens" USING btree ("token_hash");--> statement-breakpoint
+CREATE INDEX "idx_portal_tokens_user" ON "portal_auth_tokens" USING btree ("portal_user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_portal_users_email_unique" ON "portal_users" USING btree ("email");--> statement-breakpoint
+CREATE INDEX "idx_portal_users_client" ON "portal_users" USING btree ("client_id");--> statement-breakpoint
+CREATE INDEX "idx_portal_users_port" ON "portal_users" USING btree ("port_id");
--- a/src/lib/db/migrations/meta/0009_snapshot.json
+++ b/src/lib/db/migrations/meta/0009_snapshot.json
--- a/src/lib/db/migrations/meta/_journal.json
+++ b/src/lib/db/migrations/meta/_journal.json
@@ -64,6 +64,13 @@
      "when": 1777204563579,
      "tag": "0008_loud_ikaris",
      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1777210206070,
+      "tag": "0009_outgoing_rumiko_fujikawa",
+      "breakpoints": true
    }
  ]
 }
--- a/src/lib/db/schema/index.ts
+++ b/src/lib/db/schema/index.ts
@@ -31,6 +31,9 @@ export * from './financial';
 // Email
 export * from './email';

+// Portal (client-portal auth)
+export * from './portal';
+
 // Operations
 export * from './operations';

--- a/src/lib/db/schema/portal.ts
+++ b/src/lib/db/schema/portal.ts
@@ -0,0 +1,76 @@
+import { pgTable, text, boolean, timestamp, index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+import { ports } from './ports';
+import { clients } from './clients';
+
+/**
+ * Portal users — one per client account that's been invited to the client
+ * portal. Separate from the CRM `users` table (managed by better-auth) so the
+ * authentication realms stay isolated.
+ *
+ * Created by an admin from the client detail page; the admin's invite mails
+ * an activation token that lets the client set their own password.
+ */
+export const portalUsers = pgTable(
+  'portal_users',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id),
+    clientId: text('client_id')
+      .notNull()
+      .references(() => clients.id, { onDelete: 'cascade' }),
+    email: text('email').notNull(),
+    /**
+     * scrypt-hashed password. Format: `salt:keyHex` (both base64url). Null
+     * until the user activates their account.
+     */
+    passwordHash: text('password_hash'),
+    name: text('name'),
+    isActive: boolean('is_active').notNull().default(true),
+    lastLoginAt: timestamp('last_login_at', { withTimezone: true }),
+    createdBy: text('created_by').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('idx_portal_users_email_unique').on(table.email),
+    index('idx_portal_users_client').on(table.clientId),
+    index('idx_portal_users_port').on(table.portId),
+  ],
+);
+
+/**
+ * Single-use tokens for portal-account activation and password reset.
+ *
+ * `tokenHash` is a SHA-256 hash of the raw token sent in the email. Lookups
+ * happen by hash so a DB compromise never leaks active tokens.
+ */
+export const portalAuthTokens = pgTable(
+  'portal_auth_tokens',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portalUserId: text('portal_user_id')
+      .notNull()
+      .references(() => portalUsers.id, { onDelete: 'cascade' }),
+    tokenHash: text('token_hash').notNull(),
+    type: text('type').notNull(), // 'activation' | 'reset'
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    usedAt: timestamp('used_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('idx_portal_tokens_hash_unique').on(table.tokenHash),
+    index('idx_portal_tokens_user').on(table.portalUserId),
+  ],
+);
+
+export type PortalUser = typeof portalUsers.$inferSelect;
+export type NewPortalUser = typeof portalUsers.$inferInsert;
+export type PortalAuthToken = typeof portalAuthTokens.$inferSelect;
+export type NewPortalAuthToken = typeof portalAuthTokens.$inferInsert;
--- a/src/lib/email/index.ts
+++ b/src/lib/email/index.ts
@@ -16,6 +16,9 @@ export function createTransporter(): Transporter {
    port: env.SMTP_PORT,
    // Implicitly secure when port is 465; STARTTLS for all other ports.
    secure: env.SMTP_PORT === 465,
+    ...(env.SMTP_USER && env.SMTP_PASS
+      ? { auth: { user: env.SMTP_USER, pass: env.SMTP_PASS } }
+      : {}),
  });
 }

@@ -43,7 +46,7 @@ export async function sendEmail(
  const transporter = createTransporter();

  const info = await transporter.sendMail({
-    from: from ?? `Port Nimara CRM <noreply@${env.SMTP_HOST}>`,
+    from: from ?? env.SMTP_FROM ?? `Port Nimara CRM <noreply@${env.SMTP_HOST}>`,
    to: Array.isArray(to) ? to.join(', ') : to,
    subject,
    html,
--- a/src/lib/env.ts
+++ b/src/lib/env.ts
@@ -32,6 +32,9 @@ const envSchema = z.object({
  // Email
  SMTP_HOST: z.string().min(1),
  SMTP_PORT: z.coerce.number().int().positive(),
+  SMTP_USER: z.string().optional(),
+  SMTP_PASS: z.string().optional(),
+  SMTP_FROM: z.string().optional(),

  // Encryption
  EMAIL_CREDENTIAL_KEY: z
--- a/src/lib/errors.ts
+++ b/src/lib/errors.ts
@@ -26,6 +26,12 @@ export class ForbiddenError extends AppError {
  }
 }

+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(401, message, 'UNAUTHORIZED');
+  }
+}
+
 export class ValidationError extends AppError {
  constructor(
    message: string,
--- a/src/lib/portal/passwords.ts
+++ b/src/lib/portal/passwords.ts
@@ -0,0 +1,60 @@
+import { randomBytes, scrypt as scryptCb, timingSafeEqual, createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scrypt = promisify(scryptCb) as (
+  password: string,
+  salt: Buffer,
+  keyLen: number,
+) => Promise<Buffer>;
+
+const KEY_LENGTH = 64;
+const SALT_LENGTH = 16;
+
+/**
+ * Hash a password with a fresh random salt. Stored format is
+ * `salt:keyHex` (both as hex strings) so verification can re-derive without
+ * a separate salt column.
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_LENGTH);
+  const key = await scrypt(password, salt, KEY_LENGTH);
+  return `${salt.toString('hex')}:${key.toString('hex')}`;
+}
+
+/**
+ * Constant-time check of a candidate password against a stored
+ * `salt:keyHex` hash. Returns false on any malformed input rather than
+ * throwing — callers should treat false uniformly.
+ */
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const parts = stored.split(':');
+  if (parts.length !== 2) return false;
+  const [saltHex, keyHex] = parts;
+  if (!saltHex || !keyHex) return false;
+  let salt: Buffer;
+  let expected: Buffer;
+  try {
+    salt = Buffer.from(saltHex, 'hex');
+    expected = Buffer.from(keyHex, 'hex');
+  } catch {
+    return false;
+  }
+  if (expected.length !== KEY_LENGTH) return false;
+  const candidate = await scrypt(password, salt, KEY_LENGTH);
+  return timingSafeEqual(candidate, expected);
+}
+
+/**
+ * Mint a fresh raw token (returned to the caller) and its SHA-256 hash
+ * (stored in the DB). The raw token is meant to be embedded in a one-shot
+ * URL; only the hash persists.
+ */
+export function mintToken(byteLength = 32): { raw: string; hash: string } {
+  const raw = randomBytes(byteLength).toString('base64url');
+  const hash = createHash('sha256').update(raw).digest('hex');
+  return { raw, hash };
+}
+
+export function hashToken(raw: string): string {
+  return createHash('sha256').update(raw).digest('hex');
+}
--- a/src/lib/services/portal-auth.service.ts
+++ b/src/lib/services/portal-auth.service.ts
@@ -0,0 +1,286 @@
+import { and, eq, gt, isNull } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { clients } from '@/lib/db/schema/clients';
+import { ports } from '@/lib/db/schema/ports';
+import { portalAuthTokens, portalUsers } from '@/lib/db/schema/portal';
+import { env } from '@/lib/env';
+import { sendEmail } from '@/lib/email';
+import { ConflictError, NotFoundError, UnauthorizedError, ValidationError } from '@/lib/errors';
+import { logger } from '@/lib/logger';
+import { createPortalToken } from '@/lib/portal/auth';
+import { hashPassword, hashToken, mintToken, verifyPassword } from '@/lib/portal/passwords';
+
+const ACTIVATION_TOKEN_TTL_HOURS = 72;
+const RESET_TOKEN_TTL_MINUTES = 30;
+const MIN_PASSWORD_LENGTH = 12;
+
+// ─── Admin-side: invite a client to the portal ───────────────────────────────
+
+export async function createPortalUser(args: {
+  clientId: string;
+  portId: string;
+  email: string;
+  name?: string;
+  createdBy: string;
+}): Promise<{ portalUserId: string }> {
+  const normalizedEmail = args.email.toLowerCase().trim();
+
+  const client = await db.query.clients.findFirst({
+    where: and(eq(clients.id, args.clientId), eq(clients.portId, args.portId)),
+  });
+  if (!client) throw new NotFoundError('Client');
+
+  // Email uniqueness check is enforced at the DB level too, but we do a
+  // friendlier preflight so the admin sees a clear conflict error.
+  const existing = await db.query.portalUsers.findFirst({
+    where: eq(portalUsers.email, normalizedEmail),
+  });
+  if (existing) {
+    throw new ConflictError(`A portal user already exists for ${normalizedEmail}`);
+  }
+
+  const [user] = await db
+    .insert(portalUsers)
+    .values({
+      portId: args.portId,
+      clientId: args.clientId,
+      email: normalizedEmail,
+      name: args.name ?? client.fullName,
+      createdBy: args.createdBy,
+    })
+    .returning({ id: portalUsers.id });
+
+  if (!user) {
+    throw new Error('Failed to create portal user');
+  }
+
+  await issueActivationToken(user.id, normalizedEmail, args.portId);
+
+  return { portalUserId: user.id };
+}
+
+async function issueActivationToken(
+  portalUserId: string,
+  email: string,
+  portId: string,
+): Promise<void> {
+  const { raw, hash } = mintToken();
+  const expiresAt = new Date(Date.now() + ACTIVATION_TOKEN_TTL_HOURS * 3600 * 1000);
+
+  await db.insert(portalAuthTokens).values({
+    portalUserId,
+    tokenHash: hash,
+    type: 'activation',
+    expiresAt,
+  });
+
+  const port = await db.query.ports.findFirst({ where: eq(ports.id, portId) });
+  const portName = port?.name ?? 'Port Nimara';
+
+  const link = `${env.APP_URL}/portal/activate?token=${encodeURIComponent(raw)}`;
+  const subject = `Activate your ${portName} client portal account`;
+  const html = activationEmailHtml({ portName, link, ttlHours: ACTIVATION_TOKEN_TTL_HOURS });
+
+  try {
+    await sendEmail(email, subject, html);
+  } catch (err) {
+    logger.error({ err, email }, 'Failed to send portal activation email');
+    // Re-throw — the admin should know if their invite mail bounced.
+    throw err;
+  }
+}
+
+export async function resendActivation(portalUserId: string, portId: string): Promise<void> {
+  const user = await db.query.portalUsers.findFirst({
+    where: and(eq(portalUsers.id, portalUserId), eq(portalUsers.portId, portId)),
+  });
+  if (!user) throw new NotFoundError('Portal user');
+  if (user.passwordHash) {
+    throw new ConflictError('Portal user has already activated their account');
+  }
+  await issueActivationToken(user.id, user.email, user.portId);
+}
+
+// ─── Activation: client sets their initial password ──────────────────────────
+
+export async function activateAccount(rawToken: string, password: string): Promise<void> {
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    throw new ValidationError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+  const tokenRow = await consumeToken(rawToken, 'activation');
+  const passwordHash = await hashPassword(password);
+  await db
+    .update(portalUsers)
+    .set({ passwordHash, updatedAt: new Date() })
+    .where(eq(portalUsers.id, tokenRow.portalUserId));
+}
+
+// ─── Sign in (email + password) ──────────────────────────────────────────────
+
+export async function signIn(args: {
+  email: string;
+  password: string;
+}): Promise<{ token: string; clientId: string; portId: string; email: string }> {
+  const normalizedEmail = args.email.toLowerCase().trim();
+
+  // Always do the same amount of work regardless of whether the email
+  // exists, so timing doesn't leak account presence.
+  const user = await db.query.portalUsers.findFirst({
+    where: eq(portalUsers.email, normalizedEmail),
+  });
+
+  // Dummy hash with the right shape — used to keep verifyPassword's compute
+  // cost identical when the user doesn't exist.
+  const dummyHash =
+    '0000000000000000000000000000000000000000000000000000000000000000:00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000';
+
+  const ok = user?.passwordHash
+    ? await verifyPassword(args.password, user.passwordHash)
+    : (await verifyPassword(args.password, dummyHash), false);
+
+  if (!user || !user.isActive || !user.passwordHash || !ok) {
+    throw new UnauthorizedError('Invalid email or password');
+  }
+
+  const token = await createPortalToken({
+    clientId: user.clientId,
+    portId: user.portId,
+    email: user.email,
+  });
+
+  await db.update(portalUsers).set({ lastLoginAt: new Date() }).where(eq(portalUsers.id, user.id));
+
+  return { token, clientId: user.clientId, portId: user.portId, email: user.email };
+}
+
+// ─── Forgot password ─────────────────────────────────────────────────────────
+
+export async function requestPasswordReset(email: string): Promise<void> {
+  const normalizedEmail = email.toLowerCase().trim();
+
+  const user = await db.query.portalUsers.findFirst({
+    where: eq(portalUsers.email, normalizedEmail),
+  });
+
+  if (!user || !user.isActive) {
+    // Silently no-op so unknown emails don't leak through timing or
+    // response shape. Caller surfaces "if the email matches an account…".
+    logger.debug({ email: normalizedEmail }, 'Password reset for unknown email');
+    return;
+  }
+
+  const { raw, hash } = mintToken();
+  const expiresAt = new Date(Date.now() + RESET_TOKEN_TTL_MINUTES * 60 * 1000);
+
+  await db.insert(portalAuthTokens).values({
+    portalUserId: user.id,
+    tokenHash: hash,
+    type: 'reset',
+    expiresAt,
+  });
+
+  const port = await db.query.ports.findFirst({ where: eq(ports.id, user.portId) });
+  const portName = port?.name ?? 'Port Nimara';
+  const link = `${env.APP_URL}/portal/reset-password?token=${encodeURIComponent(raw)}`;
+
+  try {
+    await sendEmail(
+      user.email,
+      `Reset your ${portName} client portal password`,
+      resetEmailHtml({ portName, link, ttlMinutes: RESET_TOKEN_TTL_MINUTES }),
+    );
+  } catch (err) {
+    logger.error({ err, email: user.email }, 'Failed to send password-reset email');
+    // Don't propagate — the public route returns 200 either way.
+  }
+}
+
+export async function resetPassword(rawToken: string, password: string): Promise<void> {
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    throw new ValidationError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+  const tokenRow = await consumeToken(rawToken, 'reset');
+  const passwordHash = await hashPassword(password);
+  await db
+    .update(portalUsers)
+    .set({ passwordHash, updatedAt: new Date() })
+    .where(eq(portalUsers.id, tokenRow.portalUserId));
+}
+
+// ─── Token consumption (shared between activation + reset) ───────────────────
+
+async function consumeToken(
+  rawToken: string,
+  type: 'activation' | 'reset',
+): Promise<{ portalUserId: string }> {
+  const tokenHash = hashToken(rawToken);
+  const now = new Date();
+
+  const row = await db.query.portalAuthTokens.findFirst({
+    where: and(
+      eq(portalAuthTokens.tokenHash, tokenHash),
+      eq(portalAuthTokens.type, type),
+      isNull(portalAuthTokens.usedAt),
+      gt(portalAuthTokens.expiresAt, now),
+    ),
+  });
+
+  if (!row) {
+    throw new ValidationError('Invalid or expired token');
+  }
+
+  await db.update(portalAuthTokens).set({ usedAt: now }).where(eq(portalAuthTokens.id, row.id));
+
+  return { portalUserId: row.portalUserId };
+}
+
+// ─── Email templates ─────────────────────────────────────────────────────────
+
+function activationEmailHtml(args: { portName: string; link: string; ttlHours: number }): string {
+  return `
+    <!DOCTYPE html>
+    <html><body style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#f5f5f5;padding:40px 0;margin:0;">
+      <div style="max-width:480px;margin:0 auto;background:#fff;border-radius:8px;overflow:hidden;box-shadow:0 2px 8px rgba(0,0,0,0.08);">
+        <div style="background:#1e2844;padding:32px 40px;text-align:center;">
+          <h1 style="color:#fff;margin:0;font-size:22px;font-weight:600;">${args.portName}</h1>
+          <p style="color:#9ca3af;margin:6px 0 0;font-size:14px;">Client Portal</p>
+        </div>
+        <div style="padding:40px;">
+          <p style="color:#374151;font-size:16px;margin:0 0 16px;">Welcome,</p>
+          <p style="color:#6b7280;font-size:15px;line-height:1.6;margin:0 0 32px;">
+            You've been invited to access the ${args.portName} client portal. Click the button below to set your password and activate your account. The link expires in ${args.ttlHours} hours.
+          </p>
+          <div style="text-align:center;margin:0 0 32px;">
+            <a href="${args.link}" style="display:inline-block;background:#1e2844;color:#fff;text-decoration:none;padding:14px 32px;border-radius:6px;font-size:15px;font-weight:500;">Activate account</a>
+          </div>
+          <p style="color:#9ca3af;font-size:13px;margin:0;line-height:1.5;">If the button doesn't work, paste this link into your browser:<br/><a href="${args.link}" style="color:#1e2844;word-break:break-all;">${args.link}</a></p>
+        </div>
+      </div>
+    </body></html>
+  `;
+}
+
+function resetEmailHtml(args: { portName: string; link: string; ttlMinutes: number }): string {
+  return `
+    <!DOCTYPE html>
+    <html><body style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#f5f5f5;padding:40px 0;margin:0;">
+      <div style="max-width:480px;margin:0 auto;background:#fff;border-radius:8px;overflow:hidden;box-shadow:0 2px 8px rgba(0,0,0,0.08);">
+        <div style="background:#1e2844;padding:32px 40px;text-align:center;">
+          <h1 style="color:#fff;margin:0;font-size:22px;font-weight:600;">${args.portName}</h1>
+          <p style="color:#9ca3af;margin:6px 0 0;font-size:14px;">Password reset</p>
+        </div>
+        <div style="padding:40px;">
+          <p style="color:#374151;font-size:16px;margin:0 0 16px;">Hello,</p>
+          <p style="color:#6b7280;font-size:15px;line-height:1.6;margin:0 0 32px;">
+            We received a request to reset your client portal password. Click the button below to choose a new one. The link expires in ${args.ttlMinutes} minutes. If you didn't request this, you can ignore this email.
+          </p>
+          <div style="text-align:center;margin:0 0 32px;">
+            <a href="${args.link}" style="display:inline-block;background:#1e2844;color:#fff;text-decoration:none;padding:14px 32px;border-radius:6px;font-size:15px;font-weight:500;">Reset password</a>
+          </div>
+          <p style="color:#9ca3af;font-size:13px;margin:0;line-height:1.5;">If the button doesn't work, paste this link into your browser:<br/><a href="${args.link}" style="color:#1e2844;word-break:break-all;">${args.link}</a></p>
+        </div>
+      </div>
+    </body></html>
+  `;
+}
--- a/src/lib/services/portal.service.ts
+++ b/src/lib/services/portal.service.ts
@@ -1,7 +1,7 @@
 import { and, eq, count, inArray, isNull, desc } from 'drizzle-orm';

 import { db } from '@/lib/db';
-import { clients, clientContacts } from '@/lib/db/schema/clients';
+import { clients } from '@/lib/db/schema/clients';
 import { interests } from '@/lib/db/schema/interests';
 import { documents, files } from '@/lib/db/schema/documents';
 import { invoices } from '@/lib/db/schema/financial';
@@ -10,95 +10,7 @@ import { ports } from '@/lib/db/schema/ports';
 import { yachts } from '@/lib/db/schema/yachts';
 import { companies, companyMemberships } from '@/lib/db/schema/companies';
 import { berthReservations } from '@/lib/db/schema/reservations';
-import { createPortalToken } from '@/lib/portal/auth';
-import { sendEmail } from '@/lib/email';
 import { getPresignedUrl } from '@/lib/minio';
-import { env } from '@/lib/env';
-import { logger } from '@/lib/logger';
-
-// ─── Magic Link ────────────────────────────────────────────────────────────────
-
-/**
- * Requests a magic link for portal access.
- * Always returns success — never reveals whether an email exists in the system.
- */
-export async function requestMagicLink(email: string): Promise<void> {
-  const normalizedEmail = email.toLowerCase().trim();
-
-  // Find client contact with matching email
-  const contact = await db.query.clientContacts.findFirst({
-    where: and(eq(clientContacts.channel, 'email'), eq(clientContacts.value, normalizedEmail)),
-    with: {
-      client: true,
-    },
-  });
-
-  if (!contact || !contact.client) {
-    // Don't reveal that the email doesn't exist — silently return
-    logger.debug({ email: normalizedEmail }, 'Portal magic link: no matching client contact');
-    return;
-  }
-
-  const client = contact.client;
-
-  // Build the JWT
-  const token = await createPortalToken({
-    clientId: client.id,
-    portId: client.portId,
-    email: normalizedEmail,
-  });
-
-  const magicLinkUrl = `${env.APP_URL}/verify?token=${encodeURIComponent(token)}`;
-
-  // Fetch port name for the email
-  const port = await db.query.ports.findFirst({
-    where: eq(ports.id, client.portId),
-  });
-
-  const portName = port?.name ?? 'Port Nimara';
-  const clientName = client.fullName;
-
-  const html = `
-    <!DOCTYPE html>
-    <html>
-    <head>
-      <meta charset="utf-8">
-      <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    </head>
-    <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #f5f5f5; padding: 40px 0; margin: 0;">
-      <div style="max-width: 480px; margin: 0 auto; background: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.08);">
-        <div style="background: #1e2844; padding: 32px 40px; text-align: center;">
-          <h1 style="color: #ffffff; margin: 0; font-size: 22px; font-weight: 600;">${portName}</h1>
-          <p style="color: #9ca3af; margin: 6px 0 0; font-size: 14px;">Client Portal</p>
-        </div>
-        <div style="padding: 40px;">
-          <p style="color: #374151; font-size: 16px; margin: 0 0 8px;">Hello, ${clientName}</p>
-          <p style="color: #6b7280; font-size: 15px; margin: 0 0 32px; line-height: 1.6;">
-            You requested access to your client portal. Click the button below to sign in. This link expires in 24 hours.
-          </p>
-          <div style="text-align: center; margin: 0 0 32px;">
-            <a href="${magicLinkUrl}" style="display: inline-block; background: #1e2844; color: #ffffff; text-decoration: none; padding: 14px 32px; border-radius: 6px; font-size: 15px; font-weight: 500;">
-              Access My Portal
-            </a>
-          </div>
-          <p style="color: #9ca3af; font-size: 13px; margin: 0; line-height: 1.6;">
-            If you didn't request this, you can safely ignore this email. If you're having trouble with the button above, copy and paste this URL into your browser:
-            <br><br>
-            <span style="color: #6b7280; word-break: break-all;">${magicLinkUrl}</span>
-          </p>
-        </div>
-        <div style="background: #f9fafb; padding: 20px 40px; text-align: center; border-top: 1px solid #e5e7eb;">
-          <p style="color: #9ca3af; font-size: 12px; margin: 0;">&copy; ${new Date().getFullYear()} ${portName}. All rights reserved.</p>
-        </div>
-      </div>
-    </body>
-    </html>
-  `;
-
-  await sendEmail(normalizedEmail, `Your ${portName} portal access link`, html);
-
-  logger.info({ clientId: client.id, portId: client.portId }, 'Portal magic link sent');
-}

 // ─── Dashboard ────────────────────────────────────────────────────────────────