Google Services Secure

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.

nelmaz@nelmaz

Install

openclaw skills install @nelmaz/google-services-secure

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:

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"

First-Time Setup Required:

bash

cd /data/.openclaw/workspace/skills/google-services-secure
./scripts/validate-setup.sh

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:

text

/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: me@example.com\r\nTo: recipient@example.com\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": "new@example.com"}],
    "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="manager@example.com"
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: me@example.com\\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

text

Error: Invalid Credentials

Solution:

Verify API key format
Check client ID and secret
Regenerate credentials in Google Cloud Console

Error: Invalid Grant

text

Error: Invalid grant

Solution:

Verify redirect URI matches
Check OAuth scopes
Ensure authorization flow is correct

Error: Rate Limit Exceeded

text

Error: User Rate Limit Exceeded

Solution:

Wait for quota to reset
Reduce request frequency
Upgrade Google Cloud quota

Error: Permission Denied

text

Error: 403 Forbidden

Solution:

Verify OAuth scopes
Check permission mode
Re-authenticate if token expired

Security Checklist

Before using this skill in production, verify:

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:

Maintain security guarantees
Include audit logging
Pass validation checks
Update documentation
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.

Google Services Secure

Install

Google Services Secure

🔒 Security First

⚠️ Before Using

Quick Start

1. Configure Environment Variables

2. Validate Setup

3. Authenticate via OAuth 2.0

4. List Gmail Messages (Read-Only)

Security Architecture

Credential Management

OAuth 2.0 Authorization Flow

Permissions System

Audit Logging

Rate Limiting

Available Services

📧 Gmail (gmail.googleapis.com)

1. List Messages

2. Get Message

3. Send Email (Requires Permission)

💾 Google Drive (drive.googleapis.com)

1. List Files

2. Upload File (Requires Permission)

3. Download File

📅 Google Calendar (calendar.googleapis.com)

1. List Events

2. Create Event (Requires Permission)

📊 Google Sheets (sheets.googleapis.com)

1. List Spreadsheets

2. Read Sheet Values

3. Update Sheet (Requires Permission)

📝 Google Docs (docs.googleapis.com)

1. List Documents

2. Get Document Content

👥 Google Contacts (people.googleapis.com)

1. List Connections

2. Create Contact (Requires Permission)

Input Validation

Email Validation

File Path Validation

Data Sanitization

Coding Use Cases

Use Case 1: Email Automation

Use Case 2: File Backup

Use Case 3: Calendar Scheduling

Security Best Practices

✅ DO

❌ DON'T

Troubleshooting

Error: Invalid Credentials

Error: Invalid Grant

Error: Rate Limit Exceeded

Error: Permission Denied

Security Checklist

OpenClaw Integration

Recommended Configuration

Enable Skill

References

Version History

License

Contributing

Support

Related skills