Magic links: how passwordless email sign-in works (and how to make them arrive)

import { createHash, randomBytes } from "node:crypto";

export function createMagicLinkToken() {
  const token = randomBytes(32).toString("base64url"); // goes in the email
  const tokenHash = createHash("sha256").update(token).digest("hex"); // goes in the database
  const expiresAt = new Date(Date.now() + 15 * 60 * 1000);
  return { token, tokenHash, expiresAt };
}

// GET: render a page. Never redeem the token here.
app.get("/auth/magic", (req, res) => {
  res.set("Referrer-Policy", "no-referrer");
  res.send(`<form method="post" action="/auth/magic">
  <input type="hidden" name="token" value="${escapeHtml(String(req.query.token ?? ""))}">
  <button type="submit">Sign in to Example</button>
</form>`);
});

// POST: claim the token once, then start the session.
app.post("/auth/magic", express.urlencoded({ extended: false }), async (req, res) => {
  const tokenHash = sha256(String(req.body.token ?? ""));
  const { rows } = await db.query(
    "DELETE FROM magic_links WHERE token_hash = $1 AND expires_at > now() RETURNING user_id",
    [tokenHash],
  );
  if (!rows[0]) return res.redirect(303, "/login?error=link_expired");
  await startSession(res, rows[0].user_id);
  res.redirect(303, "/");
});

import { Groundmail } from "groundmail";

const gm = new Groundmail(process.env.GROUNDMAIL_API_KEY!);

export async function sendMagicLink(email: string, linkId: string, token: string) {
  const url = `https://app.example.com/auth/magic?token=${token}`;
  return gm.emails.send({
    from: { email: "no-reply@mail.example.com", name: "Example" },
    to: email,
    subject: "Your Example sign-in link",
    text: `Sign in to Example:\n\n${url}\n\nThis link works once and expires in 15 minutes. If you didn't try to sign in, ignore this email.`,
    html: `<p><a href="${url}">Sign in to Example</a></p>
<p>Or paste this link into your browser:<br>${url}</p>
<p>This link works once and expires in 15 minutes. If you didn't try to sign in, ignore this email.</p>`,
    tags: [{ name: "type", value: "magic_link" }],
    idempotencyKey: `magic-link:${linkId}`,
  });
}

import hashlib
import os
import secrets

from groundmail import Groundmail

client = Groundmail(os.environ["GROUNDMAIL_API_KEY"])


def create_token() -> tuple[str, str]:
    token = secrets.token_urlsafe(32)  # goes in the email
    return token, hashlib.sha256(token.encode()).hexdigest()  # store the hash


def send_magic_link(email: str, link_id: str, token: str) -> dict:
    url = f"https://app.example.com/auth/magic?token={token}"
    return client.emails.send(
        from_="Example <no-reply@mail.example.com>",
        to=email,
        subject="Your Example sign-in link",
        text=(
            f"Sign in to Example:\n\n{url}\n\n"
            "This link works once and expires in 15 minutes. "
            "If you didn't try to sign in, ignore this email."
        ),
        html=(
            f'<p><a href="{url}">Sign in to Example</a></p>'
            f"<p>Or paste this link into your browser:<br>{url}</p>"
            "<p>This link works once and expires in 15 minutes. "
            "If you didn't try to sign in, ignore this email.</p>"
        ),
        tags=[{"name": "type", "value": "magic_link"}],
        idempotency_key=f"magic-link:{link_id}",
    )