simply-auth

simply-auth is a lightweight Node.js library that simplifies Google and GitHub OAuth2 authentication for server‑side applications. It provides helpers to generate login URLs and exchange authorization codes for user info and signed JWT tokens (access and refresh).

Installation

npm install simply-auth

Usage

Google OAuth

import { simpleGoogleLink, simpleGoogleCallback } from "simply-auth";

// Configuration
const GOOGLE_CLIENT_ID = process.env.GOOGLE_CLIENT_ID;
const GOOGLE_CLIENT_SECRET = process.env.GOOGLE_CLIENT_SECRET;
const GOOGLE_REDIRECT_URI = "https://yourapp.com/auth/google/callback";

// JWT Configuration
const JWT_DETAILS = {
  accessSecret: process.env.JWT_ACCESS_SECRET,
  refreshSecret: process.env.JWT_REFRESH_SECRET,
  accessExpiry: "15m",
  refreshExpiry: "7d",
};

// User Adapter (Implement your DB logic)
const userAdapter = {
  async findByEmail(email) {
    // return await db.users.findOne({ email });
  },
  async createUser(userInfo) {
    // return await db.users.create(userInfo);
  },
};

// 1. Generate Login Link
const loginUrl = simpleGoogleLink(GOOGLE_CLIENT_ID, GOOGLE_REDIRECT_URI);
console.log("Login here:", loginUrl);

// 2. Handle Callback
// Inside your route handler (e.g., Express)
app.get("/auth/google/callback", async (req, res) => {
  const { code } = req.query;

  const result = await simpleGoogleCallback(
    code,
    GOOGLE_CLIENT_ID,
    GOOGLE_REDIRECT_URI,
    GOOGLE_CLIENT_SECRET,
    JWT_DETAILS,
    userAdapter,
  );

  if (!result.user) {
    return res.status(401).json({ error: "Authentication failed" });
  }

  // result contains: { user, tokens: { accessToken, refreshToken } }
  res.json(result);
});

GitHub OAuth

The library creates a URL with user:email scope. If the user's public profile lacks an email, it automatically fetches it from the GitHub User Emails API.

import { simpleGithubLink, simpleGithubCallback } from "simply-auth";

// ... (Configuration similar to above defined constants)

// 1. Generate Login Link
const loginUrl = simpleGithubLink(GITHUB_CLIENT_ID, GITHUB_REDIRECT_URI);

// 2. Handle Callback
app.get("/auth/github/callback", async (req, res) => {
  const { code } = req.query;

  const result = await simpleGithubCallback(
    code,
    GITHUB_CLIENT_ID,
    GITHUB_REDIRECT_URI,
    GITHUB_CLIENT_SECRET,
    JWT_DETAILS,
    userAdapter,
  );

  if (!result.user) {
    return res.status(401).json({ error: "Authentication failed" });
  }

  res.json(result);
});

API Reference

simpleGoogleLink(clientId, redirectUri)

Returns the Google OAuth2 authorization URL.

simpleGithubLink(clientId, redirectUri)

Returns the GitHub OAuth2 authorization URL (includes user:email scope).

simpleGoogleCallback(authCode, clientId, redirectUri, clientSecret, jwtDetails, userAdapter)

simpleGithubCallback(authCode, clientId, redirectUri, clientSecret, jwtDetails, userAdapter)

Exchanges the auth code for tokens and user info.

Parameters:

• authCode: The code received in the query params.
• clientId: Your App's Client ID.
• redirectUri: Your App's Redirect URI.
• clientSecret: Your App's Client Secret.
• jwtDetails: Object containing JWT config.
  • accessSecret: Secret for access token.
  • refreshSecret: Secret for refresh token.
  • accessExpiry: Expiration time (e.g., "15m").
  • refreshExpiry: Expiration time (e.g., "7d").
• userAdapter: Object with DB methods.
  • findByEmail(email): Should return user object or null.
  • createUser(userInfo): Should create and return the user. userInfo includes provider data.

Returns:

Promise resolving to { user, tokens: { accessToken, refreshToken } }. On failure, returns { user: null, tokens: { accessToken: null, refreshToken: null } }.

License

ISC