gh-christianlouis-docuelevate/docs/BrowserExtension.md

Browser Extension Guide

The DocuElevate Browser Extension enables users to send files from their web browser directly to DocuElevate for processing.

Overview

The browser extension provides a seamless way to process files without manually downloading them first. Users can send file URLs with a single click, and DocuElevate will download and process the files automatically.

Features

Core Functionality

• One-Click File Sending: Send file URLs from the browser to DocuElevate
• Context Menu Integration: Right-click on links or pages to send them
• Popup Interface: Simple configuration and file submission UI
• Status Notifications: Immediate feedback on submission success or failure

Security Features

• Minimal Permissions: Only requests necessary browser permissions
• Secure Storage: Configuration stored locally in browser extension storage
• Direct Communication: All requests go directly to your DocuElevate server
• Session-Based Auth: Supports DocuElevate authentication via session cookies

Cross-Browser Support

The extension is compatible with:

• Google Chrome
• Microsoft Edge
• Chromium-based browsers (Brave, Opera, etc.)
• Mozilla Firefox (with minor adjustments)

Installation

For End Users

See the Browser Extension README for detailed installation instructions.

Quick steps:

1. Load the extension from the browser-extension folder
2. Configure your DocuElevate server URL
3. Optionally add authentication (session cookie)
4. Start sending files!

For Administrators

Prerequisites

• DocuElevate server running with URL upload API enabled
• Server accessible from users' browsers (not blocked by firewall/CORS)
• Optional: Authentication configured if required

Deployment Options

Option 1: Direct Distribution

• Share the browser-extension folder with users
• Users load it as an unpacked extension

Option 2: Internal Extension Store

• Package the extension as a .zip file
• Distribute via internal Chrome Web Store or Firefox Add-ons for Enterprise

Option 3: Public Store (requires additional steps)

• Submit to Chrome Web Store
• Submit to Firefox Add-ons

Configuration

Extension Settings

Users need to configure two settings:

1. DocuElevate Server URL (required)

   • Format: https://docuelevate.example.com
   • Must be accessible from user's browser
   • Should not include trailing slashes or API paths

2. Session Cookie (optional, if auth enabled)

   • Format: session=cookie_value_here
   • Obtained by logging into DocuElevate and copying session cookie
   • Expires when the session expires (users need to update it)

Server Configuration

No server-side configuration is required. The extension uses the existing URL upload API endpoint:

POST /api/process-url

Ensure this endpoint is:

• Accessible from users' browsers
• Not blocked by CORS policies (if different domain)
• Properly secured with authentication if needed

Usage

Sending Files via Popup

1. Click the DocuElevate extension icon
2. The current page URL is displayed
3. Optionally enter a custom filename
4. Click "Send to DocuElevate"
5. Status message shows success or error

Sending Files via Context Menu

1. Right-click on any link or the current page
2. Select "Send to DocuElevate"
3. A notification appears with the result

Supported URLs

The extension can send any URL, but DocuElevate will only process:

Document URLs:

• PDFs: https://example.com/document.pdf
• Office: https://example.com/report.docx
• Spreadsheets: https://example.com/data.xlsx
• Text files: https://example.com/notes.txt

Image URLs:

• https://example.com/image.jpg
• https://example.com/scan.png
• https://example.com/diagram.svg

How It Works

Architecture

┌─────────────┐         ┌──────────────────┐         ┌──────────────┐
│   Browser   │         │  Browser Ext.    │         │ DocuElevate  │
│     Tab     │────────▶│  (popup.js)      │────────▶│   Server     │
│             │  URL    │                  │  API    │              │
└─────────────┘         └──────────────────┘ Request └──────────────┘
                               │
                               │ Stores config in
                               ▼
                        ┌──────────────────┐
                        │ Browser Storage  │
                        │ (chrome.storage) │
                        └──────────────────┘

Data Flow

1. User initiates send: Via popup or context menu
2. Extension gets current URL: From active tab
3. Extension loads config: Server URL and session cookie from storage
4. API request sent: POST to /api/process-url with URL and optional filename
5. DocuElevate processes:
   • Downloads file from URL
   • Validates file type and size
   • Enqueues for processing (OCR, metadata extraction)
6. Response returned: Task ID and status
7. User notified: Success or error message displayed

Security Flow

The extension implements several security measures:

1. No direct file access: Extension only sends URLs, not file contents
2. User-controlled config: Server URL and auth stored per-user
3. HTTPS recommended: Encourages secure communication
4. Minimal permissions: Only requests necessary browser APIs
5. Server-side validation: DocuElevate validates all URLs (SSRF protection)

Technical Details

Extension Structure

manifest.json: Extension metadata and configuration

• Manifest v3 format (latest standard)
• Minimal permissions requested
• Compatible with Chrome, Edge, and Firefox

popup/: User interface files

• popup.html: Extension popup interface
• popup.css: Styling with modern UI design
• popup.js: Configuration and file sending logic

scripts/: Background functionality

• background.js: Service worker for context menu and notifications
• content.js: Content script for page interaction (minimal)

icons/: Extension icons in multiple sizes

API Integration

The extension communicates with DocuElevate via the URL upload API:

Request Format:

POST /api/process-url
Content-Type: application/json
Cookie: session=<session_value>  // if auth enabled

{
  "url": "https://example.com/file.pdf",
  "filename": "optional-custom-name.pdf"  // optional
}

Response Format:

{
  "task_id": "abc-123-def",
  "status": "queued",
  "message": "File downloaded from URL and queued for processing",
  "filename": "file.pdf",
  "size": 1024
}

Error Response:

{
  "detail": "Error message explaining what went wrong"
}

Browser Permissions

The extension requests these permissions:

• activeTab: Get URL of current tab
• storage: Save configuration (server URL, session cookie)
• contextMenus: Add "Send to DocuElevate" to right-click menu
• notifications: Show success/error notifications

All permissions are used only for stated purposes. No data is collected or transmitted to third parties.

Troubleshooting

Common Issues

"Failed to connect to DocuElevate server"

• Check server URL is correct and accessible
• Verify server is running
• Check firewall/network settings
• Test API directly: curl https://your-server/api/process-url

"Authentication required" (401 error)

• User needs to add session cookie
• Session may have expired (log in again)
• Check AUTH_ENABLED setting in DocuElevate

"Unsupported file type" (400 error)

• URL must point to a supported file type
• Check file extension and Content-Type header
• See DocuElevate supported file types

"File too large" (413 error)

• File exceeds MAX_UPLOAD_SIZE setting
• Contact admin to increase limit or use smaller file

Extension not appearing

• Ensure developer mode is enabled
• Reload the extension
• Check browser console for errors

Debug Mode

To debug the extension:

1. Open Extension Console:

   • Chrome: Right-click extension icon → "Inspect popup"
   • Or go to chrome://extensions/ → Click "Inspect views: service worker"

2. Check Console Logs:

   • Look for error messages
   • Verify API requests are being sent
   • Check response status codes

3. Test API Directly:

   curl -X POST https://your-server/api/process-url \
     -H "Content-Type: application/json" \
     -H "Cookie: session=your_session" \
     -d '{"url": "https://example.com/test.pdf"}'
   

Best Practices

For Users

• Keep your session cookie secure and don't share it
• Verify the DocuElevate server URL is correct before saving
• Only send files from trusted sources
• Check file size limits before sending large files

For Administrators

• Configure HTTPS for production servers
• Set appropriate MAX_UPLOAD_SIZE limits
• Enable authentication for security
• Monitor API usage and set rate limits if needed
• Provide clear documentation to users on getting session cookies

Future Enhancements

Possible future improvements:

• OAuth2 authentication instead of session cookies
  • Current session cookie approach has limitations:
    • Session cookies expire and need manual refresh
    • Users must manually copy cookie from browser DevTools
    • No automatic token refresh mechanism
  • OAuth2 would provide:
    • Automatic token refresh
    • Better security with short-lived access tokens
    • Easier user experience (login flow instead of cookie copying)
• File preview before sending
• Batch processing multiple URLs
• Progress indication for large files
• History of sent files
• Custom processing options (OCR language, metadata fields, etc.)

Session Cookie Security Best Practices

For users of the current implementation:

1. Keep session cookies secure: Never share your session cookie value
2. Refresh regularly: Session cookies expire; update the extension when you log in again
3. Use HTTPS: Always use HTTPS for your DocuElevate server
4. Clear on logout: Remove the session cookie from extension when logging out
5. Private browsing: Session cookies from private/incognito windows have shorter lifetimes

Related Documentation

• DocuElevate API Documentation
• DocuElevate Configuration Guide
• DocuElevate Security Guide
• Browser Extension README

Support

For issues or questions:

• Check the troubleshooting section above
• Review the main documentation
• Open an issue on GitHub