@bernierllc/dropbox-oauth

OAuth 2.0 authentication and token management for Dropbox.

Features

- OAuth 2.0 authorization URL generation with PKCE
- Authorization code exchange for access tokens
- Automatic token refresh with refresh tokens
- Token validation and expiration checking
- Secure credential storage interfaces
- Multi-user token management

Installation

``bash
npm install @bernierllc/dropbox-oauth
`

Usage

$3

`typescript
import { DropboxOAuth } from '@bernierllc/dropbox-oauth';

// Create auth instance
const dropboxAuth = new DropboxOAuth({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
redirectUri: 'https://your-app.com/oauth/dropbox/callback'
});

// Step 1: Generate authorization URL
const { url, state } = dropboxAuth.getAuthorizationUrl();
// Store state in session for CSRF protection
// Redirect user to url

// Step 2: Exchange authorization code for tokens
const tokens = await dropboxAuth.exchangeCodeForTokens(code, state);
console.log('Access token:', tokens.accessToken);
console.log('Refresh token:', tokens.refreshToken);
`

$3

`typescript
// Manually refresh token
const newTokens = await dropboxAuth.refreshAccessToken(refreshToken);

// Or use automatic refresh with storage
const storage: TokenStorage = {
async store(key, tokens) {
// Store tokens in your database
await db.saveTokens(key, tokens);
},
async retrieve(key) {
// Retrieve tokens from your database
return await db.getTokens(key);
},
async delete(key) {
// Delete tokens from your database
await db.deleteTokens(key);
}
};

const authWithStorage = new DropboxOAuth(config, storage);

// Automatically refreshes if token is expired
const validToken = await authWithStorage.getValidToken('user-123');
`

$3

`typescript
const isValid = await dropboxAuth.validateToken(accessToken);
if (!isValid) {
console.log('Token is invalid or expired');
}
`

API

$3

#### Constructor

`typescript
constructor(config: DropboxOAuthConfig, storage?: TokenStorage)
`

- config.clientId - Dropbox app client ID
- config.clientSecret - Dropbox app client secret
- config.redirectUri - OAuth redirect URI
- config.logger - (Optional) Custom logger instance
- storage - (Optional) Token storage implementation

#### Methods

##### getAuthorizationUrl(state?: string, scopes?: string[]): { url: string; state: string }

Generate OAuth authorization URL with PKCE.

##### exchangeCodeForTokens(code: string, state: string): Promise

Exchange authorization code for access and refresh tokens.

##### refreshAccessToken(refreshToken: string): Promise

Refresh access token using refresh token.

##### validateToken(accessToken: string): Promise

Validate access token against Dropbox API.

##### getValidToken(storageKey: string): Promise

Get a valid access token, automatically refreshing if expired (requires storage).

##### storeTokens(key: string, tokens: DropboxOAuthTokens): Promise

Store tokens (requires storage).

##### revokeTokens(storageKey: string): Promise

Revoke and delete tokens (requires storage).

$3

`typescript
interface TokenStorage {
store(key: string, tokens: DropboxOAuthTokens): Promise;
retrieve(key: string): Promise;
delete(key: string): Promise;
}
`

Implement this interface to provide persistent token storage.

Token Expiration

Tokens are automatically refreshed when:
- Less than 5 minutes remaining before expiration
- getValidToken() is called with valid refresh token

Error Handling

`typescript
try {
const tokens = await dropboxAuth.exchangeCodeForTokens(code, state);
} catch (error) {
console.error('OAuth failed:', error.message);
}
`

All methods throw descriptive errors on failure.

Integration

$3

This package uses @bernierllc/logger` for structured logging. The logger is optional and will use a no-op logger if not provided.

License

Copyright (c) 2025 Bernier LLC. See LICENSE file for details.