faceit-visa

v1.0.2

Published

5 months ago

A lightweight OAuth2 authentication library for FACEIT integration

Downloads

0High
0Medium
0Low

shadiflo

faceit oauth2 authentication gaming express nodejs

FaceitVisa

The easiest way to add FACEIT OAuth2 authentication to any web application.

Inspired by the simplicity of getting a visa - just the essentials you need to authenticate with FACEIT.

✨ Features

🚀 One-Command Setup - Auto-generates complete integration
🔒 Secure by Default - PKCE OAuth2 flow with security best practices
🌐 Works Everywhere - Next.js, PHP, Vanilla HTML/CSS/JS
🤖 Smart Detection - Automatically detects your project type
🎯 TypeScript Ready - Full type safety included
📦 Zero Config - Just add your FACEIT credentials

🚀 Quick Start

Auto-Setup (Recommended)

npm install faceit-visa

That's it! We'll detect your project type and generate everything you need.

Manual Setup

Choose your framework:

# Next.js App Router (TypeScript + HTTPS)
npx faceit-visa generate nextjs-app-router

# Vanilla HTML/CSS/JS (Universal)
npx faceit-visa generate vanilla

# Pure PHP (Zero dependencies)
npx faceit-visa generate php

📋 What Gets Generated

Next.js App Router

src/app/api/auth/
├── faceit/route.ts           # OAuth initiation
├── callback/faceit/route.ts  # OAuth callback
├── user/route.ts            # Get current user
└── logout/route.ts          # Logout endpoint

src/components/
└── Navbar.tsx               # Ready-to-use auth navbar

.env.example                 # Environment template

Vanilla HTML/CSS/JS

├── index.html              # Main page with auth
├── faceit-auth.js          # Authentication logic
├── server.js               # Express.js backend
├── styles.css              # Responsive styling
├── package.json            # Dependencies
└── .env.example            # Environment template

PHP

├── index.php               # Homepage
├── login.php               # OAuth initiation
├── callback.php            # OAuth callback
├── logout.php              # Logout
├── profile.php             # User profile page
├── FaceitAuth.php          # OAuth class
├── config.php              # Configuration
├── styles.css              # Styling
└── .env.example            # Environment template

🎯 Examples

Next.js Integration

After running npx faceit-visa generate nextjs-app-router:

1. Add credentials to .env.local:

FACEIT_CLIENT_ID=your_client_id_here
FACEIT_CLIENT_SECRET=your_client_secret_here
NEXTAUTH_URL=https://localhost:3000

2. Use the generated navbar:

// app/layout.tsx
import Navbar from '@/components/Navbar'

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <Navbar />
        {children}
      </body>
    </html>
  )
}

3. Start with HTTPS:

npm run dev -- --experimental-https

4. Set FACEIT redirect URI:

https://localhost:3000/api/auth/callback/faceit

PHP Integration

After running npx faceit-visa generate php:

1. Add credentials to .env:

FACEIT_CLIENT_ID=your_client_id_here
FACEIT_CLIENT_SECRET=your_client_secret_here
BASE_URL=http://localhost:8000

2. Start PHP server:

php -S localhost:8000

3. Set FACEIT redirect URI:

http://localhost:8000/callback.php

Vanilla HTML/JS Integration

After running npx faceit-visa generate vanilla:

1. Install dependencies:

npm install

2. Add credentials to .env:

FACEIT_CLIENT_ID=your_client_id_here
FACEIT_CLIENT_SECRET=your_client_secret_here
BASE_URL=http://localhost:3000

3. Start server:

npm start

🔧 Manual Usage (Advanced)

For custom implementations:

import { FaceitVisa } from 'faceit-visa'

const visa = new FaceitVisa({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://yourapp.com/callback'
})

// Generate auth URL
const { url, codeVerifier } = visa.getAuthUrl()

// Exchange code for token
const token = await visa.exchangeCode(code, codeVerifier)

// Get user profile
const user = await visa.getUserProfile(token.access_token)

🎮 FACEIT Setup

Go to FACEIT Developer Portal
Create a new application
Set your redirect URI based on your template:
- Next.js: https://localhost:3000/api/auth/callback/faceit
- PHP: http://localhost:8000/callback.php
- Vanilla: http://localhost:3000/api/auth/callback/faceit
Copy Client ID and Client Secret to your .env file

🛠️ CLI Commands

# Generate templates
npx faceit-visa generate nextjs-app-router
npx faceit-visa generate vanilla
npx faceit-visa generate php

# List available templates
npx faceit-visa list

# Get help
npx faceit-visa help

🔒 Security Features

PKCE Flow: Proof Key for Code Exchange for maximum security
State Parameter: CSRF protection during OAuth flow
Secure Cookies: httpOnly, secure, SameSite settings
Input Sanitization: All user inputs properly validated
Token Storage: Secure server-side session management

🌟 User Flow

Click "Login with FACEIT" → Redirect to FACEIT OAuth
User authorizes → FACEIT redirects back with code
Exchange code for token → Get access token securely
Fetch user profile → Display user info and gaming stats
Session management → Maintain login state

📚 API Reference

FaceitVisa Class

interface FaceitUser {
  user_id: string
  player_id: string
  nickname: string
  avatar: string
  country: string
  level?: number
}

class FaceitVisa {
  getAuthUrl(): { url: string, codeVerifier: string }
  exchangeCode(code: string, codeVerifier: string): Promise<TokenResponse>
  getUserProfile(accessToken: string): Promise<FaceitUser>
}

🚨 Troubleshooting

| Issue | Solution | |-------|----------| | 404 on callback | Check redirect URI matches exactly | | HTTPS required | Use --experimental-https for Next.js dev | | Missing credentials | Verify .env file has correct values | | CORS errors | Ensure same origin for frontend/backend |

📦 Requirements

Next.js: Node.js 18+, Next.js 13+
PHP: PHP 7.4+, cURL extension
Vanilla: Node.js 16+, Express.js

🤝 Contributing

Contributions welcome! Please check the issues page.

📄 License

MIT License - see LICENSE file for details.

🙋 Support

📖 Documentation: This README
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Made with ❤️ for the gaming community