gpsoauth-js

A modern JavaScript/TypeScript implementation of Google Play Services OAuth (gpsoauth) for React Native and Node.js.

Features

• 🚀 Modern: Built with TypeScript and modern JavaScript
• 📱 React Native Compatible: Works seamlessly with React Native and Expo
• 🌐 Universal: Also works in Node.js environments
• 🔐 Complete: Implements performOAuth, exchangeToken, and performMasterLogin
• 🐛 Debuggable: Comprehensive logging for troubleshooting authentication issues
• 📝 Type Safe: Full TypeScript support with detailed type definitions

Installation

npm install gpsoauth-js crypto-js
# or
yarn add gpsoauth-js crypto-js

For TypeScript projects, also install types:

npm install --save-dev @types/crypto-js

Quick Start

Basic OAuth Authentication

import { GPSOAuth } from 'gpsoauth-js';

// Perform OAuth with a master token
const result = await GPSOAuth.performOAuth(
  '[email protected]',
  'your_master_token_here',
  {
    service: 'sj', // Google Play Music
    app: 'com.google.android.music',
    clientSig: '...'
  }
);

if (result.error) {
  console.error('OAuth failed:', result.error);
} else {
  console.log('Auth token:', result.auth);
  console.log('LSID:', result.lsid);
  console.log('SID:', result.sid);
}

Token Exchange

// Exchange a web OAuth token for a master token
const result = await GPSOAuth.exchangeToken(
  '[email protected]',
  'web_oauth_token_here'
);

if (result.error) {
  console.error('Token exchange failed:', result.error);
} else {
  console.log('Master token:', result.masterToken);
}

API Reference

GPSOAuth.performOAuth(email, masterToken, config?)

Performs OAuth authentication to a specific Google service using a master token.

Parameters:

• email (string): Google account email
• masterToken (string): Master token from previous authentication
• config (OAuthConfig, optional): Configuration options

Returns: Promise<AuthResult>

Config Options:

interface OAuthConfig {
  service?: string;              // Default: 'sj'
  app?: string;                 // Default: 'com.google.android.music'
  clientSig?: string;           // Default: '...'
  androidId?: string;           // Auto-generated if not provided
  deviceCountry?: string;       // Default: 'us'
  operatorCountry?: string;     // Default: 'us'
  lang?: string;                // Default: 'en'
  sdkVersion?: number;          // Default: 17
  googlePlayServicesVersion?: number; // Default: 240913000
}

GPSOAuth.exchangeToken(email, token, config?)

Exchanges a web OAuth token for a master token.

Parameters:

• email (string): Google account email
• token (string): Web OAuth token
• config (TokenExchangeConfig, optional): Configuration options

Returns: Promise<AuthResult>

Response Format

interface AuthResult {
  masterToken?: string;  // Master token for subsequent operations
  error?: string;        // Error message if authentication failed
  email?: string;        // User's email address
  auth?: string;         // Authentication token for API requests
  lsid?: string;         // Login Session ID
  sid?: string;          // Session ID
}

Common Use Cases

Google Keep Integration

const keepAuth = await GPSOAuth.performOAuth(
  '[email protected]',
  masterToken,
  {
    service: 'oauth2:https://www.googleapis.com/auth/memento',
    app: 'com.google.android.keep',
    clientSig: '24bb24c05e47e0aefa68a58a766179d9b613a600'
  }
);

// Use keepAuth.auth in Authorization header:
// Authorization: GoogleLogin auth=${keepAuth.auth}

Google Play Music

const musicAuth = await GPSOAuth.performOAuth(
  '[email protected]',
  masterToken,
  {
    service: 'sj',
    app: 'com.google.android.music',
    clientSig: '...'
  }
);

React Native Example

import { GPSOAuth } from 'gpsoauth-js';
import AsyncStorage from '@react-native-async-storage/async-storage';

const authenticateWithGoogle = async () => {
  try {
    // Load saved master token
    const masterToken = await AsyncStorage.getItem('@master_token');
    const email = await AsyncStorage.getItem('@email');
    
    if (!masterToken || !email) {
      throw new Error('No saved credentials');
    }
    
    // Perform OAuth
    const result = await GPSOAuth.performOAuth(email, masterToken, {
      service: 'oauth2:https://www.googleapis.com/auth/memento',
      app: 'com.google.android.keep',
      clientSig: '24bb24c05e47e0aefa68a58a766179d9b613a600'
    });
    
    if (result.error) {
      throw new Error(result.error);
    }
    
    // Use result.auth for API requests
    return result.auth;
    
  } catch (error) {
    console.error('Authentication failed:', error);
    throw error;
  }
};

Troubleshooting

Common Issues

1. "BadAuthentication" Error

   • Ensure your master token is correct and doesn't contain line breaks
   • Verify the service, app, and clientSig parameters match a valid Google service
   • Check that your master token hasn't expired

2. 403 Forbidden

   • Usually indicates incorrect authentication parameters
   • Enable debug logging to see the exact request being sent

3. Network Issues

   • The library makes requests to https://android.clients.google.com/auth
   • Ensure your app has network permissions

Debug Logging

The library includes comprehensive console logging. Check your console for detailed information about requests and responses.

Limitations

• RSA Encryption: The performMasterLogin function currently uses a mock signature implementation. For production use with password authentication, proper RSA encryption should be implemented.
• SSL Context: Unlike the Python implementation, this library cannot modify SSL/TLS settings, which may affect compatibility with some Google services.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Credits

Based on the original gpsoauth Python library by Simon Weber.

Related Projects

• gpsoauth - Original Python implementation
• gkeepapi - Unofficial Google Keep API for Python