papercrane

A CLI tool for managing OAuth credentials for LLM integrations.

Features

• 🔐 Google OAuth 2.0 authentication using PKCE flow
• 💾 Secure credential storage in ~/.papercrane/google
• 📋 List and manage stored credentials
• 🌐 Automatic browser-based authentication flow

Installation

Local Development

npm install
chmod +x bin/papercrane.js
npm link

Global Installation

npm install -g papercrane

Setup

Before using papercrane, you need to create OAuth 2.0 credentials in the Google Cloud Console:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the APIs you want to access (e.g., Gmail API, Drive API, Calendar API)
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth client ID
6. Select Desktop app as the application type
7. Set the redirect URI to http://127.0.0.1:8080/callback
8. Save your Client ID and Client Secret

Usage

Authenticate with Google

papercrane google <scope1> [scope2] [...]

Examples:

# Authenticate for Gmail read-only access
papercrane google https://www.googleapis.com/auth/gmail.readonly

# Authenticate for multiple scopes
papercrane google https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/calendar.readonly

# Authenticate for Gmail and Drive
papercrane google https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/drive.file

The command will:

1. Prompt you for your Google OAuth Client ID and Client Secret
2. Generate PKCE credentials for secure authentication
3. Start a local server on port 8080
4. Open your browser to complete authentication
5. Store the credentials in ~/.papercrane/google/

List Stored Credentials

papercrane list

This shows all stored credentials including:

• File name and path
• Creation and expiration dates
• Token validity status
• Granted scopes
• Refresh token availability

Help

papercrane help
papercrane --help

Credential Storage

Credentials are stored as JSON files in:

~/.papercrane/google/credentials-<hash>.json

Each credential file contains:

• access_token: The OAuth access token
• refresh_token: The refresh token (if available)
• expires_in: Token lifetime in seconds
• expires_at: Absolute expiration timestamp
• scope: Granted OAuth scopes
• token_type: Token type (usually "Bearer")
• created_at: Creation timestamp

Common OAuth Scopes

Gmail

• https://www.googleapis.com/auth/gmail.readonly - Read-only access
• https://www.googleapis.com/auth/gmail.compose - Compose and send messages
• https://www.googleapis.com/auth/gmail.modify - Read, send, and modify emails

Google Drive

• https://www.googleapis.com/auth/drive.readonly - Read-only access
• https://www.googleapis.com/auth/drive.file - Per-file access
• https://www.googleapis.com/auth/drive - Full access

Google Calendar

• https://www.googleapis.com/auth/calendar.readonly - Read-only access
• https://www.googleapis.com/auth/calendar - Full access

See Google OAuth 2.0 Scopes for a complete list.

Security Considerations

• PKCE Flow: Uses Proof Key for Code Exchange for enhanced security
• Local Storage: Credentials are stored locally on your machine
• Refresh Tokens: Requested by default (access_type=offline) for long-term access
• Localhost Only: Callback server binds to 127.0.0.1 (localhost only)

Development

Project Structure

papercrane/
├── bin/
│   └── papercrane.js          # CLI entry point
├── lib/
│   ├── callback-server.js  # Local OAuth callback server
│   ├── google-auth.js      # Google OAuth flow implementation
│   ├── list-credentials.js # Credential listing
│   ├── pkce.js            # PKCE generation utilities
│   └── storage.js         # Credential storage management
├── package.json
└── README.md

Technologies

• Commander.js: CLI framework
• Axios: HTTP client for token exchange
• Chalk: Terminal styling
• Inquirer: Interactive prompts
• Open: Cross-platform browser opening

Troubleshooting

Port 8080 already in use

If port 8080 is occupied, stop any processes using it or modify the PORT constant in lib/google-auth.js.

Browser doesn't open automatically

Copy the authorization URL from the terminal and paste it into your browser manually.

Invalid client error

Ensure your Client ID and Client Secret are correct and that the redirect URI http://127.0.0.1:8080/callback is registered in your Google Cloud Console OAuth credentials.

License

MIT