feat(auth): implement staff-triggered password-reset links

apps/edr-freight-api/src/modules/auth/customer-reset.controller.ts

@@ -1,6 +1,7 @@
 import {
   Body,
   Controller,
+  Get,
   NotFoundException,
   Param,
   ParseUUIDPipe,
@@ -11,11 +12,14 @@ import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 import { BookingStaff } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { BackofficeResetPasswordDto } from "./dto/forgot-password.dto";
-import { CustomerResetService } from "./customer-reset.service";
+import {
+  CustomerResetService,
+  CustomerResetTarget,
+} from "./customer-reset.service";
 
 /**
- * Staff-triggered password reset. The customer receives the code and sets their
- * own password — staff never see or handle a credential.
+ * Staff-triggered password reset. The customer receives a single-use link and
+ * sets their own password — staff never see or handle a credential.
  */
 @ApiTags("backoffice")
 @Controller("backoffice/customers")
@@ -23,26 +27,45 @@ import { CustomerResetService } from "./customer-reset.service";
 export class CustomerResetController {
   constructor(private readonly customerResetService: CustomerResetService) {}
 
+  @Get(":companyId/reset-target")
+  @BookingStaff(FREIGHT_PERMS.customers.resetPassword)
+  @ApiOperation({
+    summary: "The primary contact's IAM account a reset link would be sent to",
+  })
+  async resetTarget(
+    @Param("companyId", ParseUUIDPipe) companyId: string,
+  ): Promise<CustomerResetTarget> {
+    const target = await this.customerResetService.getResetTarget(companyId);
+
+    if (!target) {
+      throw new NotFoundException(
+        "This customer has no active primary-contact account to reset",
+      );
+    }
+
+    return target;
+  }
+
   @Post(":companyId/reset-password")
   @BookingStaff(FREIGHT_PERMS.customers.resetPassword)
   @ApiOperation({
-    summary: "Send a password-reset code to a customer's primary contact",
+    summary: "Send a password-reset link to a customer's primary contact",
   })
   async resetPassword(
     @Param("companyId", ParseUUIDPipe) companyId: string,
     @Body() dto: BackofficeResetPasswordDto,
   ) {
-    const maskedTarget = await this.customerResetService.sendResetToCustomer(
+    const sent = await this.customerResetService.sendResetLinkToCustomer(
       companyId,
       dto.channel,
     );
 
-    if (!maskedTarget) {
+    if (!sent) {
       throw new NotFoundException(
         `No active primary contact with ${dto.channel === "email" ? "an email address" : "a phone number"} for this customer`,
       );
     }
 
-    return { channel: dto.channel, maskedTarget };
+    return sent;
   }
 }

apps/edr-freight-api/src/modules/auth/customer-reset.service.ts

@@ -1,10 +1,31 @@
 import { Injectable, Logger } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
 import { InjectRepository } from "@nestjs/typeorm";
 import { Repository } from "typeorm";
 
 import { ExternalProfile } from "../companies/entities/external-profile.entity";
+import { EmailClientService } from "../notifications/email-client.service";
+import { SmsClientService } from "../notifications/sms-client.service";
 import { ResetChannel } from "./dto/forgot-password.dto";
-import { ForgotPasswordService } from "./forgot-password.service";
+import {
+  ForgotPasswordService,
+  RESET_LINK_TTL_MS,
+} from "./forgot-password.service";
+import { maskOtpTarget } from "./mask-target.util";
+
+/** The account a staff-triggered reset would land on. */
+export interface CustomerResetTarget {
+  userId: string;
+  name: string;
+  email: string | null;
+  phone: string | null;
+}
+
+export interface SentResetLink {
+  channel: ResetChannel;
+  maskedTarget: string;
+  expiresAt: string;
+}
 
 @Injectable()
 export class CustomerResetService {
@@ -14,19 +35,110 @@ export class CustomerResetService {
     @InjectRepository(ExternalProfile)
     private readonly externalProfileRepository: Repository<ExternalProfile>,
     private readonly forgotPasswordService: ForgotPasswordService,
+    private readonly emailClient: EmailClientService,
+    private readonly smsClient: SmsClientService,
+    private readonly config: ConfigService,
   ) {}
 
   /**
-   * Send a reset code to the company's primary contact. Returns the masked
-   * destination, or null when there is no eligible account for that channel.
+   * The IAM account a reset would actually reach. The backoffice shows these
+   * values rather than `company.email` / `company.phone`: the company row holds
+   * business contact detail, while the link is delivered to the primary
+   * contact's own login credentials — the two drift apart routinely, and showing
+   * the wrong one has staff telling customers to check an inbox nothing was sent
+   * to.
+   */
+  async getResetTarget(companyId: string): Promise<CustomerResetTarget | null> {
+    const resolved = await this.resolvePrimaryContactUser(companyId);
+    if (!resolved) return null;
+
+    const { profile, user, userId } = resolved;
+    return {
+      userId,
+      name: `${profile.firstName} ${profile.lastName}`.trim(),
+      email: user.email ?? null,
+      phone: user.phoneNumber ?? null,
+    };
+  }
+
+  /**
+   * Mint a password-reset link and send it to the company's primary contact.
+   * Returns the masked destination, or null when there is no eligible account
+   * for that channel.
    *
    * Unlike the public flow this reports failure honestly — the caller is an
    * authenticated staff member, so there is nothing to enumerate.
    */
-  async sendResetToCustomer(
+  async sendResetLinkToCustomer(
     companyId: string,
     channel: ResetChannel,
-  ): Promise<string | null> {
+  ): Promise<SentResetLink | null> {
+    const resolved = await this.resolvePrimaryContactUser(companyId);
+    if (!resolved) return null;
+
+    const { user, userId } = resolved;
+    const target = this.forgotPasswordService.targetFor(user, channel);
+    if (!target) return null;
+
+    // Mint first, send second: a failed send leaves an unused ticket that simply
+    // expires, whereas sending a link before the ticket exists would hand the
+    // customer a URL that is dead on arrival.
+    const ticket = await this.forgotPasswordService.mintResetTicket(
+      userId,
+      RESET_LINK_TTL_MS,
+    );
+    const link = this.buildResetLink(ticket.userId, ticket.verificationCode);
+    const expiresAt = new Date(Date.now() + RESET_LINK_TTL_MS);
+
+    const { queued } = target.email
+      ? await this.emailClient.sendEmail({
+          to: target.email,
+          subject: "Reset your EDR Freight password",
+          text:
+            "A password reset was started for your EDR Freight account.\n\n" +
+            `Open this link to choose a new password:\n${link}\n\n` +
+            "The link expires in 24 hours and can only be used once. If you did " +
+            "not expect this, ignore this message — your password stays unchanged.",
+        })
+      : await this.smsClient.sendSms({
+          to: target.phone as string,
+          message: `Reset your EDR Freight password: ${link} (expires in 24 hours, single use)`,
+        });
+
+    this.logger.log(
+      `Staff-triggered ${channel} reset link sent to user ${userId} (company ${companyId}) queued=${queued}`,
+    );
+
+    if (!queued) {
+      // The ticket is committed and the backoffice is about to say "link sent",
+      // but nothing left this process — with RABBITMQ_ENABLED=false both clients
+      // are no-ops. Without this line the only symptom is a customer who never
+      // receives anything, indistinguishable from carrier loss.
+      this.logger.error(
+        `reset-link.dispatch.dropped channel=${channel} user=${userId} rabbitmqEnabled=${
+          process.env.RABBITMQ_ENABLED ?? "unset"
+        } — transport reported no hand-off; no link will arrive`,
+      );
+      // SECURITY: logs a live password-reset credential in cleartext. Same
+      // deliberate tradeoff the OTP service makes — this is the only way to
+      // complete a reset on an environment with no broker. Only reached when
+      // delivery already failed.
+      this.logger.warn(`Undelivered reset link for user ${userId}: ${link}`);
+    }
+
+    return {
+      channel,
+      maskedTarget: maskOtpTarget(target),
+      expiresAt: expiresAt.toISOString(),
+    };
+  }
+
+  /**
+   * The company's primary contact, gated on the same active-account rule the
+   * public flow uses — so a suspended customer cannot be reactivated by a
+   * staff-triggered reset (IAM's `set-password` flips `isActive` back on).
+   */
+  private async resolvePrimaryContactUser(companyId: string) {
     const profile = await this.externalProfileRepository.findOne({
       where: { companyId, isPrimaryContact: true },
     });
@@ -36,24 +148,28 @@ export class CustomerResetService {
       return null;
     }
 
-    // Resolve through the same active-account gate the public flow uses, so a
-    // suspended customer cannot be reactivated by a staff-triggered reset.
     const user = await this.forgotPasswordService.resolveActiveUserById(
       profile.userId,
     );
-    if (!user) {
+    if (!user?.id) {
       this.logger.warn(
         `Primary contact ${profile.userId} of company ${companyId} is not an active account`,
       );
       return null;
     }
 
-    const target = await this.forgotPasswordService.requestReset(user, channel);
-    if (!target) return null;
+    return { profile, user, userId: user.id };
+  }
 
-    this.logger.log(
-      `Staff-triggered ${channel} reset sent to user ${user.id} (company ${companyId})`,
-    );
-    return this.forgotPasswordService.maskTarget(target);
+  /**
+   * The portal route that trades the token for a set-password form. Params are
+   * URL-encoded because the token is base64url — safe as-is, but the encoding
+   * keeps this correct if the token format ever changes.
+   */
+  private buildResetLink(userId: string, token: string): string {
+    const base = this.config.get<string>("app.portalBaseUrl");
+    return `${base}/reset-password?uid=${encodeURIComponent(
+      userId,
+    )}&token=${encodeURIComponent(token)}`;
   }
 }

apps/edr-freight-api/src/modules/auth/dto/forgot-password.dto.ts

@@ -1,5 +1,5 @@
 import { ApiProperty } from "@nestjs/swagger";
-import { IsEnum, IsNotEmpty, IsString } from "class-validator";
+import { IsEnum, IsNotEmpty, IsString, IsUUID } from "class-validator";
 
 /** The channel the reset code is delivered over. */
 export enum ResetChannel {
@@ -33,3 +33,19 @@ export class BackofficeResetPasswordDto {
   @IsEnum(ResetChannel)
   channel!: ResetChannel;
 }
+
+/**
+ * The two halves of a reset link's query string. Together they stand in for the
+ * identifier + OTP pair of the typed flow: the token proves possession of the
+ * inbox/handset the link was delivered to.
+ */
+export class ResolveResetLinkDto {
+  @ApiProperty({ description: "IAM user id from the reset link's `uid` param" })
+  @IsUUID()
+  userId!: string;
+
+  @ApiProperty({ description: "Opaque token from the reset link's `token` param" })
+  @IsString()
+  @IsNotEmpty()
+  token!: string;
+}

apps/edr-freight-api/src/modules/auth/forgot-password.controller.ts

@@ -5,8 +5,13 @@ import { Public } from "@edr/api-common";
 import {
   ForgotPasswordRequestDto,
   ForgotPasswordVerifyDto,
+  ResolveResetLinkDto,
 } from "./dto/forgot-password.dto";
-import { ForgotPasswordService, ResetTicket } from "./forgot-password.service";
+import {
+  ForgotPasswordService,
+  ResetLinkAccount,
+  ResetTicket,
+} from "./forgot-password.service";
 
 /**
  * Freight-owned reset flow. IAM ships a `forgot-password` route, but it only
@@ -66,4 +71,16 @@ export class ForgotPasswordController {
       dto.otp,
     );
   }
+
+  @Post("forgot-password/resolve-link")
+  @ApiOperation({
+    summary: "Validate a staff-issued reset link and return its set-password ticket",
+    description:
+      "Takes the link's uid/token pair. The returned { userId, identifier, verificationCode } " +
+      "is the body for PATCH /api/auth/set-password, so the customer never types an identifier. " +
+      "A bad or expired link is rejected here rather than after the password is typed.",
+  })
+  resolveLink(@Body() dto: ResolveResetLinkDto): Promise<ResetLinkAccount> {
+    return this.forgotPasswordService.resolveResetLink(dto.userId, dto.token);
+  }
 }

apps/edr-freight-api/src/modules/auth/forgot-password.service.ts

@@ -4,7 +4,7 @@ import { BadRequestException, Injectable, Logger } from "@nestjs/common";
 import { InjectDataSource, InjectRepository } from "@nestjs/typeorm";
 import { DataSource, Repository } from "typeorm";
 
-import { hashPassword } from "@tria-plc/api-common/utils/argon";
+import { hashPassword, verifyPassword } from "@tria-plc/api-common/utils/argon";
 import { EOtpType } from "@tria-plc/iamapi-common/enums/otp.enum";
 import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 import { UserVerification } from "@tria-plc/iamapi-common/entities/iam/user/user-verification.entity";
@@ -22,11 +22,32 @@ const RESET_TICKET_TTL_MS = 10 * 60 * 1000;
 /** How long the emailed/SMS'd OTP stays valid before it must be re-requested. */
 const RESET_OTP_TTL_MS = 10 * 60 * 1000;
 
+/**
+ * A staff-triggered reset link lives longer than a typed OTP: the customer may
+ * only see the SMS/email hours after the call that prompted it.
+ */
+export const RESET_LINK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** IAM refuses a ticket once its row hits this many failed attempts. */
+const MAX_TICKET_ATTEMPTS = 5;
+
 export interface ResetTicket {
   userId: string;
   verificationCode: string;
 }
 
+/**
+ * What a valid reset link resolves to. `identifier` is the value IAM's
+ * `set-password` matches the user on (it accepts email / username / phone), so
+ * the portal can spend the ticket without the customer typing anything.
+ */
+export interface ResetLinkAccount {
+  userId: string;
+  identifier: string;
+  maskedIdentifier: string;
+  verificationCode: string;
+}
+
 @Injectable()
 export class ForgotPasswordService {
   private readonly logger = new Logger(ForgotPasswordService.name);
@@ -82,13 +103,23 @@ export class ForgotPasswordService {
   }
 
   /** The address the code goes to, taken from the account — never from input. */
-  private targetFor(user: User, channel: ResetChannel): OtpTarget | null {
+  targetFor(user: User, channel: ResetChannel): OtpTarget | null {
     if (channel === ResetChannel.Email) {
       return user.email ? { email: user.email } : null;
     }
     return user.phoneNumber ? { phone: user.phoneNumber } : null;
   }
 
+  /**
+   * The value IAM's `set-password` will match this account on. It looks the user
+   * up by email OR username OR phoneNumber (and lowercases whatever it is
+   * given), so prefer email, then phone, and fall back to username last —
+   * a mixed-case username would not survive that lowercasing.
+   */
+  private identifierFor(user: User): string | null {
+    return user.email ?? user.phoneNumber ?? user.username ?? null;
+  }
+
   /**
    * Send a reset code to the account's own email/phone. Returns the target so
    * authenticated (backoffice) callers can echo a masked version; unauthenticated
@@ -134,9 +165,18 @@ export class ForgotPasswordService {
 
     await this.otpService.verifyOtpForAction(target, otp, RESET_OTP_TTL_MS);
 
+    return await this.mintResetTicket(user.id, RESET_TICKET_TTL_MS);
+  }
+
+  /**
+   * Mint a single-use IAM reset ticket. Shared by the OTP flow (where the code
+   * is the proof of possession) and the staff-triggered link flow (where the
+   * ticket travels in the link and delivery to the account's own inbox/handset
+   * is the proof).
+   */
+  async mintResetTicket(userId: string, ttlMs: number): Promise<ResetTicket> {
     const code = randomBytes(24).toString("base64url");
     const verificationCode = await hashPassword(code);
-    const userId = user.id;
 
     await this.dataSource.transaction(async (manager) => {
       const repo = manager.getRepository(UserVerification);
@@ -147,7 +187,7 @@ export class ForgotPasswordService {
         userId,
         otpType: EOtpType.RESET_PASSWORD,
         verificationCode,
-        expiresAt: new Date(Date.now() + RESET_TICKET_TTL_MS),
+        expiresAt: new Date(Date.now() + ttlMs),
         isUsed: false,
         attemptCount: 0,
       });
@@ -157,6 +197,63 @@ export class ForgotPasswordService {
     return { userId, verificationCode: code };
   }
 
+  /**
+   * Validate a reset link and hand back everything the portal needs to spend it
+   * on IAM's `PATCH /api/auth/set-password`.
+   *
+   * The checks mirror IAM's own — newest row, unused, unexpired, attempts left,
+   * argon match — so a link that resolves here is one IAM will honour. Doing
+   * them up front is what lets the page say "this link has expired" before the
+   * customer types a password rather than after.
+   *
+   * Every rejection is the same message: a link is a bearer credential, and the
+   * holder of a bad one learns nothing about why it failed or whether the user
+   * id exists.
+   */
+  async resolveResetLink(
+    userId: string,
+    token: string,
+  ): Promise<ResetLinkAccount> {
+    const invalid = new BadRequestException(
+      "This password-reset link is invalid or has expired. Request a new one.",
+    );
+
+    const user = await this.resolveActiveUserById(userId);
+    const identifier = user && this.identifierFor(user);
+    if (!user || !identifier) throw invalid;
+
+    const verification = await this.dataSource
+      .getRepository(UserVerification)
+      .findOne({
+        where: { userId, otpType: EOtpType.RESET_PASSWORD },
+        order: { createdAt: "DESC" },
+      });
+
+    // `expiresAt` / `attemptCount` are optional on IAM's entity but always
+    // written by `mintResetTicket`. A row missing either is malformed, so treat
+    // it as expired rather than letting it through unchecked.
+    if (
+      !verification ||
+      verification.isUsed ||
+      !verification.expiresAt ||
+      verification.expiresAt < new Date() ||
+      (verification.attemptCount ?? 0) >= MAX_TICKET_ATTEMPTS ||
+      !(await verifyPassword(token, verification.verificationCode))
+    ) {
+      this.logger.warn(`Reset link rejected for user ${userId}`);
+      throw invalid;
+    }
+
+    return {
+      userId,
+      identifier,
+      maskedIdentifier: maskOtpTarget(
+        identifier.includes("@") ? { email: identifier } : { phone: identifier },
+      ),
+      verificationCode: token,
+    };
+  }
+
   /** `+251911234567` -> `+251•••••4567`; `ab@x.com` -> `a•@x.com`. */
   maskTarget(target: OtpTarget): string {
     return maskOtpTarget(target);

apps/edr-freight-api/src/modules/auth/freight-auth.module.ts

@@ -7,6 +7,7 @@ import { User } from '@tria-plc/iamapi-common/entities/iam/user/user.entity';
 import { UserVerification } from '@tria-plc/iamapi-common/entities/iam/user/user-verification.entity';
 
 import { ExternalProfile } from '../companies/entities/external-profile.entity';
+import { NotificationsModule } from '../notifications/notifications.module';
 import { OtpModule } from '../otp/otp.module';
 import { AccountController } from './account.controller';
 import { AccountService } from './account.service';
@@ -29,6 +30,8 @@ import { FreightMeService } from './freight-me.service';
       Employee,
     ]),
     OtpModule,
+    // Reset links go out over email/SMS directly, not through the OTP service.
+    NotificationsModule,
   ],
   controllers: [
     FreightMeController,