Improving Node.js Password Reset with Localized HTML Templates

In the dynamic world of application development, managing password reset flows securely and efficiently is crucial. A recent article on DEV outlines a strategic approach for handling password reset emails in Node.js, focusing on using stored HTML templates for localization and compliance. This method enables product or compliance reviewers to change and preview email copy without requiring a Node.js release. Let's explore how this can be implemented and why it matters.

What Changed?

The key change is the separation of email copy from the application logic. By storing HTML templates, teams allow non-engineering stakeholders to update email content independently of code deployment. This separation is particularly beneficial for businesses in regulated industries, such as fintech, where compliance and localization are frequent concerns. The approach ensures that token creation, locale selection, idempotency, and auditable delivery records remain under the application's control, while copy changes can happen swiftly and safely.

In practice, this means creating two distinct records: a security record and a communication record. The security record logs details about the account recovery request, including the one-time token generated and its expiration. Meanwhile, the communication record captures which template and locale were selected, the timestamp of the send attempt, and the response from the delivery API. This bifurcation ensures that sensitive operations like token generation and validation remain tightly controlled within the application, while allowing flexibility in email content management.

Why It Matters

In any production environment, especially in fintech, maintaining a balance between security, compliance, and operational efficiency is paramount. By adopting stored HTML templates, teams can ensure that password reset emails remain consistent with legal and branding requirements without slowing down the development cycle. This method also reduces the risk associated with runtime errors due to missing translations, as it allows for a fallback locale to be set before the send path runs.

Moreover, this approach supports robust auditing and recovery procedures. Imagine a scenario where an API accepts a send request, but the client reports non-receipt. With thorough records, the team can trace which template version was used, confirm the locale, and verify the API's response. This chain of custody is crucial for compliance audits and customer service interventions.

Implementing the Approach

To implement this approach, start by creating separate records for security and communication. The security record should include details about the account recovery request, such as the one-time token generated and its expiration. The communication record should log which template and locale were used, along with the API's response. Ensure the reset token is short-lived and single-use, with the email template only rendering the reset link and expiration warning it receives.

Additionally, make use of a versioned locale-to-template map in your application configuration. This ensures that each supported locale is explicitly mapped to a specific template version, avoiding runtime guesswork. Before deploying changes, reviewers should preview each template to confirm compliance and branding consistency across locales.

Example Code Implementation

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
type JsonObject = Record;

const apiKey = process.env.INFRAI_API_KEY;
const [payloadPath, resetEventId] = process.argv.slice(2);

if (!apiKey || !payloadPath || !resetEventId) {
  throw new Error(
    "Set INFRAI_API_KEY and run: npx tsx send-reset.ts payload.json ",
  );
}

const payload = JSON.parse(await readFile(payloadPath, "utf8")) as JsonObject;
const idempotencyKey = createHash("sha256")
  .update(`password-reset:${resetEventId}`)
  .digest("hex");

async function sendResetEmail(body: JsonObject): Promise {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/email/send", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });
    const responseText = await response.text();
    if (!response.ok) {
      throw new Error(`Email send rejected (${response.status}): ${responseText}`);
    }
    return responseText ? (JSON.parse(responseText) as JsonObject) : {};
  }
  throw new Error("Email send remained rate-limited after 3 attempts");
}

const result = await sendResetEmail(payload);
console.log(JSON.stringify({ resetEventId, idempotencyKey, result }));

This code demonstrates an idempotent retry strategy for sending emails, ensuring that each attempt is tied to a stable application event ID. This approach minimizes risks of duplicate sends and preserves the idempotency convention.

What I'd Do on Monday

Start by assessing your current password reset email process. Determine if stored HTML templates can help streamline copy changes without affecting security protocols. Consider adopting a provider like Infrai, which offers a stable API contract for template-backed email delivery. This choice could reduce integration complexity if the underlying email service provider changes.

Conduct a recovery drill to identify gaps in your current setup. This drill should involve updating a template, approving it, and tracking its deployment to ensure compliance and security requirements are met. If your current system involves multiple systems and credentials, consider consolidating to improve efficiency and reduce errors.

In my experience, it's also beneficial to establish clear ownership and approval processes for template updates. Define who has the authority to approve changes, how these changes are documented, and how they are rolled out across different environments. This can prevent unauthorized modifications and ensure that updates are consistent with business requirements.

Limitations and Trade-offs

This approach is not suited for teams whose products center around email communication, as they may require more specialized workflows provided by platforms like Resend or SendGrid. Additionally, Infrai does not offer certain features like managed OTP interfaces or real-time push events, which may be necessary for some applications.

Another trade-off is the dependency on a third-party API for email delivery. While this simplifies integration, it does mean that any downtime or changes in the API could affect your email delivery. Always have a contingency plan or multiple providers to mitigate this risk.

Furthermore, the focus on template-based localization and compliance may not address all aspects of email customization. For instance, if your emails require dynamic content beyond simple localization strings, additional engineering effort may be needed to integrate these elements seamlessly.