🔐 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