@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

``bash
npm install @pushpilot/oauth-helpers
`

Usage

$3

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

$3

The package currently supports the following provider identifiers (OAuthProvider):
- asana
- jira
- linear
- trello
- clickup
- monday (Auth only)

$3

`typescript
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.

$3

`typescript
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

`typescript
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.

$3

`typescript
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.

`bash


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

$3

This project uses Jest for unit testing.
`bash
npm test
`

$3

To build the project for distribution:
`bash
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