Skill: nelmaz/google-services-secure (version 1.0.0)

--- name: google-services-secure description: Secure Google Workspace integration (Gmail, Drive, Calendar, Sheets, Docs, Contacts, etc.) with enterprise-grade security. Features credential isolation, input validation, audit logging, rate limiting, and granular permissions. Use when working with Google APIs, sending emails, managing files, scheduling calendar events, or automating Google Workspace workflows. version: "1.0.0" metadata: author: nelson-mazonzika homepage: https://clawhub.ai/nelson-mazonzika/google-services-secure license: MIT openclaw: emoji: 🔒 requires: bins: [] env: - GOOGLE_API_KEY - GOOGLE_CLIENT_ID - GOOGLE_CLIENT_SECRET node: ">=18.0.0" security: level: enterprise features: - credential-isolation - input-validation - audit-logging - rate-limiting - granular-permissions - sandbox-support - oauth-2.0-flow - https-only - confirmation-required tested: true audit-trail: true --- # Google Services Secure ## 🔒 Security First This skill implements **enterprise-grade security** protections for Google Workspace APIs: - ✅ **Credential Isolation** - OAuth tokens and secrets never stored in config files - ✅ **Input Validation** - All emails, file IDs, and parameters sanitized - ✅ **Audit Logging** - Complete action trail with timestamps - ✅ **Rate Limiting** - Prevents abuse and DoS - ✅ **Granular Permissions** - Read-only mode by default - ✅ **Sandbox Support** - Isolated execution environment - ✅ **OAuth 2.0 Flow** - Secure authorization flow - ✅ **HTTPS Only** - Enforces encrypted connections - ✅ **Confirmation Required** - Dangerous operations need explicit approval ## ⚠️ Before Using **CRITICAL SECURITY REQUIREMENTS:** 1. **Environment Variables MUST be Set:** ```bash # NEVER store these in openclaw.json or any config file export GOOGLE_API_KEY="your-api-key" export GOOGLE_CLIENT_ID="your-client-id" export GOOGLE_CLIENT_SECRET="your-client-secret" export GOOGLE_REDIRECT_URI="http://localhost:8080/callback" ``` 2. **First-Time Setup Required:** ```bash cd /data/.openclaw/workspace/skills/google-services-secure ./scripts/validate-setup.sh ``` 3. **OAuth 2.0 Flow:** ```bash # Generate OAuth URL and authenticate ./scripts/auth-google.sh ``` ## Quick Start ### 1. Configure Environment Variables ```bash # Add to ~/.bashrc or /etc/environment export GOOGLE_API_KEY="your-api-key" export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" export GOOGLE_CLIENT_SECRET="your-client-secret" export GOOGLE_REDIRECT_URI="http://localhost:8080/callback" # Reload shell source ~/.bashrc ``` ### 2. Validate Setup ```bash cd /data/.openclaw/workspace/skills/google-services-secure ./scripts/validate-setup.sh ``` This will: - Verify environment variables are set - Validate Google API key format - Test OAuth credentials - Create audit log directory - Report any security issues ### 3. Authenticate via OAuth 2.0 ```bash cd /data/.openclaw/workspace/skills/google-services-secure ./scripts/auth-google.sh ``` This will: - Generate OAuth 2.0 authorization URL - Open browser for user consent - Capture authorization code - Exchange code for access token - Store tokens securely in memory ### 4. List Gmail Messages (Read-Only) ```bash curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" ``` ## Security Architecture ### Credential Management **❌ NEVER do this:** ```json { "env": { "GOOGLE_API_KEY": "AIza...", // ❌ INSECURE "GOOGLE_CLIENT_ID": "...apps.googleusercontent.com", // ❌ INSECURE "GOOGLE_CLIENT_SECRET": "..." // ❌ CRITICAL SECURITY ISSUE } } ``` **✅ CORRECT approach:** ```bash # Set at system level, never in files export GOOGLE_API_KEY="your-api-key" export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" export GOOGLE_CLIENT_SECRET="your-client-secret" ``` ### OAuth 2.0 Authorization Flow **Step 1: Generate Authorization URL** ```bash https://accounts.google.com/o/oauth2/v2/auth?client_id=$GOOGLE_CLIENT_ID \ &redirect_uri=$GOOGLE_REDIRECT_URI \ &response_type=code \ &scope=https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly ``` **Step 2: Exchange Code for Token** ```bash curl -X POST https://oauth2.googleapis.com/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=$GOOGLE_CLIENT_ID" \ -d "client_secret=$GOOGLE_CLIENT_SECRET" \ -d "code=$AUTHORIZATION_CODE" \ -d "redirect_uri=$GOOGLE_REDIRECT_URI" \ -d "grant_type=authorization_code" ``` ### Permissions System The skill operates in **three permission modes**: | Mode | Read | Write | Delete | Share | Risk Level | |-------|------|-------|---------|-------|-------------| | `readonly` | ✅ | ❌ | ❌ | ❌ | 🟢 LOW | | `restricted` | ✅ | ✅* | ❌ | ❌ | 🟡 MEDIUM | | `full` | ✅ | ✅ | ✅* | ✅* | 🔴 HIGH | * Requires explicit confirmation for each operation **Default mode:** `readonly` **To change mode:** ```bash export GOOGLE_PERMISSION_MODE="readonly" # Recommended for production ``` ### Audit Logging All actions are logged to: ``` /data/.openclaw/logs/google-services-audit.log ``` **Log format:** ```json { "timestamp": "2024-04-04T00:30:45.123Z", "user": "nelson", "service": "gmail", "action": "LIST_MESSAGES", "status": "success", "messageCount": 10, "durationMs": 234, "permissionMode": "readonly" } ``` ### Rate Limiting Default limits (configurable): | Service | Limit | Window | |---------|-------|---------| | Gmail API | 100 | per minute | | Drive API | 500 | per minute | | Calendar API | 100 | per minute | | Sheets API | 100 | per minute | | Contacts API | 50 | per minute | **Customize limits:** ```bash export GOOGLE_RATE_LIMIT_GMAIL="100/minute" export GOOGLE_RATE_LIMIT_DRIVE="500/minute" ``` ## Available Services ### 📧 Gmail (gmail.googleapis.com) #### 1. List Messages ```bash curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Get Message ```bash curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MESSAGE_ID" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 3. Send Email (Requires Permission) **⚠️ Confirmation required before sending** ```bash curl -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "raw": "From: [REDACTED_SECRET]\r\nTo: [REDACTED_SECRET]\r\nSubject: Test\r\n\r\nTest message body" }' ``` ### 💾 Google Drive (drive.googleapis.com) #### 1. List Files ```bash curl -s "https://www.googleapis.com/drive/v3/files?pageSize=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Upload File (Requires Permission) **⚠️ Confirmation required before uploading** ```bash curl -X POST "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -F "metadata={\"name\":\"test.txt\"};type=application/json; charset=UTF-8" \ -F "file=@test.txt" ``` #### 3. Download File ```bash curl -s "https://www.googleapis.com/drive/v3/files/$FILE_ID?alt=media" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -O downloaded_file.txt ``` ### 📅 Google Calendar (calendar.googleapis.com) #### 1. List Events ```bash curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Create Event (Requires Permission) **⚠️ Confirmation required before creating** ```bash curl -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "summary": "Meeting", "start": {"dateTime": "2024-04-04T10:00:00Z"}, "end": {"dateTime": "2024-04-04T11:00:00Z"} }' ``` ### 📊 Google Sheets (sheets.googleapis.com) #### 1. List Spreadsheets ```bash curl -s "https://sheets.googleapis.com/v4/spreadsheets" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Read Sheet Values ```bash curl -s "https://sheets.googleapis.com/v4/spreadsheets/$SPREADSHEET_ID/values/Sheet1!A1:B10" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 3. Update Sheet (Requires Permission) **⚠️ Confirmation required before updating** ```bash curl -X PUT "https://sheets.googleapis.com/v4/spreadsheets/$SPREADSHEET_ID/values/Sheet1!A1:B10" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "values": [["New Value"]] }' ``` ### 📝 Google Docs (docs.googleapis.com) #### 1. List Documents ```bash curl -s "https://www.googleapis.com/drive/v3/files?q=mimeType%3D'application/vnd.google-apps.document'" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Get Document Content ```bash curl -s "https://www.googleapis.com/drive/v3/files/$DOC_ID/export?mimeType=text/plain" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### 👥 Google Contacts (people.googleapis.com) #### 1. List Connections ```bash curl -s "https://people.googleapis.com/v1/people/me/connections?personFields=names,emailAddresses" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` #### 2. Create Contact (Requires Permission) **⚠️ Confirmation required before creating** ```bash curl -X POST "https://people.googleapis.com/v1/people:createContact" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "emailAddresses": [{"value": "[REDACTED_SECRET]"}], "names": [{"givenName": "John", "familyName": "Doe"}] }' ``` ## Input Validation ### Email Validation ```javascript function validateEmail(email) { // Must be valid email format if (!email.match(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/)) { throw new Error('Invalid email format'); } // No dangerous characters if (email.match(/<script|javascript:|onerror|onload/i)) { throw new Error('Email contains dangerous patterns'); } return email; } ``` ### File Path Validation ```javascript function validateFilePath(path) { // Prevent directory traversal if (path.includes('..') || path.includes('~')) { throw new Error('Invalid file path'); } // Validate file extension const allowedExtensions = ['.txt', '.pdf', '.doc', '.docx', '.xls', '.xlsx']; const extension = path.slice(-5); if (!allowedExtensions.includes(extension)) { throw new Error('File type not allowed'); } return path; } ``` ### Data Sanitization ```javascript function sanitizeData(data) { const sensitive = ['password', 'apiKey', 'secret', 'token', 'credential']; const sanitized = JSON.parse(JSON.stringify(data)); function clean(obj) { for (const key in obj) { if (sensitive.some(s => key.toLowerCase().includes(s))) { obj[key] = '***REDACTED***'; } else if (typeof obj[key] === 'object') { clean(obj[key]); } else if (typeof obj[key] === 'string') { // Remove potential HTML/Script tags obj[key] = obj[key].replace(/<[^>]*>/g, ''); } } } clean(sanitized); return sanitized; } ``` ## Coding Use Cases ### Use Case 1: Email Automation ```bash #!/bin/bash # Send automated email notifications EMAIL_SUBJECT="Daily Report" RECIPIENT="[REDACTED_SECRET]" MESSAGE_BODY="Daily report attached." curl -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{ \"raw\": \"From: [REDACTED_SECRET]\\r\\nTo: $RECIPIENT\\r\\nSubject: $EMAIL_SUBJECT\\r\\n\\r\\n$MESSAGE_BODY\" }" ``` ### Use Case 2: File Backup ```bash #!/bin/bash # Backup files from Drive to local storage curl -s "https://www.googleapis.com/drive/v3/files?pageSize=100" \ -H "Authorization: Bearer $ACCESS_TOKEN" | \ jq -r '.files[] | "\(.id) \t \(.name)"' | \ while read id name; do curl -s "https://www.googleapis.com/drive/v3/files/$id?alt=media" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -O "backups/$name" done ``` ### Use Case 3: Calendar Scheduling ```bash #!/bin/bash # Schedule automated calendar events EVENT_SUMMARY="Weekly Meeting" START_TIME=$(date -u +"%Y-%m-%dT%H:%M:00Z") END_TIME=$(date -u -d +1hour +"%Y-%m-%dT%H:%M:00Z") curl -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{ \"summary\": \"$EVENT_SUMMARY\", \"start\": {\"dateTime\": \"$START_TIME\"}, \"end\": {\"dateTime\": \"$END_TIME\"} }" ``` ## Security Best Practices ### ✅ DO ```bash # Set environment variables at system level export GOOGLE_API_KEY="your-api-key" export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" export GOOGLE_CLIENT_SECRET="your-client-secret" # Use readonly mode in production export GOOGLE_PERMISSION_MODE="readonly" # Review audit logs regularly tail -100 /data/.openclaw/logs/google-services-audit.log # Validate setup before use ./scripts/validate-setup.sh ``` ### ❌ DON'T ```bash # NEVER store credentials in config files { "env": { "GOOGLE_CLIENT_SECRET": "..." # ❌ CRITICAL SECURITY ISSUE } } # NEVER use HTTP (unencrypted) export GOOGLE_API_KEY="http://..." # ❌ INSECURE # NEVER share access tokens echo "$ACCESS_TOKEN" # ❌ LEAKS CREDENTIALS ``` ## Troubleshooting ### Error: Invalid Credentials ``` Error: Invalid Credentials ``` **Solution:** - Verify API key format - Check client ID and secret - Regenerate credentials in Google Cloud Console ### Error: Invalid Grant ``` Error: Invalid grant ``` **Solution:** - Verify redirect URI matches - Check OAuth scopes - Ensure authorization flow is correct ### Error: Rate Limit Exceeded ``` Error: User Rate Limit Exceeded ``` **Solution:** - Wait for quota to reset - Reduce request frequency - Upgrade Google Cloud quota ### Error: Permission Denied ``` Error: 403 Forbidden ``` **Solution:** - Verify OAuth scopes - Check permission mode - Re-authenticate if token expired ## Security Checklist Before using this skill in production, verify: - [ ] Environment variables are set at system level - [ ] No credentials stored in config files - [ ] OAuth 2.0 flow configured correctly - [ ] Permission mode is set appropriately - [ ] Audit logging is enabled and working - [ ] Rate limiting is configured - [ ] First-time setup validation passed - [ ] Sandbox mode is enabled in OpenClaw (if applicable) - [ ] Dangerous operations require confirmation - [ ] Regular audit reviews are scheduled ## OpenClaw Integration ### Recommended Configuration ```json { "agents": { "google-services": { "id": "google-services", "name": "Google Services (Secure)", "skills": ["google-services-secure"], "sandbox": "require", "tools": { "allowlist": ["curl", "read", "write"], "denylist": ["exec", "eval", "shell"] }, "maxConcurrent": 1 } } } ``` ### Enable Skill ```bash # Add skill to main agent openclaw agent add-skill main google-services-secure # Or create dedicated agent openclaw agent create google-services \ --skills google-services-secure \ --sandbox require \ --max-concurrent 1 ``` ## References - **Documentation:** `references/security.md` - Complete security guide - **Validation Script:** `scripts/validate-setup.sh` - Setup verification - **Auth Script:** `scripts/auth-google.sh` - OAuth 2.0 flow - **Gmail API:** https://developers.google.com/gmail/api/reference/rest/ - **Drive API:** https://developers.google.com/drive/api/reference/rest/v3/ - **Calendar API:** https://developers.google.com/calendar/api/v3/reference/ - **Sheets API:** https://developers.google.com/sheets/api/reference/rest/ - **Contacts API:** https://developers.google.com/people/api/rest/v1/ ## Version History - **1.0.0** (2024-04-04) - Initial secure release - OAuth 2.0 authorization flow - Credential isolation (environment variables only) - Input validation (email, file paths, sanitization) - Audit logging with complete action trail - Rate limiting to prevent abuse - Granular permissions (readonly, restricted, full) - Multi-service support (Gmail, Drive, Calendar, Sheets, Contacts) - Confirmation required for dangerous operations - HTTPS enforcement - Setup validation scripts ## License MIT License - See LICENSE.md for details ## Contributing Security is top priority. All contributions must: 1. Maintain security guarantees 2. Include audit logging 3. Pass validation checks 4. Update documentation 5. Add tests for security features ## Support - **Security Issues:** Report immediately via private channels - **Issues:** https://github.com/[your-repo]/issues - **Documentation:** `references/` directory --- **⚠️ IMPORTANT:** This skill prioritizes security over convenience. Read-only operations work immediately. Dangerous operations require explicit confirmation and appropriate permission levels. **Note:** This skill uses OAuth 2.0 flow for secure authorization. Never share your access tokens or store them in files.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)