@auth-gate/core

Core client library for AuthGate — the OAuth proxy that handles provider configuration, token exchange, and user normalization so you don't have to.

Installation

npm install @auth-gate/core

Setup

import { createAuthGateClient } from "@auth-gate/core";

const client = createAuthGateClient({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: "https://authgate.dev", // or your self-hosted instance
});

Features

OAuth Authentication

Supports Google, GitHub, Discord, Azure (Microsoft), and Apple.

// Generate the authorization URL (async — resolves project ID from API key)
const url = await client.getOAuthUrl("google", "https://yourapp.com/auth/callback");

// After callback, verify the JWT token from AuthGate
const result = await client.verifyToken(token);
if (result.valid) {
  console.log(result.user); // { id, email, name, picture, provider }
}

Session Encryption

Sessions are encrypted with AES-256-GCM using keys derived via HKDF-SHA256.

// Encrypt a user into a session cookie value
const cookieValue = await client.encryptSession(user);

// Decrypt a session cookie back to a user
const user = await client.decryptSession(cookieValue);

// Get full payload with timestamps
const payload = await client.decryptSessionPayload(cookieValue);
// { user, iat, exp }

CSRF / OAuth State

// Before redirect: create state + nonce
const { state, nonce } = await client.createState();
// Store nonce in a cookie, pass state in the OAuth URL

// After callback: verify state against nonce
const valid = await client.verifyState(state, nonce);

Email Authentication

// Sign up
await client.emailSignup({ email, password, name });

// Sign in
const result = await client.emailSignin({ email, password });

// Verify email with OTP code
await client.emailVerifyCode({ email, code });

// Password reset
await client.emailForgotPassword({ email });
await client.emailResetPassword({ token, password });

// Magic link
await client.magicLinkSend({ email, callbackUrl });

SMS Authentication

// Send verification code
await client.smsSendCode({ phone }); // E.164 format: +15551234567

// Verify code
const result = await client.smsVerifyCode({ phone, code });

Multi-Factor Authentication (MFA)

// TOTP setup
const setup = await client.mfaTotpSetup(jwt);
// { secret, qr_code, uri }

// Verify TOTP setup
await client.mfaTotpVerifySetup(jwt, { code });

// Complete MFA challenge during sign-in
const result = await client.mfaVerify({ mfa_challenge, code, method: "totp" });

// SMS-based MFA
await client.mfaSmsSendCode({ mfa_challenge });
await client.mfaVerify({ mfa_challenge, code, method: "sms" });

// Backup codes
const codes = await client.mfaBackupCodesGenerate(jwt);

Session Management

// Refresh an expired token
const result = await client.refreshToken(refreshToken);

// Revoke a session
await client.revokeSession(refreshToken);

Cookie Helpers

client.cookieName;              // "__authgate"
client.nonceCookieName;         // "__authgate_nonce"
client.refreshTokenCookieName;  // "__authgate_refresh"
client.sessionMaxAge;           // 604800 (7 days)

client.getSessionCookieOptions();
// { httpOnly: true, secure: true, sameSite: "lax", maxAge: 604800, path: "/" }

client.getNonceCookieOptions();
// { httpOnly: true, secure: true, sameSite: "lax", maxAge: 600, path: "/" }

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your AuthGate API key (also used to resolve project ID) | | baseUrl | string | Yes | AuthGate instance URL | | cookieName | string | No | Session cookie name (default: __authgate) | | sessionMaxAge | number | No | Session TTL in seconds (default: 604800 / 7 days) | | callbackPath | string | No | OAuth callback path (default: /api/auth/callback) |

Types

import type {
  AuthGateUser,
  AuthGateConfig,
  OAuthProvider,
  TokenVerifyResult,
  SessionPayload,
  CookieOptions,
  MfaChallengeResponse,
  MfaStatus,
  TotpSetupResponse,
  BackupCodesResponse,
} from "@auth-gate/core";

AuthGateUser

interface AuthGateUser {
  id: string;
  email: string;
  phone?: string;
  name?: string;
  picture?: string;
  provider: string;
}

OAuthProvider

type OAuthProvider = "google" | "github" | "discord" | "azure" | "apple";

Error Handling

import {
  AuthGateError,
  TokenVerificationError,
  SessionDecryptionError,
  InvalidStateError,
} from "@auth-gate/core";

Framework SDKs

For framework-specific integrations with built-in route handlers, session helpers, and middleware:

• Next.js — @auth-gate/nextjs
• React + Hono — @auth-gate/react

License

MIT