@microfox/google-oauth NPM

Google OAuth SDK

A robust TypeScript SDK for Google OAuth 2.0 authentication and API integration. This SDK provides a simple way to integrate Google OAuth 2.0 authentication into your application with built-in security features and TypeScript support.

Installation

npm install @microfox/google-oauth

Features

🔒 Built-in CSRF protection with state parameter
✨ TypeScript support with full type definitions
🛡️ Input validation using Zod schemas
🔄 Refresh token support
🎯 Comprehensive Google API scopes
🔍 Token validation and introspection

Usage

Import the SDK and necessary types:

import { GoogleOAuthSdk, GoogleScope } from '@microfox/google-oauth';

Initialize the SDK with your Google OAuth credentials:

const googleOAuthSdk = new GoogleOAuthSdk({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'YOUR_REDIRECT_URI',
  scopes: [GoogleScope.OPENID, GoogleScope.PROFILE, GoogleScope.EMAIL], // Optional, these are the default scopes
  state: 'custom-state-string', // Optional, a random state will be generated if not provided
});

Generate the authorization URL:

// The SDK automatically configures offline access and consent prompt
const authUrl = googleOAuthSdk.getAuthUrl();
// This will include access_type=offline and prompt=consent by default

Handle the OAuth callback:

// Get the state from the redirect URL and verify it
const receivedState = new URL(redirectUrl).searchParams.get('state');
const expectedState = await googleOAuthSdk.getState();

if (receivedState === expectedState) {
  const code = new URL(redirectUrl).searchParams.get('code');
  if (code) {
    try {
      const { accessToken, refreshToken, idToken, expiresIn } =
        await googleOAuthSdk.exchangeCodeForTokens(code);
      // Store tokens securely and use them for API calls
    } catch (error) {
      // Handle token exchange error
      console.error('Token exchange failed:', error);
    }
  }
} else {
  // Handle invalid state (potential CSRF attack)
  console.error('Invalid state parameter');
}

Refresh expired access tokens:

try {
  const { accessToken, expiresIn } =
    await googleOAuthSdk.refreshAccessToken(refreshToken);
  // Update stored access token
} catch (error) {
  // Handle refresh token error
  console.error('Token refresh failed:', error);
}

Validate access tokens:

try {
  const result = await googleOAuthSdk.validateAccessToken(accessToken);
  if (result.isValid) {
    console.log('Token is valid');
    console.log('Expires at:', new Date(result.expiresAt!).toISOString());
    console.log('Scopes:', result.scopes);
    console.log('Email:', result.email);
  } else {
    console.error('Token validation failed:', result.error);
  }
} catch (error) {
  console.error('Validation error:', error);
}

Available Scopes

The SDK provides a comprehensive set of Google API scopes through the GoogleScope enum:

Default Scopes (Automatically Included)

GoogleScope.OPENID (openid) - OpenID Connect scope
GoogleScope.PROFILE (profile) - User's basic profile information
GoogleScope.EMAIL (email) - User's email address

Google Calendar API

GoogleScope.CALENDAR (https://www.googleapis.com/auth/calendar) - Full access to Google Calendar
GoogleScope.CALENDAR_READONLY (https://www.googleapis.com/auth/calendar.readonly) - Read-only access to calendars
GoogleScope.CALENDAR_EVENTS (https://www.googleapis.com/auth/calendar.events) - Manage calendar events
GoogleScope.CALENDAR_EVENTS_READONLY (https://www.googleapis.com/auth/calendar.events.readonly) - Read-only access to calendar events

Google Drive API

GoogleScope.DRIVE (https://www.googleapis.com/auth/drive) - Full access to Google Drive
GoogleScope.DRIVE_READONLY (https://www.googleapis.com/auth/drive.readonly) - Read-only access to files
GoogleScope.DRIVE_FILE (https://www.googleapis.com/auth/drive.file) - Access to files created by the app
GoogleScope.DRIVE_METADATA (https://www.googleapis.com/auth/drive.metadata) - View and manage metadata
GoogleScope.DRIVE_APPDATA (https://www.googleapis.com/auth/drive.appdata) - Access to application data folder
GoogleScope.DRIVE_SCRIPTS (https://www.googleapis.com/auth/drive.scripts) - Modify and execute Google Apps Scripts

Gmail API

GoogleScope.GMAIL (https://www.googleapis.com/auth/gmail.readonly) - Read-only access to Gmail
GoogleScope.GMAIL_SEND (https://www.googleapis.com/auth/gmail.send) - Send emails only
GoogleScope.GMAIL_COMPOSE (https://www.googleapis.com/auth/gmail.compose) - Create and modify email drafts
GoogleScope.GMAIL_MODIFY (https://www.googleapis.com/auth/gmail.modify) - All read/write operations except delete
GoogleScope.GMAIL_FULL (https://www.googleapis.com/auth/gmail.full) - Full access to Gmail account

Google Contacts API

GoogleScope.CONTACTS (https://www.googleapis.com/auth/contacts) - Manage contacts
GoogleScope.CONTACTS_READONLY (https://www.googleapis.com/auth/contacts.readonly) - Read-only access to contacts
GoogleScope.CONTACTS_OTHER_READONLY (https://www.googleapis.com/auth/contacts.other.readonly) - Read-only access to domain's contacts

YouTube API

GoogleScope.YOUTUBE (https://www.googleapis.com/auth/youtube) - Manage YouTube account
GoogleScope.YOUTUBE_READONLY (https://www.googleapis.com/auth/youtube.readonly) - Read-only access to YouTube data
GoogleScope.YOUTUBE_UPLOAD (https://www.googleapis.com/auth/youtube.upload) - Upload YouTube videos
GoogleScope.YOUTUBE_PARTNER (https://www.googleapis.com/auth/youtubepartner) - Manage YouTube content and channel

Google Photos API

GoogleScope.PHOTOS (https://www.googleapis.com/auth/photoslibrary) - Access to Google Photos library
GoogleScope.PHOTOS_READONLY (https://www.googleapis.com/auth/photoslibrary.readonly) - Read-only access to photos
GoogleScope.PHOTOS_SHARING (https://www.googleapis.com/auth/photoslibrary.sharing) - Share photos and albums

Google Fitness API

GoogleScope.FITNESS (https://www.googleapis.com/auth/fitness.activity.read) - Read fitness activity data
GoogleScope.FITNESS_ACTIVITY_WRITE (https://www.googleapis.com/auth/fitness.activity.write) - Write fitness activity data
GoogleScope.FITNESS_LOCATION_READ (https://www.googleapis.com/auth/fitness.location.read) - Read location data
GoogleScope.FITNESS_LOCATION_WRITE (https://www.googleapis.com/auth/fitness.location.write) - Write location data

Google Tasks API

GoogleScope.TASKS (https://www.googleapis.com/auth/tasks) - Manage tasks and task lists
GoogleScope.TASKS_READONLY (https://www.googleapis.com/auth/tasks.readonly) - Read-only access to tasks

Google Workspace APIs

GoogleScope.SHEETS (https://www.googleapis.com/auth/spreadsheets) - Full access to Google Sheets
GoogleScope.SHEETS_READONLY (https://www.googleapis.com/auth/spreadsheets.readonly) - Read-only access to Sheets
GoogleScope.DOCS (https://www.googleapis.com/auth/documents) - Full access to Google Docs
GoogleScope.DOCS_READONLY (https://www.googleapis.com/auth/documents.readonly) - Read-only access to Docs

Google Cloud Platform

GoogleScope.CLOUD_PLATFORM (https://www.googleapis.com/auth/cloud-platform) - Full access to Google Cloud services
GoogleScope.CLOUD_PLATFORM_READONLY (https://www.googleapis.com/auth/cloud-platform.read-only) - Read-only access to Cloud services

Google Analytics

GoogleScope.ANALYTICS (https://www.googleapis.com/auth/analytics) - Full access to Analytics data
GoogleScope.ANALYTICS_READONLY (https://www.googleapis.com/auth/analytics.readonly) - Read-only access to Analytics

Google Classroom

GoogleScope.CLASSROOM_COURSES (https://www.googleapis.com/auth/classroom.courses) - Manage Classroom courses
GoogleScope.CLASSROOM_COURSES_READONLY (https://www.googleapis.com/auth/classroom.courses.readonly) - View Classroom courses
GoogleScope.CLASSROOM_ROSTERS (https://www.googleapis.com/auth/classroom.rosters) - Manage class rosters
GoogleScope.CLASSROOM_PROFILE_EMAILS (https://www.googleapis.com/auth/classroom.profile.emails) - View student/teacher email addresses

Google Meet

GoogleScope.MEET (https://www.googleapis.com/auth/meetings.space.readonly) - View Meet space information
GoogleScope.MEET_ROOMS (https://www.googleapis.com/auth/meetings.room.readonly) - View Meet room information

Google People API

GoogleScope.PEOPLE (https://www.googleapis.com/auth/people) - Manage contacts and other people data
GoogleScope.PEOPLE_READONLY (https://www.googleapis.com/auth/people.readonly) - Read-only access to people data

Google Chat API

GoogleScope.CHAT (https://www.googleapis.com/auth/chat.messages) - Allows the application to send and manage chat messages on behalf of the user.
GoogleScope.CHAT_READONLY (https://www.googleapis.com/auth/chat.messages.readonly) - Provides the application with read-only access to the user's chat messages.

Google Search Console API

GoogleScope.WEBMASTERS (https://www.googleapis.com/auth/webmasters) - Grants the application full access to the user's Search Console data.
GoogleScope.WEBMASTERS_READONLY (https://www.googleapis.com/auth/webmasters.readonly) - Provides the application with read-only access to the user's Search Console data.

Error Handling

The SDK uses Zod for input validation and provides clear error messages:

try {
  const { accessToken, refreshToken, idToken, expiresIn } =
    await googleOAuthSdk.exchangeCodeForTokens(code);
} catch (error) {
  if (error instanceof Error) {
    console.error('OAuth error:', error.message);
    // Error messages will be in format: "error_code: error_description"
  }
}