Stateless OAuth utilities for provider integrations
npm install @pushpilot/oauth-helpers@pushpilot/oauth-helpers is a pure OAuth utility package for generating authorization URLs, exchanging codes for tokens, refreshing tokens, and validating webhook signatures.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.
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:urlVerify a sample webhook signature
npm run example:webhookAttempt 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