feat: add otp to contract

2026-08-26 18:42:49 +00:00 · 2026-07-03 12:19:07 +00:00
parent d3707fe704
commit 79731e58ec
8 changed files with 553 additions and 242 deletions
--- a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
@@ -19,6 +19,7 @@ import { CargoTypesService } from '../rule-engine/services/cargo-types.service';
 import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.service';
 import { FilesService } from '../files/files.service';
 import { SignaturesService } from '../signatures/signatures.service';
+import { OtpService } from '../otp/otp.service';
 import { ContractPricingService } from './contract-pricing.service';
 import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { ContractsRepository } from './contracts.repository';
@@ -63,6 +64,7 @@ export class ContractTransitionService {
    private readonly renderer: ContractRendererService,
    private readonly pdfService: ContractPdfService,
    private readonly minioService: MinioService,
+    private readonly otpService: OtpService,
  ) {}

  /** Customer submits the contract for approval → SUBMITTED; freeze unit rates. */
@@ -520,6 +522,12 @@ export class ContractTransitionService {
      if (existing) {
        throw new BadRequestException('Customer has already signed this contract');
      }
+      // Sudo-mode gate: a fresh, single-use OTP (SMS'd to the customer's phone)
+      // must be verified before the signature is applied.
+      if (!dto.otpPhone || !dto.otp) {
+        throw new BadRequestException('OTP verification is required to sign the contract');
+      }
+      await this.otpService.verifyOtpForAction(dto.otpPhone, dto.otp);
      await this.applySignature(contract, dto, options);
      await this.contractsRepository.update(contractId, {
        status: 'SIGNED_CUSTOMER',
--- a/apps/edr-freight-api/src/modules/contracts/contracts.module.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.module.ts
@@ -11,6 +11,7 @@ import { RuleEngineModule } from '../rule-engine/rule-engine.module';
 import { FileUploadSettingsModule } from '../file-upload-settings/file-upload-settings.module';
 import { DropdownSettingsModule } from '../dropdown-settings/dropdown-settings.module';
 import { SignaturesModule } from '../signatures/signatures.module';
+import { OtpModule } from '../otp/otp.module';
 import { BookingsModule } from '../bookings/bookings.module';

 import { ContractsController } from './contracts.controller';
@@ -72,6 +73,7 @@ import { ContractDocumentViewModelBuilder } from '../../contracts/contract-docum
    FilesModule,
    MinioModule,
    SignaturesModule,
+    OtpModule,
    CompaniesModule,
    // BookingsModule provides BookingsRepository/BookingPricingService used by the
    // contract PDF builders (they read a Booking today — see docs/new-doc.md §3.3).
--- a/apps/edr-freight-api/src/modules/contracts/dto/sign-contract.dto.ts
+++ b/apps/edr-freight-api/src/modules/contracts/dto/sign-contract.dto.ts
@@ -1,5 +1,5 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsIn, IsOptional, IsString, MinLength } from 'class-validator';
+import { IsIn, IsOptional, IsString, Matches, MinLength } from 'class-validator';

 export class SignContractDto {
  @ApiProperty({ enum: ['CUSTOMER', 'STAFF', 'DIRECTOR', 'CEO'] })
@@ -26,4 +26,19 @@ export class SignContractDto {
  @IsOptional()
  @IsString()
  consentText?: string;
+
+  // Sudo-mode OTP challenge. Required when role=CUSTOMER: a fresh 6-digit code
+  // SMS'd to the signer's phone, verified server-side before the signature is
+  // applied. `otpPhone` is the number the code was sent to (the signed-in
+  // customer's registered phone).
+  @ApiPropertyOptional({ description: '6-digit OTP; required when role=CUSTOMER' })
+  @IsOptional()
+  @IsString()
+  @Matches(/^\d{6}$/, { message: 'otp must be 6 digits' })
+  otp?: string;
+
+  @ApiPropertyOptional({ description: 'Phone the OTP was sent to; required when role=CUSTOMER' })
+  @IsOptional()
+  @IsString()
+  otpPhone?: string;
 }
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -11,12 +11,7 @@ import {
 } from "@mantine/core";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { useQuery } from "@tanstack/react-query";
-import {
-  AlertCircle,
-  ArrowLeft,
-  ArrowRight,
-  UserCheck,
-} from "lucide-react";
+import { AlertCircle, ArrowLeft, ArrowRight, UserCheck } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { useForm } from "react-hook-form";

@@ -288,6 +283,7 @@ export default function CompanyProfileForm({
  const useOwnerAsManager = () => {
    if (!etradeOwner) return;
    setValue("generalManagerName", etradeOwner.name);
+    setValue("generalManagerEmail", user.email);
    setValue("generalManagerPhone", etradeOwner.phone ?? "", {
      shouldValidate: true,
    });
@@ -367,7 +363,6 @@ export default function CompanyProfileForm({
    "contact",
    "poa",
    "documents",
-    "additional",
  ];
  const currentIdx = stepOrder.indexOf(step);

@@ -398,16 +393,6 @@ export default function CompanyProfileForm({

  const nextStep = async () => {
    userNavigatedRef.current = true;
-    if (step === "additional") {
-      if (!licenseComplete) {
-        setSaveError(
-          "Please upload a business license for each of your operational profiles.",
-        );
-        return;
-      }
-      handleSubmit((data) => onSubmit(buildPayload(data, user)))();
-      return;
-    }
    // The documents step auto-uploads whatever the user selected as they
    // continue (partial uploads are allowed — required-doc completeness is
    // re-checked on resume). A failed upload holds them on the step.
@@ -424,8 +409,15 @@ export default function CompanyProfileForm({
          setSaving(false);
        }
      }
+
+      if (!licenseComplete) {
+        setSaveError(
+          "Please upload a business license for each of your operational profiles.",
+        );
+        return;
+      }
      setSaveError(null);
-      setStep(stepOrder[currentIdx + 1]);
+      handleSubmit((data) => onSubmit(buildPayload(data, user)))();
      return;
    }
    // Field steps validate + save before advancing.
@@ -450,10 +442,7 @@ export default function CompanyProfileForm({
      <form onSubmit={(e) => e.preventDefault()}>
        <Stack gap="md">
          {step === "company" && (
-            <>
-              <Text fw={600} size="sm" c="edr-text">
-                Enter your TIN to auto-fill company information from eTrade
-              </Text>
+            <Stack gap="sm">
              <ETradeInfo
                tin={watch("tinNumber")}
                register={register("tinNumber")}
@@ -592,7 +581,7 @@ export default function CompanyProfileForm({
                  {...register("houseNo")}
                />
              </SimpleGrid>
-            </>
+            </Stack>
          )}

          {step === "personnel" && (
@@ -752,15 +741,13 @@ export default function CompanyProfileForm({
                  onChange={setDocumentFiles}
                />
              )}
-            </>
-          )}

-          {step === "additional" && (
-            <RoleLicenseStep
-              profiles={roleProfiles ?? []}
-              value={licenseFiles ?? {}}
-              onChange={onLicenseChange ?? (() => { })}
-            />
+              <RoleLicenseStep
+                profiles={roleProfiles ?? []}
+                value={licenseFiles ?? {}}
+                onChange={onLicenseChange ?? (() => { })}
+              />
+            </>
          )}

          {saveError && (
@@ -768,11 +755,7 @@ export default function CompanyProfileForm({
              color="red"
              variant="light"
              icon={<AlertCircle size={18} />}
-              title={
-                step === "additional"
-                  ? "Business license required"
-                  : "Couldn't save this step"
-              }
+              title={"Couldn't save this step"}
            >
              {saveError}
            </Alert>
@@ -796,7 +779,7 @@ export default function CompanyProfileForm({
                onClick={prevStep}
                leftSection={<ArrowLeft size={16} />}
              >
-                {step === "additional" ? "Back to Documents" : "Back"}
+                Back
              </Button>
            ) : (
              <span />
@@ -811,12 +794,10 @@ export default function CompanyProfileForm({
              }
              loading={isPending || saving}
              rightSection={
-                !isPending && !saving && step !== "additional" ? (
-                  <ArrowRight size={16} />
-                ) : undefined
+                !isPending && !saving ? <ArrowRight size={16} /> : undefined
              }
            >
-              {step === "additional" ? "Submit for review" : "Continue"}
+              {step === "documents" ? "Submit for review" : "Continue"}
            </Button>
          </Group>
        </Stack>
--- a/apps/edr-freight-web/portal/src/pages/accounts/SignupPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/SignupPage.tsx
@@ -1,18 +1,38 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { zodResolver } from "@hookform/resolvers/zod";
-import { ArrowRight, Check, Eye, EyeOff, X } from "lucide-react";
-import { Controller, useForm } from "react-hook-form";
+import {
+  Alert,
+  Button,
+  PasswordInput,
+  PinInput,
+  SegmentedControl,
+  SimpleGrid,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import {
+  AlertCircle,
+  ArrowLeft,
+  ArrowRight,
+  Check,
+  Mail,
+  RotateCw,
+  ShieldCheck,
+  Smartphone,
+  X,
+} from "lucide-react";
+import { useForm } from "react-hook-form";
 import { useNavigate } from "react-router-dom";
 import { z } from "zod";
-import RPNInput from "react-phone-number-input";
-import "react-phone-number-input/style.css";

 import { userType } from "@/enums/userType";
 import useAuth from "@/hooks/useAuth";
 import type { SignupPayload } from "@/types/auth";
-import AuthShell, { fieldClass, primaryButtonClass } from "@/components/auth/AuthShell";
-import { isValidPhone } from "@/components/PhoneField";
-import "@/components/phone-field.css";
+import AuthShell from "@/components/auth/AuthShell";
+import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
+import { api } from "@/services/api";
+import { extractApiError } from "@/utils/result";

 const EDR_LOGO = "/assets/edr-logo.png";

@@ -50,16 +70,46 @@ const userSchema = z

 type FormData = z.infer<typeof userSchema>;

-const errorText = (msg?: string) =>
-  msg ? <p className="mt-1 text-xs text-red-600">{msg}</p> : null;
+/** Mask all but the first 7 chars of an E.164 phone for display. */
+const maskPhone = (p: string) =>
+  p.length > 4 ? `${p.slice(0, 7)}${"*".repeat(Math.max(0, p.length - 7))}` : p;
+
+/** Mask the local part of an email for display (j***e@example.com). */
+const maskEmail = (email: string) => {
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return email;
+  if (local.length <= 2) return `${local[0] ?? ""}***@${domain}`;
+  return `${local[0]}***${local[local.length - 1]}@${domain}`;
+};
+
+type OtpChannel = "phone" | "email";

 export default function SignupPage() {
  const navigate = useNavigate();
  const { signup } = useAuth();
  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [showPassword, setShowPassword] = useState(false);
-  const [showConfirm, setShowConfirm] = useState(false);
+
+  // Two-stage signup: fill the form, then a mandatory SMS OTP challenge on the
+  // phone number before the account is actually created. The account is only
+  // created after the code is verified — the OTP is a hard requirement.
+  const [stage, setStage] = useState<"form" | "otp">("form");
+  const [pendingData, setPendingData] = useState<FormData | null>(null);
+  // Which contact method the code was sent to — chosen on the form, locked in
+  // once the challenge is sent.
+  const [channel, setChannel] = useState<OtpChannel>("phone");
+  const [otpChannel, setOtpChannel] = useState<OtpChannel>("phone");
+  const [sending, setSending] = useState(false);
+  const [verifying, setVerifying] = useState(false);
+  const [otpCode, setOtpCode] = useState("");
+  const [otpError, setOtpError] = useState<string | null>(null);
+  const [resendIn, setResendIn] = useState(0);
+
+  // Resend cooldown countdown (pure setTimeout ticks — no Date.now needed).
+  useEffect(() => {
+    if (resendIn <= 0) return;
+    const t = setTimeout(() => setResendIn((s) => s - 1), 1000);
+    return () => clearTimeout(t);
+  }, [resendIn]);

  const {
    register,
@@ -80,226 +130,329 @@ export default function SignupPage() {
    },
  });

-  const onSubmit = async (data: FormData) => {
+  const passwordValue = watch("password") ?? "";
+
+  // Step 1 — form is valid: send a fresh code to the chosen channel, then
+  // move to the OTP challenge.
+  const requestOtp = async (data: FormData) => {
    setError(null);
-    setLoading(true);
+    setSending(true);
    try {
+      await api.auth.sendOTP.call(
+        channel === "email" ? { email: data.email } : { phone: data.phone },
+      );
+      setPendingData(data);
+      setOtpChannel(channel);
+      setOtpCode("");
+      setOtpError(null);
+      setResendIn(60);
+      setStage("otp");
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const resendOtp = async () => {
+    if (!pendingData) return;
+    setOtpError(null);
+    setSending(true);
+    try {
+      await api.auth.sendOTP.call(
+        otpChannel === "email"
+          ? { email: pendingData.email }
+          : { phone: pendingData.phone },
+      );
+      setOtpCode("");
+      setResendIn(60);
+    } catch (err) {
+      setOtpError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  // Step 2 — verify the code, then (only on success) create the account.
+  const confirmOtp = async () => {
+    if (!pendingData) return;
+    setOtpError(null);
+    if (otpCode.trim().length !== 6) {
+      setOtpError("Enter the 6-digit code we sent you.");
+      return;
+    }
+    setVerifying(true);
+    try {
+      await api.auth.verifyOTP.call({
+        ...(otpChannel === "email"
+          ? { email: pendingData.email }
+          : { phone: pendingData.phone }),
+        otp: otpCode.trim(),
+      });
      const payload: SignupPayload = {
-        email: data.email,
-        username: data.email,
+        email: pendingData.email,
+        username: pendingData.email,
        // Already a canonical E.164 string from the phone field (e.g. +251912345678).
-        phoneNumber: data.phone,
-        userType: data.userType,
+        phoneNumber: pendingData.phone,
+        userType: pendingData.userType,
        name: {
-          en: `${data.firstName.en} ${data.lastName.en}`,
-          am: `${data.firstName.en} ${data.lastName.en}`,
+          en: `${pendingData.firstName.en} ${pendingData.lastName.en}`,
+          am: `${pendingData.firstName.en} ${pendingData.lastName.en}`,
        },
-        password: data.password,
-        confirmPassword: data.confirmPassword,
+        password: pendingData.password,
+        confirmPassword: pendingData.confirmPassword,
      };
      const result = await signup(payload);
      if (result.success) {
        navigate("/portal");
      } else {
-        setError(result.error.message);
+        setOtpError(result.error.message);
      }
-    } catch {
-      setError("An unexpected error occurred");
+    } catch (err) {
+      setOtpError(extractApiError(err).message);
    } finally {
-      setLoading(false);
+      setVerifying(false);
    }
  };

-  const passwordValue = watch("password") ?? "";
-
  return (
    <AuthShell
      tagline="Smart Freight Operations"
      taglineBody="Join EDR Freight to manage shipments, track consignments, and streamline logistics workflows across Ethiopia and Djibouti."
    >
-      <form className="flex w-full flex-col" onSubmit={handleSubmit(onSubmit)}>
+      <div className="flex w-full flex-col">
        <div className="mb-4 flex justify-center sm:mb-6">
          <img src={EDR_LOGO} alt="EDR Freight" className="h-9 w-auto sm:h-11" />
        </div>

-        <div className="mb-4 space-y-1.5 text-center sm:mb-5">
-          <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
-            Create account
-          </h1>
-          <p className="text-sm leading-relaxed text-gray-500">
-            Register to access EDR Freight services.
-          </p>
-        </div>
-
-        <div className="flex w-full flex-col gap-4">
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
-            <div className="space-y-1.5">
-              <label className="text-sm font-medium text-gray-800">
-                First name <span className="text-red-500">*</span>
-              </label>
-              <input
-                placeholder="John"
-                disabled={loading}
-                className={fieldClass}
-                {...register("firstName.en")}
-              />
-              {errorText(errors.firstName?.en?.message)}
+        {stage === "form" ? (
+          <form onSubmit={handleSubmit(requestOtp)} className="flex w-full flex-col">
+            <div className="mb-4 space-y-1.5 text-center sm:mb-5">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Create account
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                Register to access EDR Freight services.
+              </p>
            </div>
-            <div className="space-y-1.5">
-              <label className="text-sm font-medium text-gray-800">
-                Last name <span className="text-red-500">*</span>
-              </label>
-              <input
-                placeholder="Doe"
-                disabled={loading}
-                className={fieldClass}
-                {...register("lastName.en")}
+
+            <Stack gap="md">
+              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+                <TextInput
+                  label="First name"
+                  placeholder="John"
+                  required
+                  disabled={sending}
+                  error={errors.firstName?.en?.message}
+                  {...register("firstName.en")}
+                />
+                <TextInput
+                  label="Last name"
+                  placeholder="Doe"
+                  required
+                  disabled={sending}
+                  error={errors.lastName?.en?.message}
+                  {...register("lastName.en")}
+                />
+              </SimpleGrid>
+
+              <TextInput
+                label="Email"
+                type="email"
+                placeholder="john@example.com"
+                required
+                disabled={sending}
+                error={errors.email?.message}
+                {...register("email")}
              />
-              {errorText(errors.lastName?.en?.message)}
-            </div>
-          </div>

-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Email <span className="text-red-500">*</span>
-            </label>
-            <input
-              type="email"
-              placeholder="john@example.com"
-              disabled={loading}
-              className={fieldClass}
-              {...register("email")}
-            />
-            {errorText(errors.email?.message)}
-          </div>
-
-          <div className="space-y-1.5">
-            <label htmlFor="signup-phone" className="text-sm font-medium text-gray-800">
-              Phone <span className="text-red-500">*</span>
-            </label>
-            <Controller
-              control={control}
-              name="phone"
-              render={({ field }) => (
-                <div
-                  className={`edr-phone-wrapper${
-                    errors.phone ? " edr-phone-wrapper--error" : ""
-                  }`}
-                >
-                  <RPNInput
-                    international
-                    defaultCountry="ET"
-                    countryCallingCodeEditable={false}
-                    addInternationalOption
-                    id="signup-phone"
-                    placeholder="912 345 678"
-                    disabled={loading}
-                    value={field.value || undefined}
-                    onChange={(v) => field.onChange(v ?? "")}
-                    onBlur={field.onBlur}
-                  />
-                </div>
-              )}
-            />
-            {errorText(errors.phone?.message)}
-          </div>
-
-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Password <span className="text-red-500">*</span>
-            </label>
-            <div className="relative">
-              <input
-                type={showPassword ? "text" : "password"}
-                placeholder="Create a strong password"
-                disabled={loading}
-                className={`${fieldClass} pr-11`}
-                {...register("password")}
+              <ControlledPhoneField
+                control={control}
+                name="phone"
+                label="Phone"
+                required
+                disabled={sending}
              />
-              <button
-                type="button"
-                onClick={() => setShowPassword((current) => !current)}
-                className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 transition-colors hover:text-gray-600"
-                aria-label={showPassword ? "Hide password" : "Show password"}
-              >
-                {showPassword ? <EyeOff className="h-5 w-5" /> : <Eye className="h-5 w-5" />}
-              </button>
-            </div>
-            {errorText(errors.password?.message)}
-            {passwordValue.length > 0 ? (
-              <div className="mt-2 space-y-1">
-                {passwordRequirements.map((req) => {
-                  const met = req.test(passwordValue);
-                  return (
-                    <div key={req.label} className="flex items-center gap-2">
-                      <span
-                        className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full ${
-                          met ? "bg-primary text-primary-foreground" : "bg-gray-200 text-gray-500"
-                        }`}
-                      >
-                        {met ? <Check className="h-2.5 w-2.5" /> : <X className="h-2.5 w-2.5" />}
-                      </span>
-                      <span className={`text-xs ${met ? "text-primary" : "text-gray-500"}`}>
-                        {req.label}
-                      </span>
-                    </div>
-                  );
-                })}
+
+              <div className="space-y-1.5">
+                <Text size="sm" fw={500} c="edr-text">
+                  Send verification code via
+                </Text>
+                <SegmentedControl
+                  fullWidth
+                  disabled={sending}
+                  value={channel}
+                  onChange={(v) => setChannel(v as OtpChannel)}
+                  data={[
+                    {
+                      value: "phone",
+                      label: (
+                        <span className="flex items-center justify-center gap-1.5">
+                          <Smartphone size={14} /> Phone
+                        </span>
+                      ),
+                    },
+                    {
+                      value: "email",
+                      label: (
+                        <span className="flex items-center justify-center gap-1.5">
+                          <Mail size={14} /> Email
+                        </span>
+                      ),
+                    },
+                  ]}
+                />
              </div>
-            ) : null}
-          </div>

-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Confirm password <span className="text-red-500">*</span>
-            </label>
-            <div className="relative">
-              <input
-                type={showConfirm ? "text" : "password"}
+              <div>
+                <PasswordInput
+                  label="Password"
+                  placeholder="Create a strong password"
+                  required
+                  disabled={sending}
+                  error={errors.password?.message}
+                  {...register("password")}
+                />
+                {passwordValue.length > 0 ? (
+                  <div className="mt-2 space-y-1">
+                    {passwordRequirements.map((req) => {
+                      const met = req.test(passwordValue);
+                      return (
+                        <div key={req.label} className="flex items-center gap-2">
+                          <span
+                            className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full ${
+                              met ? "bg-primary text-primary-foreground" : "bg-gray-200 text-gray-500"
+                            }`}
+                          >
+                            {met ? <Check className="h-2.5 w-2.5" /> : <X className="h-2.5 w-2.5" />}
+                          </span>
+                          <span className={`text-xs ${met ? "text-primary" : "text-gray-500"}`}>
+                            {req.label}
+                          </span>
+                        </div>
+                      );
+                    })}
+                  </div>
+                ) : null}
+              </div>
+
+              <PasswordInput
+                label="Confirm password"
                placeholder="Re-enter your password"
-                disabled={loading}
-                className={`${fieldClass} pr-11`}
+                required
+                disabled={sending}
+                error={errors.confirmPassword?.message}
                {...register("confirmPassword")}
              />
-              <button
-                type="button"
-                onClick={() => setShowConfirm((current) => !current)}
-                className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 transition-colors hover:text-gray-600"
-                aria-label={showConfirm ? "Hide password" : "Show password"}
+
+              {error ? (
+                <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                  {error}
+                </Alert>
+              ) : null}
+
+              <Button
+                type="submit"
+                color="edr-green"
+                fullWidth
+                loading={sending}
+                rightSection={!sending ? <ArrowRight size={16} /> : undefined}
              >
-                {showConfirm ? <EyeOff className="h-5 w-5" /> : <Eye className="h-5 w-5" />}
-              </button>
+                Continue
+              </Button>
+
+              <p className="text-center text-sm text-gray-500">
+                Already have an account?{" "}
+                <button
+                  type="button"
+                  onClick={() => navigate("/login")}
+                  className="font-semibold text-primary hover:underline"
+                >
+                  Sign In
+                </button>
+              </p>
+            </Stack>
+          </form>
+        ) : (
+          <Stack gap="md">
+            <div className="mb-1 flex justify-center">
+              <span className="flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+                <ShieldCheck size={22} />
+              </span>
            </div>
-            {errorText(errors.confirmPassword?.message)}
-          </div>
-
-          {error ? (
-            <div className="rounded-lg border border-red-200 bg-red-50 px-3 py-2.5 text-sm text-red-700">
-              {error}
+            <div className="space-y-1.5 text-center">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Verify your {otpChannel === "email" ? "email" : "phone"}
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                We sent a 6-digit code to{" "}
+                <span className="font-medium text-gray-700">
+                  {otpChannel === "email"
+                    ? maskEmail(pendingData?.email ?? "")
+                    : maskPhone(pendingData?.phone ?? "")}
+                </span>
+                . Enter it to finish creating your account.
+              </p>
            </div>
-          ) : null}

-          <button
-            type="submit"
-            disabled={loading}
-            className={`${primaryButtonClass} flex items-center justify-center gap-2`}
-          >
-            {loading ? "Creating account..." : "Create Account"}
-            {!loading ? <ArrowRight className="h-4 w-4" /> : null}
-          </button>
+            {otpError ? (
+              <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                {otpError}
+              </Alert>
+            ) : null}

-          <p className="text-center text-sm text-gray-500">
-            Already have an account?{" "}
-            <button
-              type="button"
-              onClick={() => navigate("/login")}
-              className="font-semibold text-primary hover:underline"
+            <Stack gap={6} align="center">
+              <Text size="sm" fw={500} c="edr-text">
+                Verification code
+              </Text>
+              <PinInput
+                length={6}
+                type="number"
+                oneTimeCode
+                value={otpCode}
+                placeholder="0"
+                disabled={verifying}
+                styles={{ input: { textAlign: "center" } }}
+                onChange={setOtpCode}
+              />
+            </Stack>
+
+            <Button
+              color="edr-green"
+              fullWidth
+              loading={verifying}
+              disabled={verifying || otpCode.trim().length !== 6}
+              onClick={confirmOtp}
            >
-              Sign In
-            </button>
-          </p>
-        </div>
-      </form>
+              Verify &amp; create account
+            </Button>
+
+            <div className="flex items-center justify-between">
+              <Button
+                variant="subtle"
+                color="gray"
+                leftSection={<ArrowLeft size={14} />}
+                disabled={sending || verifying}
+                onClick={() => {
+                  setStage("form");
+                  setOtpError(null);
+                }}
+              >
+                Back
+              </Button>
+              <Button
+                variant="subtle"
+                color="edr-green"
+                leftSection={<RotateCw size={14} />}
+                disabled={resendIn > 0 || sending || verifying}
+                onClick={resendOtp}
+              >
+                {resendIn > 0 ? `Resend in ${resendIn}s` : "Resend code"}
+              </Button>
+            </div>
+          </Stack>
+        )}
+      </div>
    </AuthShell>
  );
 }
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
@@ -11,17 +11,27 @@ import {
  Loader,
  Modal,
  Paper,
+  PinInput,
  Stack,
  Text,
  TextInput,
 } from "@mantine/core";
-import { ArrowLeft, Download, FileSignature, Printer } from "lucide-react";
+import {
+  ArrowLeft,
+  Download,
+  FileSignature,
+  Printer,
+  RotateCw,
+  ShieldCheck,
+} from "lucide-react";
 import toast from "react-hot-toast";

 import { ContractSignSuccessModal } from "@/components/contracts/ContractSignSuccessModal";
 import { ContractSignaturePad } from "@/components/bookings/ContractSignaturePad";
 import { contractsService } from "@/services/contracts.service";
 import { api } from "@/services/api";
+import useAuth from "@/hooks/useAuth";
+import { extractApiError } from "@/utils/result";

 const CONSENT_TEXT =
  "I have read the entire contract and agree to its terms.";
@@ -34,9 +44,13 @@ export default function ContractViewPage() {
  const { id } = useParams<{ id: string }>();
  const navigate = useNavigate();
  const qc = useQueryClient();
+  const { user } = useAuth();
  const iframeRef = useRef<HTMLIFrameElement>(null);

  const [signOpen, setSignOpen] = useState(false);
+  const [otpOpen, setOtpOpen] = useState(false);
+  const [otpCode, setOtpCode] = useState("");
+  const [otpError, setOtpError] = useState<string | null>(null);
  const [successOpen, setSuccessOpen] = useState(false);
  const [signerName, setSignerName] = useState("");
  const [signatureData, setSignatureData] = useState<string | null>(null);
@@ -44,6 +58,15 @@ export default function ContractViewPage() {
  const [hasScrolledToBottom, setHasScrolledToBottom] = useState(false);
  const [agreedToTerms, setAgreedToTerms] = useState(false);

+  // The signed-in customer's registered phone — where the sudo-mode OTP is sent.
+  const customerPhone = user?.phoneNumber ?? "";
+  const maskedPhone =
+    customerPhone.length > 4
+      ? `${customerPhone.slice(0, 4)}${"*".repeat(
+          Math.max(customerPhone.length - 6, 0),
+        )}${customerPhone.slice(-2)}`
+      : customerPhone;
+
  const { data, isLoading, isError, refetch } = useQuery({
    queryKey: ["contract-view", id],
    queryFn: () => contractsService.getContractView(id!),
@@ -95,6 +118,18 @@ export default function ContractViewPage() {
    };
  }, [checkScrollBottom]);

+  // Send (or resend) the fresh OTP challenge to the customer's phone. On success
+  // we swap the signature modal for the OTP entry modal.
+  const sendOtpMutation = useMutation({
+    mutationFn: () => api.auth.sendOTP.call({ phone: customerPhone }),
+    onSuccess: () => {
+      setSignOpen(false);
+      setOtpError(null);
+      setOtpOpen(true);
+    },
+    onError: () => toast.error("Failed to send verification code"),
+  });
+
  const signMutation = useMutation({
    mutationFn: () =>
      contractsService.signContract(id!, {
@@ -104,16 +139,22 @@ export default function ContractViewPage() {
          : (signatureData as string),
        signerDisplayName: signerName.trim(),
        consentText: CONSENT_TEXT,
+        otp: otpCode.trim(),
+        otpPhone: customerPhone,
      }),
    onSuccess: () => {
-      setSignOpen(false);
+      setOtpOpen(false);
+      setOtpCode("");
      setSuccessOpen(true);
      void refetch();
      void qc.invalidateQueries({
        queryKey: api.contracts.get.queryKey({ id: id! }),
      });
    },
-    onError: () => toast.error("Failed to sign contract"),
+    onError: (err) =>
+      setOtpError(
+        extractApiError(err).message ?? "Failed to verify code and sign",
+      ),
  });

  const openSign = () => {
@@ -128,6 +169,17 @@ export default function ContractViewPage() {
    if (!signerName.trim()) return;
    const image = usingSaved ? savedSignatureImage : signatureData;
    if (!image) return;
+    if (!customerPhone) {
+      toast.error("No phone number on file to verify your signature.");
+      return;
+    }
+    setOtpCode("");
+    sendOtpMutation.mutate();
+  };
+
+  const confirmOtp = () => {
+    if (otpCode.trim().length !== 6) return;
+    setOtpError(null);
    signMutation.mutate();
  };

@@ -315,20 +367,114 @@ export default function ContractViewPage() {
            </Button>
            <Button
              color="edr-green"
-              loading={signMutation.isPending}
+              loading={sendOtpMutation.isPending}
              disabled={
-                signMutation.isPending ||
+                sendOtpMutation.isPending ||
                !signerName.trim() ||
                (!usingSaved && !signatureData)
              }
              onClick={confirmSign}
            >
-              {usingSaved ? "Approve & sign" : "Confirm signature"}
+              Continue to verification
            </Button>
          </Group>
        </Stack>
      </Modal>

+      <Modal
+        opened={otpOpen}
+        onClose={() => setOtpOpen(false)}
+        title="Verify it's you"
+        centered
+        radius="lg"
+      >
+        <Stack gap="md">
+          <Group gap="sm" wrap="nowrap">
+            <Box
+              w={40}
+              h={40}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                borderRadius: 12,
+                background: "var(--mantine-color-edr-green-0)",
+                flexShrink: 0,
+              }}
+            >
+              <ShieldCheck
+                size={20}
+                color="var(--mantine-color-edr-green-6)"
+              />
+            </Box>
+            <Text size="sm" c="dimmed">
+              For security, enter the 6-digit code we sent by SMS to{" "}
+              <Text span fw={600} c="edr-text">
+                {maskedPhone}
+              </Text>{" "}
+              to confirm and apply your signature.
+            </Text>
+          </Group>
+
+          {otpError && (
+            <Alert color="red" variant="light" radius="md">
+              {otpError}
+            </Alert>
+          )}
+
+          <Stack gap={6}>
+            <Text size="sm" fw={500} c="edr-text">
+              Verification code
+            </Text>
+            <PinInput
+              length={6}
+              type="number"
+              oneTimeCode
+              value={otpCode}
+              placeholder="0"
+              disabled={signMutation.isPending}
+              styles={{ input: { textAlign: "center" } }}
+              onChange={setOtpCode}
+            />
+          </Stack>
+
+          <Group justify="space-between" gap="sm">
+            <Button
+              variant="subtle"
+              color="gray"
+              size="compact-sm"
+              leftSection={<RotateCw size={14} />}
+              loading={sendOtpMutation.isPending}
+              disabled={sendOtpMutation.isPending || signMutation.isPending}
+              onClick={() => {
+                setOtpError(null);
+                sendOtpMutation.mutate();
+              }}
+            >
+              Resend code
+            </Button>
+            <Group gap="sm">
+              <Button
+                variant="default"
+                onClick={() => setOtpOpen(false)}
+                disabled={signMutation.isPending}
+              >
+                Cancel
+              </Button>
+              <Button
+                color="edr-green"
+                leftSection={<FileSignature size={16} />}
+                loading={signMutation.isPending}
+                disabled={signMutation.isPending || otpCode.trim().length !== 6}
+                onClick={confirmOtp}
+              >
+                Verify &amp; sign
+              </Button>
+            </Group>
+          </Group>
+        </Stack>
+      </Modal>
+
      <ContractSignSuccessModal
        opened={successOpen}
        reference={data.reference}
--- a/apps/edr-freight-web/portal/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/bookings.service.ts
@@ -89,6 +89,10 @@ export interface SignContractPayload {
  signatureImageBase64: string;
  signerDisplayName: string;
  consentText?: string;
+  /** Sudo-mode OTP challenge; required when role=CUSTOMER. */
+  otp?: string;
+  /** Phone the OTP was sent to; required when role=CUSTOMER. */
+  otpPhone?: string;
 }

 export interface ApproveDeliveryResponse {
--- a/apps/edr-freight-web/portal/src/types/auth.ts
+++ b/apps/edr-freight-web/portal/src/types/auth.ts
@@ -33,7 +33,9 @@ export interface SignupResponse {
 }

 export interface OtpPayload {
-  phone: string;
+  /** Exactly one of phone/email — the channel the code is sent through. */
+  phone?: string;
+  email?: string;
  /** Required on verify; omitted on send (the server generates the code). */
  otp?: string;
 }