@pushpilot/oauth-helpers

Stateless OAuth utilities for provider integrations.

Executive Summary

@pushpilot/oauth-helpers is a pure OAuth utility package for generating authorization URLs, exchanging codes for tokens, refreshing tokens, and validating webhook signatures. It does not manage users, sessions, tokens, or storage.

PushPilot (or any SaaS) remains fully in control of:

• User identity
• Token persistence
• Security policy
• Authorization decisions

This package exists only to correctly and consistently talk OAuth.

Design Principles

• Stateless: No caching or state management.
• No opinions about storage: You choose your DB.
• Explicit inputs, explicit outputs: No magic.
• Provider-aware, SaaS-agnostic: Knows provider quirks, but not your app logic.
• Zero side effects: Just pure functions (and network calls).

Installation

npm install @pushpilot/oauth-helpers

Usage

Import

import {
  getAuthUrl,
  exchangeCode,
  refreshToken,
  verifyWebhookSignature
} from '@pushpilot/oauth-helpers'

Supported Providers

The package currently supports the following provider identifiers (OAuthProvider):

• asana
• jira
• linear
• trello
• clickup
• monday (Auth only)

1. Generate Authorization URL

const url = getAuthUrl('asana', {
  clientId: process.env.ASANA_CLIENT_ID,
  redirectUri: 'https://pushpilot.app/oauth/callback',
  scopes: ['default'],
  state: csrfToken
})

Behavior: Returns a fully formed provider URL string. Caller must verify state on callback.

2. Exchange Authorization Code for Tokens

const tokens = await exchangeCode('asana', {
  code: req.query.code,
  clientId: process.env.ASANA_CLIENT_ID,
  clientSecret: process.env.ASANA_CLIENT_SECRET,
  redirectUri: 'https://pushpilot.app/oauth/callback'
})

Returns: OAuthTokenSet (accessToken, refreshToken?, expiresAt?, raw).

3. Refresh Access Token

const newTokens = await refreshToken('asana', {
  refreshToken: oldRefreshToken,
  clientId: process.env.ASANA_CLIENT_ID,
  clientSecret: process.env.ASANA_CLIENT_SECRET
})

Behavior: Throws AuthenticationError if refresh fails. Throws NotSupportedError if the provider (e.g., Monday.com) does not support refresh tokens.

4. Webhook Signature Verification (Optional)

try {
  const valid = verifyWebhookSignature('asana', {
    payload: rawBody, // string or Buffer
    signature: req.headers['x-hook-signature'],
    secret: process.env.ASANA_WEBHOOK_SECRET
  })

  if (!valid) {
    res.status(401).send('Invalid signature')
  }
} catch (error) {
  if (error instanceof NotSupportedError) {
    // Provider verification not supported
  }
}

Examples

The package includes runnable examples in the examples/ directory.

# Generate sample Auth URLs for providers
npm run example:url

# Verify a sample webhook signature
npm run example:webhook

# Attempt a real token exchange (requires .env configuration)
npm run example:exchange

Development

Testing

This project uses Jest for unit testing.

npm test

Build

To build the project for distribution:

npm run build

Error Model

• OAuthError: Base class
• AuthenticationError: Auth failed
• ProviderConfigError: Configuration or param error
• NetworkError: HTTP/Network failure
• NotSupportedError: Feature not supported for provider

License

ISC