handler-storage-gdrive

<CRITICAL_RULES>

1. NEVER expose OAuth tokens or client secrets in outputs or logs
2. ALWAYS validate inputs before executing operations
3. ALWAYS return structured JSON results
4. NEVER fail silently - report all errors clearly
5. ALWAYS use rclone for Google Drive operations
6. NEVER log OAuth tokens, client IDs, or secrets
7. ALWAYS check rclone is installed and configured before operations </CRITICAL_RULES>

{
  "handlers": {
    "gdrive": {
      "client_id": "${GDRIVE_CLIENT_ID}",
      "client_secret": "${GDRIVE_CLIENT_SECRET}",
      "folder_id": "root",
      "rclone_remote_name": "gdrive"
    }
  }
}

Configuration Fields:

• client_id: OAuth 2.0 Client ID from Google Cloud Console (required)
• client_secret: OAuth 2.0 Client Secret (required)
• folder_id: Google Drive folder ID to use as root (default: "root")
• rclone_remote_name: Name of rclone remote (default: "gdrive")

Security Best Practices:

• Use environment variables for OAuth credentials: ${GDRIVE_CLIENT_ID}
• Never commit OAuth secrets to version control
• Use OAuth2 for authentication (no service account needed)
• Rotate OAuth tokens via rclone config reconnect
• Limit OAuth scopes to drive.file or drive (full access)

IMPORTANT: Google Drive requires initial OAuth2 setup via rclone interactive config. See docs/oauth-setup-guide.md for detailed instructions. </CONFIGURATION>

Parameter Flow:

• Agent loads configuration and expands env vars
• Skill receives: operation + rclone remote + folder + paths
• Skill invokes script with all parameters
• Script executes rclone with Google Drive backend
• Skill returns structured JSON result </WORKFLOW>

{
  "success": true,
  "message": "Operation completed successfully",
  "url": "https://drive.google.com/file/d/FILE_ID/view",
  "size_bytes": 1024,
  "checksum": "sha256:abc123..."
}

File Upload:

{
  "success": true,
  "message": "File uploaded to Google Drive successfully",
  "url": "https://drive.google.com/file/d/1a2b3c4d5e6f7g8h9i0/view",
  "size_bytes": 2048,
  "checksum": "sha256:def456...",
  "file_id": "1a2b3c4d5e6f7g8h9i0"
}

Shareable Link:

{
  "success": true,
  "message": "Shareable link generated",
  "url": "https://drive.google.com/file/d/FILE_ID/view?usp=sharing",
  "type": "shareable"
}

<ERROR_HANDLING>

• Missing configuration: Return error with setup instructions
• rclone not installed: Return installation instructions
• rclone remote not configured: Return OAuth setup guide
• OAuth token expired: Suggest running rclone config reconnect gdrive:
• Network error: Retry up to 3 times with exponential backoff
• Folder not found: Return error with folder ID
• Permission denied: Return error with OAuth scope check
• File not found: Return clear error message
• Script execution failure: Capture stderr and return to agent </ERROR_HANDLING>

Installation:

# macOS
brew install rclone

# Linux
curl https://rclone.org/install.sh | sudo bash

# Check installation
rclone version

<OAUTH2_SETUP> Google Drive requires OAuth2 authentication setup via rclone:

Prerequisites

1. Google Cloud Project with Drive API enabled
2. OAuth 2.0 Client ID (Desktop application type)
3. rclone installed on your machine

Quick Setup

See docs/oauth-setup-guide.md for complete step-by-step instructions.

Summary:

1. Create OAuth credentials in Google Cloud Console
2. Run rclone config and create new remote
3. Select Google Drive backend
4. Provide Client ID and Client Secret
5. Complete OAuth flow in browser
6. Configure fractary-file to use the rclone remote

Token Management

OAuth tokens expire after 1 hour but rclone handles refresh automatically using the refresh token.

Manual refresh (if needed):

rclone config reconnect gdrive:

Scopes

• drive.file: Access only files created by the app (recommended)
• drive: Full access to all Drive files (use with caution)

See docs/oauth-setup-guide.md for detailed security considerations. </OAUTH2_SETUP>

<RCLONE_INTEGRATION> This handler uses rclone as the backend for Google Drive operations.

Why rclone?

• Mature, well-tested Google Drive support
• Handles OAuth2 token refresh automatically
• Supports all Drive operations we need
• Cross-platform compatibility
• Active development and support

rclone Remote Configuration: The handler expects an rclone remote configured with:

• Name: gdrive (configurable via rclone_remote_name)
• Type: drive (Google Drive backend)
• OAuth2 token stored in rclone config

Configuration Location:

• Linux/macOS: ~/.config/rclone/rclone.conf
• Windows: %USERPROFILE%\.config\rclone\rclone.conf

Verifying Setup:

# Test rclone remote
rclone lsd gdrive:

# Check configuration
rclone config show gdrive

</RCLONE_INTEGRATION>