🔐 passport-magic-code

A flexible, plug-and-play Passport strategy for passwordless login, registration, and callback-based authentication using magic codes (OTP-like).

Built with:

• ✅ TypeScript and Zod for validation and type-safety
• ⚡️ Customizable storage (in-memory, database, etc.)
• 📬 Pluggable logic for sending and processing codes
• 🧠 Simple interface that handles login, registration, and callbacks

⚠️ Zod Compatibility Notice

• Version ^1.0.0 uses Zod v3
• Version ^2.0.0 and later uses Zod v4

📦 Install

npm install passport-magic-code

✨ Features

• 🔒 Magic code authentication (e.g. 6-digit OTP via email or SMS)
• 📬 Bring your own code delivery function (email, SMS, etc.)
• 🧠 Validates schema and logic with zod
• ⚙️ Works with any Express-based app using passport
• ⏳ Code expiration and single-use handling

🚀 Usage Example

import { Strategy as MagicCodeStrategy } from "passport-magic-code";
import { v4 as uuidv4 } from "uuid";

const magicCode = new MagicCodeStrategy(
  {
    secret: process.env.MAGIC_CODE_SECRET,
    codeLength: 6,
    userPrimaryKey: "email",
    codeField: "code",
    expiresIn: 15, // minutes
    storage: {
      codes: {},
      set: async (key, value) => {
        await db.otps.create({ code: key, value });
      },
      get: async (key) => {
        return (await db.otps.findOne({ code: key }))?.value;
      },
      delete: async (key) => {
        await db.otps.deleteOne({ code: key });
      },
    },
  },
  // sendCode(user, code, options)
  async ({ email, ...user }, code, { action }) => {
    const existingUser = await db.users.findOne({ email });

    if (action === "login" && !existingUser) return;

    if (action === "register" && (existingUser || !email)) {
      return {
        error: "User already exists",
        statusCode: 400,
      };
    }

    await sendEmail({
      to: email,
      subject: "Your Login Code",
      html: `<p>Your code is: <strong>${code}</strong></p>`,
    });
  },
  // callback(user, options)
  async ({ email, ...user }) => {
    let account = await db.users.findOne({ email });

    if (!account) {
      account = await db.users.create({
        id: uuidv4(),
        email,
        ...user,
        createdAt: new Date(),
      });

      await db.orgs.create({
        uid: account.id,
        id: "personal",
        profile: {
          name: "Personal",
          description: "Your default organization",
        },
      });
    }

    return account;
  }
);

🧩 Configuration

Required Args

| Option | Type | Default | Description | | ---------------- | --------------- | ------- | ------------------------------------------- | | secret | string | – | Secret used internally (min 16 chars) | | codeLength | number | 4 | Length of the OTP code | | storage | MemoryStorage | – | Your code storage interface (see below) | | expiresIn | number | 30 | Minutes until code expires | | userPrimaryKey | string | email | Field used to identify the user | | codeField | string | code | Field to look for code in body/query/params |

📦 Storage Interface

Implement a MemoryStorage object like so:

const storage = {
  codes: {},

  async set(key, value) {
    // Save to DB or in-memory store
  },

  async get(key) {
    // Return the stored value
  },

  async delete(key) {
    // Delete the key after it's used
  },
};

🛠 sendCode(user, code, options)

Use this function to send the generated code to the user via:

• 📧 Email
• 📱 SMS
• 🔔 Push notification

This function is called during login/register actions.

🔄 callback(user, options)

This is where you:

• Lookup or create the user
• Return the user object to passport
• Attach session or token logic as needed

This function is called when the user submits the correct code.

🔐 API

Actions (options.action)

• "login": Login flow (fail silently if user not found)
• "register": Register flow (fail if user exists or info is incomplete)
• "callback": Validate code and complete login

Strategy Usage

passport.use("magic-code", magicCode);

app.post(
  "/auth/send",
  passport.authenticate("magic-code", { action: "login" })
);
app.post(
  "/auth/callback",
  passport.authenticate("magic-code", { action: "callback" })
);

🧪 Development

• Built in TypeScript
• Schema validation with Zod
• Fully type-safe, async/await-first

📜 License

MIT © 2025