npm package: @scharfcsh/easyauth
Description: Simplified Multi-Provider Authentication for Node.js Applications
Author: Scharfcsh
Latest version: 1.0.3

# @scharfcsh/easyauth

A lightweight, plug-and-play authentication library for Node.js that gives you **Google, GitHub, Facebook, and Firebase** authentication with minimal setup — no complex OAuth boilerplate, no SDK hell, no endless copy-paste.

It exposes clean provider functions that:
- Generate login URLs,
- Exchange auth codes for access tokens,
- Return **normalized user objects**.

No CLI setup, no file generation — just install and use.

---

## 🚀 Installation

```bash
npm install @scharfcsh/easyauth
```

---

## 🧩 Supported Providers

- Google
- GitHub
- Facebook
- Firebase (Email/Password / Token login — depends on your implementation)

All providers expose the same interface:

```ts
{
  authURL: string;
  getAccessToken(code): Promise<{ access_token: string }>;
  getUser(token): Promise<NormalizedUser>;
}
```

`NormalizedUser` looks like:

```ts
{
  id: string;
  name: string;
  email: string;
  avatar?: string;
  provider: "google" | "github" | "facebook" | "firebase";
}
```

---

## 📦 Basic Usage Example (Node.js)

1. Import the provider you need

```ts
import { createGoogleAuth } from "@scharfcsh/easyauth/google";
```

2. Configure it

```ts
const google = createGoogleAuth({
  clientId: process.env.GOOGLE_ID!,
  clientSecret: process.env.GOOGLE_SECRET!,
  redirectURI: process.env.GOOGLE_REDIRECT!,
});
```

3. Redirect user to login

```ts
console.log("Login:", google.authURL);
```

4. Handle OAuth callback

```ts
const token = await google.getAccessToken(code);
const user = await google.getUser(token.access_token);

console.log(user);
```

---

## 🌍 Full Express Example (GitHub + Facebook)

A complete “real world” example:

```ts
import express from "express";
import dotenv from "dotenv";

dotenv.config();

import { createGitHubAuth } from "@scharfcsh/easyauth/github";
import { createFacebookAuth } from "@scharfcsh/easyauth/facebook";

const app = express();
const PORT = 3000;

// --- GitHub Config ---
const github = createGitHubAuth({
  clientId: process.env.GITHUB_ID!,
  clientSecret: process.env.GITHUB_SECRET!,
  redirectURI: process.env.GITHUB_REDIRECT!,
});

// GitHub login
app.get("/auth/github", (_, res) => {
  res.redirect(github.authURL);
});

app.get("/auth/github/callback", async (req, res) => {
  const code = req.query.code as string;

  try {
    const token = await github.getAccessToken(code);
    const user = await github.getUser(token.access_token);

    res.send(`GitHub Login Success → ${user.name} (${user.email})`);
  } catch (err) {
    res.status(500).send("GitHub Authentication Failed");
  }
});

// --- Facebook Config ---
const facebook = createFacebookAuth({
  clientId: process.env.FACEBOOK_ID!,
  clientSecret: process.env.FACEBOOK_SECRET!,
  redirectURI: process.env.FACEBOOK_REDIRECT!,
});

// Facebook login
app.get("/auth/facebook", (_, res) => {
  res.redirect(facebook.authURL);
});

app.get("/auth/facebook/callback", async (req, res) => {
  const code = req.query.code as string;

  try {
    const token = await facebook.getAccessToken(code);
    const user = await facebook.getUser(token.access_token);

    res.send(`Facebook Login Success → ${user.name} (${user.email})`);
  } catch (err) {
    res.status(500).send("Facebook Authentication Failed");
  }
});

app.listen(PORT, () => {
  console.log(`Server running: http://localhost:${PORT}`);
  console.log("GitHub Login → http://localhost:3000/auth/github");
  console.log("Facebook Login → http://localhost:3000/auth/facebook");
});
```

---

## 🔧 Environment Variables Required

Create a `.env` manually:

```env
# Google
GOOGLE_ID=
GOOGLE_SECRET=
GOOGLE_REDIRECT=http://localhost:3000/auth/google/callback

# GitHub
GITHUB_ID=
GITHUB_SECRET=
GITHUB_REDIRECT=http://localhost:3000/auth/github/callback

# Facebook
FACEBOOK_ID=
FACEBOOK_SECRET=
FACEBOOK_REDIRECT=http://localhost:3000/auth/facebook/callback

# Firebase (optional)
FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
```


---

## 🛠 Adding Your Own Providers

- Duplicate any provider file
- Update:
  - login URL
  - token URL
  - scopes
  - profile URL
- Export `create<Provider>Auth`

Every provider behaves the same, keeping your code clean and maintainable.

---

## 🤝 Contributing

- Add OAuth providers
- Improve normalization
- Submit examples
- Fix bugs

PRs are welcome.

---

## 📄 License

MIT — Use it, modify it, break it, fix it.